仕様駆動でAIエージェントに実装させる — SPEC.md・依頼テンプレート・よくある失敗5つ

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

理由は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 は変更履歴ではなく、判断の理由を非同期で共有するための制御面です。

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

依頼テンプレート: SPEC.md を書かない変更の頼み方

前述の判断基準で「直接実装させる」側に入る変更でも、依頼文に書く項目は SPEC.md とほぼ同じです。ゴールと非ゴールは「変更してよい範囲 / 変更してはいけない範囲」に、完了の定義は「完了条件 / 検証方法」に当たります。「この機能を作って」ではなく、「どのファイルを見て、何を変えて、何を変えず、どうなったら完了か」まで指定すると、手戻りが起きにくくなります。

悪い指示と良い指示

ログイン機能を直して

この指示では、何が壊れているのか、どの画面の話か、期待する動作は何か、変更してよい範囲はどこか、テストはどうすればよいか、UI や認証ロジックを変えてよいのかが分かりません。AIエージェントは曖昧な部分を推測します。推測が当たれば成功しますが、外れれば余計な変更が増えます。

目的:
ログイン画面で、正しいメールアドレスとパスワードを入力してもログインできない問題を修正してください。

背景:
現在、/login でログインボタンを押すと 401 が返ります。
API側ではなく、フロントエンド側の送信パラメータ名が間違っている可能性があります。

変更してよい範囲:
- src/pages/login.tsx
- src/components/LoginForm.tsx
- 関連するテストファイル

変更してはいけない範囲:
- 認証APIの仕様変更
- DBスキーマ変更
- デザインの大幅変更
- 新しいライブラリ追加

期待する動作:
正しい認証情報を入力した場合、ログイン成功後に /dashboard に遷移すること。
間違った認証情報の場合、既存のエラーメッセージを表示すること。

完了条件:
- 既存テストが通る
- ログインフォームのテストを追加または更新する
- 変更内容を要約する

検証方法:
npm test
npm run build

出力形式:
1. 原因
2. 変更内容
3. 実行した検証
4. 残った懸念

この指示なら、AIエージェントは迷いにくくなります。

そのまま使えるテンプレート

目的:
{何を実現したいかを一文で書く}

背景:
{なぜ必要か、現在何が起きているかを書く}

対象読者/利用者:
{この機能を誰が使うかを書く}

変更してよい範囲:
- {ファイルまたはディレクトリ}
- {関連するテスト}

変更してはいけない範囲:
- {触ってほしくないファイル}
- {変更禁止の仕様}
- {追加してほしくないライブラリ}

期待する動作:
- {期待する動作1}
- {期待する動作2}

完了条件:
- {条件1}
- {条件2}
- {条件3}

検証方法:
- {テストコマンド}
- {ビルドコマンド}
- {手動確認手順}

制約:
- UIを大きく変えない
- 新しいライブラリを追加する場合は事前に理由を説明する
- セキュリティに関わる変更は勝手に進めない

出力形式:
1. 調査結果
2. 実装方針
3. 変更内容
4. 検証結果
5. 残った懸念

変更範囲と完了条件を必ず書く

変更範囲がない依頼は危険です。「認証まわりを改善して」ではなく、次のように範囲を狭めます。

今回はログインフォームのバリデーションだけを修正してください。
認証API、DB、セッション管理、OAuth設定は変更しないでください。

変更範囲を狭くすると、意図しない変更が起きにくくなります。特に個人開発では、AIが良かれと思って大きな変更を加えた結果、自分で理解できないコードになることがあります。

完了条件がないと、AIエージェントは「コードを書いたら終わり」と判断しがちです。実務では、テスト、ビルド、説明まで含めて完了です。

完了条件:
- npm test が通る
- npm run build が通る
- 追加した挙動のテストを1つ追加する
- 変更したファイルと理由を箇条書きで説明する
- 失敗した検証がある場合は、失敗理由を隠さず報告する

実装前に「調査だけ」を依頼する

いきなり実装させるより、最初は調査だけを依頼した方が安全です。

まず、このタスクに必要な関連ファイルを調査してください。
まだファイルは変更しないでください。

出力:
- 関連ファイル一覧
- 現在の処理の流れ
- 変更が必要そうな箇所
- リスク
- 実装案

このステップを入れると、AIエージェントがどこを見ているか分かります。間違った方向に進んでいる場合も、実装前に止められます。

Claude Code / Codex でよくある5つの失敗と回避策

ここでいうAIエージェントは、Claude Code / Codex のように、ファイルを読み、編集し、コマンドを実行するコーディングエージェントです。便利な一方で、曖昧な依頼をすると曖昧なまま手を動かします。以下は、個人開発サイトの運用で Claude Code / Codex に設計相談・実装・レビュー・記事修正を任せる中で起きやすかった失敗を、5つの型に抽象化したものです。原因はモデルの能力不足より、指示設計・タスク粒度・検証設計にあります。

失敗1: コンテキストを詰め込みすぎる

