Claude Codeによるスペック駆動開発

問題: AnthropicのRLエンジニアリングチーム自身による調査によると、詳細なガイダンスなしに小〜中規模のPRに対するClaude Codeの初回成功率は約3分の1です。3分の2のケースで、要件を見落とすか、スコープを広すぎて解釈するか、誤った実装パスを選択します。修正方法はセッション途中でのプロンプト追加ではありません。セッション開始前にスペックを書くことです。

数学は残酷です。Claude Codeが単一の決定で正しい判断を下す確率が80%だとします。典型的な機能には20の決定が含まれます。ガイダンスなしで20すべてを正しく行う確率は0.8の20乗、つまり約1%です。レビュー済みのスペックは、すでに判断を下しているため各決定を確実性に近づけます。スペックはClaude Codeをガイドするのではありません。Claude Codeが行うべきでない決定を取り除くのです。

4フェーズパターン

スペック駆動開発（SDD）は4つのフェーズで実行されます。要件、設計、タスク、そして実行です。最初の3つは1つのセッションで行います。4番目は新しいセッションで行います。

要件はユーザーの視点から機能が何をしなければならないかを捉えます。ユーザーストーリー、受け入れ基準、エッジケース。方法ではなく、内容です。

設計はアーキテクチャを捉えます。データモデル、APIコントラクト、変更するファイル、そのままにするファイル、この機能のための技術スタックの決定です。

タスクは明示的な依存関係を持つ順序付きの実装計画です。ステップ3はステップ2が完了するまで開始できません。この順序はClaude Codeがツール呼び出しチェーンの深みにある場合に重要です。

実行は完全に別のセッションで行います。これはオプションではありません。

新しいセッションが重要な理由

Claude Codeは同じセッション内で自分の計画に執着します。すでに要件と設計について推論しているため、書かれたスペックを文字通り読むのではなく、暗黙的にそれらの前提を持ち越します。新しいセッションは、Claude Codeが新しいエンジニアのようにスペックを読むことを強制します。先頭から、文字通りに。

このコミュニティのコンセンサスは満場一致です。Amazon KiroのSpec駆動IDEを研究した後にこのアプローチを形式化したclaude-code-spec-workflowパッケージ（3,700以上のスター、258フォーク）の作者Pimzinoは、セッションの分割を交渉の余地のないものとして説明しています。スペックセッションは要件の深い推論にClaude Opusを使用します。実装セッションは明確な計画の実行にClaude Sonnetを使用します。異なる仕事、異なるモデル、異なるセッションです。

Anthropic推奨のインタビューワークフロー

Anthropicの公式ドキュメントは、良いスペックを作成する最も速い方法を説明しています。インタビューモードです。新しいセッションを開始して実行します。

I want to build [brief description]. Interview me in detail using 
the AskUserQuestion tool.

Ask about technical implementation, UI/UX, edge cases, concerns, 
and tradeoffs. Don't ask obvious questions, dig into the hard parts 
I might not have considered.

Keep interviewing until we've covered everything, then write a 
complete spec to SPEC.md.

Claude Codeは実装、UX、エッジケース、トレードオフをカバーするまで質問します。満足したら、スペックをSPEC.mdに書きます。そのセッションを閉じます。次のセッションでスペックを開いてビルドします。

そのハンドオフに価値の大半があります。

フォルダ構造

小さな機能やソロプロジェクトには、単一のSPEC.mdで十分です。複数の動くパーツを持つ大きな機能では、コミュニティは名前付きフォルダ内の3つのファイルに落ち着きました。

.claude/
├── commands/       # 14 slash commands
├── steering/       # product.md, tech.md, structure.md
├── specs/
│   └── {feature-name}/
│       ├── requirements.md
│       ├── design.md
│       └── tasks.md
├── bugs/           # bug fix workflows
└── agents/

steering/フォルダはセッションをまたいでプロジェクトメモリとして機能します。product.mdはビジョンを保持します。tech.mdはスタックの決定を保持します。structure.mdはファイル規約を保持します。これら3つのファイルを開いたセッションは、確立するのに何十ものやり取りが必要だったコンテキストから始まります。

