仕様駆動でAIエージェントに実装させる — SPEC.mdを書いて新セッションで作らせる

結論

なぜ仕様と実装を分けるのか?

理由は2つ、コンテキストの汚染と、意図の言語化です。

1つの会話の中で「どう作るか」を議論しながら同時に書かせると、検討して捨てた案・脱線・途中で変えた前提が、すべてコンテキストウィンドウに残り続けます。Claude Code の公式ベストプラクティスも、コンテキストウィンドウは速く埋まり、埋まるほど指示が無視されてミスが増える、という制約を中心課題として挙げています。設計の試行錯誤でウィンドウを使い切った状態から実装に入ると、最初に決めたはずの方針をエージェントが取りこぼしやすくなります。

もう1つは、人間側の意図がそもそも言語化されていない問題です。頭の中の「だいたいこんな感じ」のまま実装させると、エージェントは欠けた仕様を勝手に補完します。その補完がズレていれば手戻りです。仕様を先に文章へ落とすと、曖昧な部分が実装より前に表面化し、安く直せます。

ステップ1: エージェントに自分を面接させて SPEC.md を書かせる

最初の会話のゴールは、コードではなく SPEC.md という1枚の仕様書です。ここでいきなり「SPEC.md を書いて」と頼むと、欠けた前提を勝手に埋めた仕様が出てきます。代わりに、エージェントに質問役をやらせます。

これから新機能 X を作りたい。まだ実装しないでほしい。
仕様を確定させるために、不明点を一通り質問して。
特に次を埋めたい:
- ゴールと非ゴール(何を作り、何を作らないか)
- 入力 / 出力と、エラー時の挙動
- 既存コード(対象ファイルの絶対パス)との整合
- 完了の定義(どうなったら完成か / 検証方法)
質問が出尽くしたら、合意した内容を SPEC.md にまとめて。

エージェントの深掘り質問にあなたが答えていくと、頭の中で曖昧だった箇所が会話の中で1つずつ潰れます。これは公式の Common workflows が示す「まず計画を立てさせ、合意してから実装に入る」流れと同じ発想です。仕様にはコード例(関数シグネチャ、期待するレスポンス形)を1つでも入れておくと、実装段階の解釈ブレがさらに減ります。

出来上がった SPEC.md は必ず人間が読み、ゴール・非ゴール・完了の定義に過不足がないか確認します。ここを通したものだけを次のステップへ渡します。

ステップ2: 新セッション(クリーンなコンテキスト)で実装させる

SPEC.md が固まったら、実装は別の新しいセッションで始めます。理由は前のセクションで述べたとおり、設計議論で埋まっていない状態のコンテキストから実装に入るためです。

新セッションでは、渡す情報を実装に必要なものだけに絞ります。

@SPEC.md に従って実装して。
触ってよいファイル: src/feature/x.ts, src/feature/x.test.ts
触らないファイル: それ以外
まず計画を提示して、合意したら実装。完了したら SPEC.md の検証方法で確認まで。

SPEC.md をリポジトリにコミットしておけば、@SPEC.md のように参照でき、別の日・別のマシンからでも同じ前提で再開できます。会話履歴に依存しないのが利点です。Codex のような別エージェントへ実装を委譲する場合も、自己完結した SPEC.md がそのままハンドオフ契約になります。

ステップ3: 検証手段を最初から仕様に添える

SPEC.md には「どうなったら完成か」を、エージェント自身が確認できる形で書きます。これが仕様駆動の効果を最大化する核心です。

公式ベストプラクティスは、Claude が自分で結果を検証できる手段(テスト・スクリーンショット・期待出力)を最初から渡すことを「最大レバレッジ」と表現しています。検証手段がないと、あなたが唯一のフィードバックループになり、エージェントの出力が増えるほど見直し時間がリニアに膨らみます。

仕様には、たとえば次のような検証セクションを入れておきます。

## 検証方法(完了の定義)
- `npm test src/feature/x.test.ts` がすべて green
- 入力 [{id: 1}] に対し、出力が {count: 1, ok: true} になる
- 不正入力(空配列)では 400 を返す

期待する入出力を具体例で固定しておくと、エージェントは実装後に自分でテストを回して差分を埋められます。人間のレビューは「仕様どおりか」の確認に集中でき、往復が減ります。

ADR・メモリと接続して決定を残す

仕様駆動の会話で確定した「なぜこの設計にしたか」は、実装が終わると蒸発しがちです。後から別の判断に効く決定(構造・難逆性のあるもの)は、ADR として残します。ADR は変更履歴ではなく、判断の理由を非同期で共有するための制御面です。

繰り返し参照する作法(命名規約、テスト方針、対象ファイルの境界など)は、プロジェクトのメモリや指示ファイルに書いておくと、次の SPEC.md を書く会話が短くなります。仕様駆動・ADR・メモリは、いずれも「同じ議論を二度しない」ための仕組みとしてつながっています。

よくある質問

Q. なぜ仕様を固める会話と実装する会話を分けるのですか? 同じセッションで設計の試行錯誤と実装を混ぜると、放棄した案や脱線がコンテキストに残り、エージェントが古い前提のまま実装してしまうからです。仕様を SPEC.md に確定させ、新しいクリーンなセッションでそれだけを渡すと、判断のブレと手戻りが減ります。

Q. SPEC.md はどうやって書かせると質が上がりますか? いきなり書かせず、まずエージェントに「自分を面接させる」のが有効です。ゴール・非ゴール・入出力・エラー時の挙動・既存コードとの整合を質問させ、あなたが答えてから SPEC.md に落とします。曖昧な箇所が会話の中で先に潰れるので、実装段階の出戻りが少なくなります。

Q. 実装を新セッションで始める具体的な利点は? コンテキストウィンドウが設計議論で埋まっていない状態から始められることです。公式ガイドもコンテキスト管理を中心課題として挙げており、実装に必要な情報だけ(SPEC.md と対象ファイル)を載せた方が、指示が無視されにくくミスが減ります。

Q. 検証手段は最初から渡すべきですか? はい。テスト・期待出力・再現コマンドなど、エージェントが自分で結果を確認できる手段を SPEC.md に含めておくと、あなたが唯一のフィードバックループになる事態を避けられます。これは公式が「最大レバレッジ」と呼ぶ手法です。

Q. 小さな修正でも仕様駆動にすべきですか? いいえ。typo 修正やログ追加のように差分を1文で説明できる変更では、SPEC.md を書くオーバーヘッドの方が大きくなります。複数ファイルにまたがる、方針が不確か、触り慣れていないコードのいずれかに当てはまる時だけ使い分けてください。

関連記事

• Claude Code公式ベストプラクティス全訳＋実例補完
• バイブコーディング時代のADRベストプラクティス
• AIエージェント指示テンプレート
• エージェント指示とメモリ運用プレイブック