「関連しそうな資料を全部渡す」「過去ログを丸ごと貼る」「巨大な仕様書を読ませる」という使い方をすると、AIエージェントは本当に重要な制約を見失いやすくなります。重要な要件を読み落とす、すでに説明した制約を破る、関係ないファイルまで編集する、といった症状が出て、会話が長くなるほど修正のたびにコストも増えます。前半で仕様と実装の会話を分けたのと同じ問題です。

コンテキストは「多いほど良い」ではなく、「作業に必要な範囲だけ」が基本です。

今回渡す情報:
- 実装対象のIssue
- 関連ファイル候補
- 変更してよい範囲
- 変更してはいけない範囲
- 検証コマンド

渡さない情報:
- 過去の雑談ログ
- 関係ない設計メモ
- 解決済みの古いエラー

迷ったら、まず前節の「調査だけ」の依頼から始めます。

失敗2: タスク粒度が大きすぎる

「決済機能を作って」「管理画面をいい感じにして」のような依頼は、AIエージェントにとって範囲が広すぎます。作業範囲が広いほど、設計判断・UI判断・DB判断・セキュリティ判断が混ざり、途中で破綻しやすくなります。

ユーザー管理機能を作ってください。

ユーザー一覧ページに、表示名で絞り込む検索フォームを追加してください。
変更対象は src/pages/users と関連テストのみです。
DBスキーマ、認証、権限ロジックは変更しないでください。

1回の依頼は、理想的には「1つの小さなPR」に収まる粒度にします。範囲が広い機能は、前半の手順で先に SPEC.md を固めます。

失敗3: テスト無しで任せる

AIエージェントは、検証手段がないと「見た目上それらしいコード」を完了扱いにしがちです。人間がレビューするまで壊れていることに気づけないため、後戻りのコストが増えます。

ステップ3で検証手段を仕様に添えたのと同じく、SPEC.md を書かない依頼でも、前節の完了条件を必ず依頼文に含めます。テストが存在しないプロジェクトでは、いきなり大きな実装を任せる前に、まず「壊れたことに気づける最小テスト」を作らせます。

失敗4: 権限境界が曖昧

AIエージェントはローカルファイルやターミナルにアクセスできるため、便利な反面、危険なファイルも触れてしまいます。特に触らせたくない領域は次のとおりです。

• .env や秘密鍵
• 本番DB接続情報
• 認証・権限・決済まわり
• デプロイ設定
• 大量ファイルの一括整形

情報としても、本番APIキー、.env の中身、秘密鍵、個人情報、本番DB接続情報、顧客データ、決済関連の秘密情報は、原則としてエージェントに渡さないでください。

依頼文ではテンプレートの「変更してよい範囲」と「変更してはいけない範囲」を両方書き、毎回守るルールはプロジェクトルートの AGENTS.md や CLAUDE.md に固定します。書き方は AGENTS.md完全ガイド にまとめています。

失敗5: コスト監視をしていない

AIエージェントは、長い会話、巨大なファイル読み込み、失敗したテストの繰り返しでコストが膨らみます。特に「同じエラーを直し続ける」状態になると、時間と料金の両方を失います。同じエラーが2回続いたら、修正を止めて原因分析に切り替えます。

同じエラーが2回続いた場合:
- それ以上コードを変更しない
- エラーの原因仮説を3つ出す
- 追加で確認すべきファイルを列挙する
- 次に試す最小変更を1つだけ提案する

API従量課金で使う場合は、月次上限・アラート・プロジェクト単位の利用ログを先に決めておきます。

依頼前チェックリスト

• 大きめの機能なら、先に SPEC.md で仕様を固めた
• 目的と背景を書いた
• 変更してよい範囲と変更してはいけない範囲を書いた
• 完了条件と検証方法を書いた
• 渡すコンテキストを作業に必要な範囲に絞り、秘密情報を除外した
• タスク粒度が「1PR分」に収まっている
• まず調査だけ依頼するか検討した
• 同じエラーが続いた時の停止ルールがある
• 従量課金なら月次コスト上限またはアラートを設定した
• 最終レビューは自分で行う前提にした

よくある質問

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

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

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

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

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

Q. SPEC.md を書かない依頼では、最低限何を書けばよいですか? 目的・背景・変更してよい範囲・変更してはいけない範囲・期待する動作・完了条件・検証方法・出力形式です。依頼がうまくいかない原因は、モデル性能より作業範囲と完了条件の曖昧さにあることが多く、ここを埋めるだけでエージェントの余計な推測が減ります。

関連記事

• Claude Code導入ガイド: Windows/macOS/WSLと初期設定
• バイブコーディング時代のADRベストプラクティス
• AGENTS.md完全ガイド — Codex・Cursor・Clineで共通のエージェント指示を書く
• Claude CodeとCodexはどっち？違い・比較・使い分けを個人開発目線で解説
• AIコーディングエージェントとは？用途・予算・チーム規模で選ぶ比較ガイド
• Claude Code hooksレシピ7本：危険コマンド阻止・.env保護・自動整形・Stopでテスト