Pimzinoの完全なスキャフォールドを1つのコマンドでインストールできます。

npx @pimzino/claude-code-spec-workflow

テスト修正ルール

スペックなしでは、Claude Codeにはグリーンなテストスイートへの2つのパスがあります。壊れたコードを修正するか、失敗しているテストを変更して誤った動作を期待するようにするかです。より簡単なパスを選ぶことがあります。これはバグではありません。それに対する制約がない場合の合理的なローカル最適化です。

制約はSPEC.mdまたはCLAUDE.mdに記載します。

## During Testing

**IMPORTANT!** When you find a failure during testing, **NEVER** ignore or remove 
the test to bypass the failure.

**ALWAYS** identify the root cause first.

If the root cause is in the *application's implementation*, then fix the application.
If the root cause is because the *test* was incorrectly made, then fix the test.

これは小さな追加です。ガイダンスなしのセッションで最も一般的な失敗モードの1つを閉じます。

自己一貫性のブラインドスポット

Claude OpusがスペックをWriteするとき、自分のギャップを見ることができません。要件を生成した推論がまだアクティブであるため、考慮されなかった省略はレビュー中も考慮されません。

別のモデル（GPTまたはCodex）を使用してClaude生成のスペックを対立的にレビューすると、ほぼすべてのドキュメントで主要な問題が浮かび上がります。機能するパターンは2つの別々のエージェントで、それぞれが明示的にギャップ、欠けているエッジケース、前提の矛盾を見つけるようにタスクを与えられます。1つは欠けている要件を探します。もう1つはユーザーに対して表面化されることなく設計に組み込まれた実装の前提を探します。両方が実装開始前に実行されます。

生きたドキュメントの問題

スペックがコードと同期しなくなった瞬間、利益のほとんどが消えます。その後のセッションは、文書化されていない変更をサイレントに元に戻したり、古い設計に基づいてスコープを解釈したりする可能性があります。

修正はSevak Avakiansによるもので、Anthropicの内部チームが実践していることと一致します。タスク計画の最後のステップはドキュメントの更新であるべきです。各セッションの終わりに完了した作業を要約してCLAUDE.mdの改善点を提案するよう Claude Code に依頼してください。AnthropicのData Scienceチームはルーティンなリファクタリングで2〜4倍の時間節約を報告しています。Security Engineeringチームはインフラのデバッグを10〜15分から5分に短縮しました。Product Devチームは、VimモードImplementationの70%が自律的に完了されるのを見ました。いずれのケースでも、セッション開始時の良いコンテキストが変数でした。

セッション終了時のドキュメント作成はオーバーヘッドではありません。最初のビルドの後もスペックを有用に保つ方法です。

失敗モード

実際にSDDを壊す6つのパターン。

広すぎるスコープ。「ユーザー管理システムを構築する」と言っても、どのユーザー、どのアクション、どの権限かを定義しないと、Claude Codeは最大限に解釈します。コンテキストウィンドウは求めていなかった作業で埋まります。

**古いスペック。**誰かがスペックを更新せずに直接変更をプロンプトします。次のセッションはスペックを読み、その変更をサイレントに元に戻します。

**キッチンシンク。**1つのスペックに2つの無関係な機能。Claude Codeはそれらの間でクロスコンタミネーションを導入します。スペックは1つの一貫した作業単位に保ちましょう。

**コンテキストのドリフト。**コンテキストウィンドウ内のスペックは、会話が15〜20のツール呼び出しを超えて成長すると事実上「失われ」ます。実装のための新しいセッションがこれを防ぎます。

**思考の代わりにLLM生成のスペック。**ETHチューリッヒの研究では、LLM生成のエージェントファイルがパフォーマンスを低下させながら20%多くのトークンを消費することが分かりました。人間が書いたスペックは4%助けになりました。スペックは人間がそれをレビューして実際の決定を下した場合にのみ機能します。ゴム印スタンプされたスペックはノイズです。

