仕様駆動開発を
Claude Codeで試してみた
題材：カットアップメーカー（マルコフ連鎖で文章を再構成するWebアプリ）
github.com/tariki/cutup-machine
導入
仕様駆動開発：先に「何を作るか」を書く
AIは仕様ドキュメントを「北極星」にして実装する。ドキュメントは役割の違う2層に分ける。
docs/
永続ドキュメント
プロジェクト全体の「何を作るか」「どう作るか」
- 頻繁には更新しない基本設計
- 正式版6種類＋下書き用の ideas/
- 設計に影響する変更があれば更新
.steering/
作業単位のドキュメント
今回の作業で「何をするか」
- 作業ごとにフォルダを新規作成
- requirements・design・tasklist の3点
- 履歴として保持（git管理外）
仕様駆動開発をClaude Codeで試してみた
02 / 14
全体構造
リポジトリに用意したものの全体像
cutup-machine/
├─ CLAUDE.md
プロジェクトの憲法
├─ .claude/
│ ├─ settings.json
スキルの事前許可
│ ├─ commands/
スラッシュコマンド ×3
│ ├─ skills/
スキル ×7
│ └─ agents/
サブエージェント ×2
├─ docs/
永続ドキュメント ×6
│ └─ ideas/
壁打ち・参考実装
└─ .steering/
作業ごとの計画（git管理外）
スラッシュコマンド
定型フローの入口
スキル
手順とテンプレート
エージェント
レビュー・検証
docs/ と .steering/
成果物としてファイルに残る
CLAUDE.md は常に読み込まれ、全体のルールを与える
仕様駆動開発をClaude Codeで試してみた
03 / 14
構成要素 ｜ CLAUDE.md
CLAUDE.md：毎回読み込まれるプロジェクトの憲法
目的
Claude Code がセッション開始時に自動で読み込むファイル。毎回同じ前提・同じ進め方で作業させるための共通ルールを集約する。
書かれていること（4つの章）
1
スペック駆動開発の基本原則
基本フロー5段階（作成→計画→実装→検証→更新）と重要ルール
2
ディレクトリ構造
docs/（ideas/ と正式版6種）と .steering/ の役割
3
開発プロセス
初回は /setup-project、以降は普通の会話か /add-feature
4
ドキュメント管理の原則
永続ドキュメントと作業単位ドキュメントの使い分け
特に効いているルール
1ファイルずつ承認
1つ作るごとに承認を得てから次へ進む
実装前に必ず調べる
docs/ を読み、Grep で既存実装を確認
作業ごとにステアリング
計画・実装・振り返りは steering スキルで
仕様駆動開発をClaude Codeで試してみた
04 / 14
構成要素 ｜ Skills
Skills①：6つのドキュメント作成スキル
① prd-writing
プロダクト要求定義書
何を・誰のために・なぜ作るか
概要、ターゲット、成功指標、機能・非機能要件、スコープ外
② functional-design
機能設計書
要件を機能としてどう実現するか
システム構成、データモデル、コンポーネント、API、エラー処理
③ architecture-design
アーキテクチャ設計書
技術スタックと構造上の判断
技術スタック、パターン、性能・セキュリティ要件、技術的制約
④ repository-structure
リポジトリ構造定義書
どのファイルをどこに置くか
ディレクトリ詳細、配置・命名規則、レイヤー間の依存ルール
⑤ development-guidelines
開発ガイドライン
書き方と進め方をチームで統一
コーディング規約、Git運用、テスト戦略、レビュー基準
⑥ glossary-creation
用語集
全ドキュメントの言葉をそろえる
ドメイン用語、技術用語、略語、状態、エラー種別
構成 SKILL.md（手順・前提条件）＋ template.md（出力の型）＋ guide.md（書き方の詳細）
工夫 ①→⑥ の順に前のドキュメントを前提に読む ／ 既存ドキュメントがあればそちらを優先
仕様駆動開発をClaude Codeで試してみた
05 / 14
構成要素 ｜ Skills ｜ .steering/[日付]-[タスク名]/
Skills②：steering スキルと3つの計画ファイル
requirements.md
今回、何を作るか
概要、背景、実装対象の機能、受け入れ条件、成功指標、スコープ外、参照ドキュメント
MODE 1 計画で作成
design.md
それを、どう実装するか
コンポーネント設計、データフロー、エラーハンドリング、テスト戦略、依存ライブラリ、実装の順序
MODE 1 計画で作成
tasklist.md
何を、どの順で片付けるか
完全完了の原則、フェーズごとのタスク（品質チェック・ドキュメント更新まで）、実装後の振り返り
MODE 1 作成
MODE 2 [x]に更新
MODE 3 振り返り
AIに手抜きさせないルール
・全タスクが [x] になるまで止めない
・「時間の都合で後回し」は禁止
・大きすぎるタスクは分割する
・スキップは技術的な理由を明記
仕様駆動開発をClaude Codeで試してみた
06 / 14
構成要素 ｜ Commands & Agents
スラッシュコマンドとサブエージェント
スラッシュコマンド（入口）
/setup-project
docs/ideas/ を読み、6つの永続ドキュメントを順に作成
/add-feature [機能名]
計画・実装・検証・振り返りまでを無停止で完走
/review-docs [パス]
doc-reviewer を起動し、改善点と総合評価を報告
サブエージェント（専門家）
doc-reviewer
完全性・一貫性・測定可能性など5観点で文書を評価
implementation-validator
スペック準拠・品質・テストなど5観点で実装を検証
/review-docs と /add-feature（ステップ6）から、Task ツールで起動される
サブエージェントのメリット
コンテキストを分離できる
長いレビューでもメインの会話を圧迫しない
第三者の目で検証できる
実装者とは別の視点。到達不能コードも発見
毎回同じ基準で評価できる
チェック項目と評価基準を定義に固定
役割ごとにモデルを選べる
model: sonnet の指定で使い分け
仕様駆動開発をClaude Codeで試してみた
07 / 14
構成要素 ｜ Agents
サブエージェントの中身：何をチェックするか
doc-reviewer
ドキュメントの品質を評価し、改善を提案
観点
主なチェック項目
完全性
必要な章と前提条件が揃っているか
明確性
用語・定義が明確で具体例があるか
一貫性
他のドキュメントと矛盾がないか
実装可能性
実装に必要な情報が揃っているか
測定可能性
成功基準が数値で測れるか
PRD・機能設計書など、文書の種類ごとの追加チェックもある
implementation-validator
実装がスペック通りかを検証
観点
主なチェック項目
スペック準拠
PRD・設計・API仕様と一致するか
コード品質
規約・命名・単一責務・重複
テスト
カバレッジ80%以上、エッジケース
セキュリティ
入力検証、機密情報を埋め込まない
パフォーマンス
要件達成、データ構造やループ
lint・型チェック・テスト・ビルドも自分で実行して確認する
共通の出力
各観点を3段階で判定し、指摘を［必須］［推奨］［提案］に分けて報告する
仕様駆動開発をClaude Codeで試してみた
08 / 14
ワークフロー
ワークフロー①：/setup-project で土台をつくる
docs/ideas/
壁打ち・参考実装
Rubyのマルコフ連鎖の実装を置いておく
prd-writing
① PRDを作成
ユーザーストーリー、受け入れ条件、成功指標まで
HUMAN
人間が承認
承認待ちになるのはここだけ
AUTO
②〜⑥ を自動作成
- 機能設計書
- アーキテクチャ設計書
- リポジトリ構造定義書
- 開発ガイドライン
- 用語集
1,762行
の設計ドキュメントが、コードを書く前にできあがる
docs/ 配下の正式版6ファイルの合計行数
仕様駆動開発をClaude Codeで試してみた
09 / 14
ワークフロー
ワークフロー②：/review-docs でドキュメントを磨く
HUMAN
コマンドを実行
/review-docs [パス]
MAIN
存在を確認
指定されたドキュメントがあるか確かめる
SUB AGENT
詳細レビュー
doc-reviewer が独立したコンテキストで評価
MAIN
要点を報告
レポートから要点だけを抜き出して伝える
報告の形式（コマンドに定義）
### 主な改善点
1. [改善点1]（優先度: 高/中/低）
2. [改善点2]（優先度: 高/中/低）
### 総合評価 [1-5]/5
### 次のアクション
使いどころ
ドキュメントを作った後や大きく直した後に、詳細なレポートがほしいとき
レビュー後
指摘の反映は、普通の会話で依頼すればよい
仕様駆動開発をClaude Codeで試してみた
10 / 14
ワークフロー ｜ 8ステップ
ワークフロー③：/add-feature で機能を積み上げる
1
準備
.steering/日付-機能名/ を作成
2
プロジェクト理解
CLAUDE.md と docs/ を読む
3
既存パターン調査
src/ を Grep して命名や作法を把握
4
計画
steering 計画モードで3ファイルを生成
5
実装ループ
tasklist を先頭から1つずつ消化
6
実装検証
implementation-validator を起動
7
自動テスト
test・lint・typecheck、失敗なら修正
8
振り返り
申し送りを記録し、必要なら docs/ を更新
tasklist.md（実物・抜粋）
## フェーズ2: ドメインレイヤー
- [x] RequestValidatorを実装する
- [x] Tokenizerを実装する
- [x] MarkovChainBuilderを実装する
- [x] MarkovGeneratorを実装する
20260913-コア機能 の実績
全8フェーズを完了 → 検証 3.8/5
→ 指摘を修正し、26テスト成功
カバレッジ 97.12%
仕様駆動開発をClaude Codeで試してみた
11 / 14
実例
実例：git履歴でたどる開発の流れ
eb948a6
9/20
開発環境と仕様駆動開発フローを構築
仕組みの準備
b6422ea
9/20
永続ドキュメント一式を作成
/setup-project
cd4af0f
9/20
MVP※（API・ドメイン・Web UI）を実装
/add-feature
f9910fa
9/21
元テキストと生成結果のリセット機能
機能追加
※ MVP（Minimum Viable Product）：利用者に価値を届けられる最小限の機能だけを備えた、最初のバージョン
f9910fa の変更ファイル
public/index.html
public/main.js
public/styles.css
docs/product-requirements.md
docs/functional-design.md
コードと一緒に
仕様も更新される
仕様駆動開発をClaude Codeで試してみた
12 / 14
まとめ
やってみて分かったこと
人は「何を・誰のために・なぜ作るか」に注力できる
「どう作るか」はフローが回す
設計書の作成から実装・検証・振り返りまで、スキルとコマンドが担う
人の判断はPRDに集まる
承認待ちになるのは /setup-project のPRDだけ
PRDが以降すべての前提になる
設計・実装・検証はPRDを起点に作られ、照らし合わされる
組織の標準に置き換えれば、製品開発にも適用できる
今回は小規模な個人プロジェクト向けに構築したが、中身を差し替えれば仕組みはそのまま使える
テンプレート・ガイド
社内の設計書テンプレート・標準
スキル・コマンドの手順
組織の開発・承認プロセス
エージェントの観点
社内のレビュー基準・品質基準
リポジトリ
github.com/tariki/cutup-machine
仕様駆動開発をClaude Codeで試してみた
13 / 14
おまけ ｜ サブカルの帝王
ウィリアム・S・バロウズとカットアップ
ウィリアム・S・バロウズ
1914–1997 ｜ アメリカの作家
ビート・ジェネレーションを代表する作家。代表作は『裸のランチ』（1959）。音楽・映画・アートなど、その後のサブカルチャーに大きな影響を与えた。
カットアップとは
既存の文章をハサミで切り刻み、並べ替えて新しい文章をつくる技法。1959年ごろ、画家ブライオン・ガイシンとパリで実践し、自身の小説に取り入れた。
切る
並べ替える
偶然の意味
今回のアプリ
カットアップメーカーは、この「切って並べ替える」を単語単位のマルコフ連鎖で再現している
仕様駆動開発をClaude Codeで試してみた
14 / 14