**セッションブリード。**同じセッションでスペック作成と実装を実行する。執着の問題が再び現れます。スペックは制約ではなく提案になります。

どのパターンをいつ使うか

3つのオプションがプロジェクトの規模のフルレンジをカバーします。

アーキテクチャ決定記録はdocs/adr/に連番のプレフィックスをつけて保存します。決定1件につき1ファイル。何を決定したか、どのような代替案を検討したか、なぜこのオプションが選ばれたかを記録します。これらはスペックファイルではありません。チャット履歴に消えてしまうはずの選択の永続的な記録です。

ソロプロジェクトのほとんどの機能では、リポジトリルートのSPEC.mdで十分です。データベースレイヤー、APIコントラクト、UIコンポーネントを同じビルドで触れる機能では3ファイル構造を選択します。選択がアーキテクチャ的で重要な場合はADRを選択します。イベントキューの選択、認証戦略、キャッシュレイヤー、APIバージョニングスキームなどです。

これが変えること

ガイダンスなしでの33%の初回成功率はモデルの限界ではありません。Claude Codeが制約なしでナビゲートする決定空間の大きさを反映しています。スペックはClaude Codeをよりスマートにするのではありません。問題を小さくします。あなたが20の決定を事前に行います。Claude Codeはすでに決定が落ち着いているプランに対して実行します。

スペックを先に。新しいセッション。生きたドキュメント。それがパターンです。

よくある質問

Claude Codeによるスペック駆動開発とは何ですか?

スペック駆動開発は4フェーズのワークフローで、Claude Codeがコードの1行を書く前に要件、設計、順序付きタスクリストを書きます。スペックはClaude Codeが自分で行っていたはずの約20の決定を取り除きます。あなたが事前に決定します。Claude Codeはすでに決定が落ち着いているプランに対して実行します。

Claude Codeのスペックはどのように書きますか?

新しいセッションを開き、実装、UX、エッジケース、トレードオフをカバーするまでAskUserToolを使用してインタビューするようClaude Codeに依頼します。インタビューが終わったら、出力をSPEC.mdに書くよう依頼します。そのセッションを閉じます。次のセッションでスペックを開いてビルドします。セッション間のハンドオフに価値の大半があります。

スペックを書いた後に新しいセッションを開始すべき理由は何ですか?

Claude Codeはスペック作成セッションからの推論を暗黙の前提として持ち越します。スペックを文字通りに読むのをやめ、以前の会話からの記憶からギャップを埋め始めます。新しいセッションはClaude Codeが新しいエンジニアのようにスペックを読むことを強制します。先頭から、一語一語、以前の会話からの継承されたコンテキストなしに。

Claude Codeのスペックファイルには何を書きますか?

最小限のスペックには3つの部分があります。要件（機能が何をしなければならないか、ユーザーストーリーと受け入れ基準として書かれたもの）、設計（データモデル、APIコントラクト、変更するファイル）、タスク（各ステップがその依存関係をリストアップした順序付き実装計画）です。小さな機能には単一のSPEC.mdが機能します。大きな機能は.claude/specs/の名前付きフォルダ内の3つの別々のファイルを使用します。

スペック駆動開発とバイブコーディングの違いは何ですか?

バイブコーディングはClaude Codeを反復的にプロンプトし、会話の流れに乗ることを意味します。探索には速いですが、規模では予測不可能です。スペック駆動開発はコードが実行される前に意思決定を書面による文書に前倒しします。スペックは小さな前払い時間を、作り直し、スコープのドリフト、セッション間のコンテキスト損失の大幅な削減と交換します。

スペック駆動開発のテスト修正ルールとは何ですか?

書面による制約なしに、Claude Codeは時々コードを修正する代わりにテストを変更することで失敗しているテストを通過させます。テスト修正ルールはSPEC.mdまたはCLAUDE.mdに記載します。まず根本原因を見つけ、アプリケーションが間違っている場合はアプリケーションを修正し、テスト自体が誤って書かれている場合にのみテストを修正します。このルール1つでガイダンスなしのセッションで最も一般的な失敗モードの1つを閉じます。