コーディングエージェントは機能を素早く実装できますが、速く作れるからといって、製品のあるべき姿が分かるわけではありません。仕様駆動開発（SDD）では、エージェントがコードを変更する前に、開発者の意図、制約、受け入れ基準を文書化します。実装はエージェントが担い、開発者はアーキテクチャの主導権を保ち、成果物が完成したかどうかを判断します。
プロンプトを追加しても問題が解決しない理由
「バイブコーディング」とも呼ばれる、その場限りのプロンプトによる開発は、使い捨ての小さな作業なら十分な場合があります。しかし、多くのファイルにまたがって一貫した設計判断が必要なプロジェクトでは、信頼性が下がります。ボタンを作るよう依頼し、出来上がったものが大きすぎると指摘すれば、そのボタンは改善されるかもしれません。それでも、アプリケーションのほかの部分にも通用する継続的なルールは定まりません。
修正のやり取りを重ねると、エージェントが一度に利用できる情報量の上限であるコンテキストウィンドウも、会話履歴で埋まっていきます。履歴が増えるほど、プロジェクト当初の意図を把握し直すことが難しくなります。コーディングエージェントはファイルを調べ、コマンドを実行し、ワークスペース全体を変更できるため、曖昧な指示の影響は一つの返答にとどまりません。
▲ 場当たり的な指示と構造化された仕様
仕様書は、そうした判断をより安定して残せる場所になります。機能が何をすべきか、なぜ必要かを明記しつつ、適切な実装上の選択はエージェントに委ねます。技術上の制約を短く修正するだけで、数百行に及ぶコードが変わることもあります。だからこそ、実装前にその制約を確認することが特に重要です。
プロジェクトの憲章を定める
まず、バージョン管理された/specsディレクトリに3つのMarkdownファイルを用意します。これらを合わせたものがプロジェクトの憲章となり、要件の変化に応じて開発者が意図的に見直せる共通の基準になります。
▲ プロジェクト憲章の3文書
mission.mdには、製品の目的、対象ユーザー、想定する動作を定義します。tech-stack.mdには、採用する技術とアーキテクチャ上の制約を記録します。roadmap.mdでは、作業を順序立てたフェーズに分けます。独立してリリースできる機能を1〜3個含む小さなフェーズのほうが、広範な依頼を一度に出すより確認しやすくなります。
実例では、働きすぎのAIエージェントを対象にした、風刺的な診療所アプリケーションを題材にしました。当初の技術選択には、TypeScript、サーバー用のHono、データ保存用のSQLiteが含まれていました。こうした選択はエージェントとの会話だけでなく、プロジェクト文書にも残す必要があります。開発者は生成されたファイルをGitの差分として確認し、機能の開発に入る前にコミットしました。
エージェントに対象範囲や技術選択について体系的な質問をさせ、憲章の下書きを手伝わせることもできます。それでも、重要な判断は開発者が下さなければなりません。目的はすべての変数名を指定することではなく、使命、境界、依存関係、基準を明確にすることです。
機能ごとに3段階を踏む
ロードマップの各フェーズは、途切れないチャットではなく、管理された一連の工程として扱います。要件、作業計画、確認項目を別々のファイルに分け、次へ進む前に各段階を確認します。
- 仕様策定。 機能ブランチを作成し、
requirements.md、plan.md、validation.mdを記述します。要件には機能とその範囲を、計画には作業の順序を、検証ファイルには結果の判定方法を定めます。ファイルを書く前に、未決定の点をエージェントに確認させます。 - 実装。 機能の仕様を確認してコミットした後、エージェントに計画を実行させます。単純なひな型作成なら、まとめて実行するのが適している場合があります。データベースのマイグレーションのような慎重さを要する変更は、作業を小さな単位に分け、より注意深く確認する必要があります。
- 検証。 計画したチェックを実行し、コードの差分を調べ、自分でも動作を試します。エージェントからテストが通ったと報告されても、人によるレビューの代わりにはなりません。受け入れた実装と仕様に違いがあれば仕様を更新し、その後コミットして機能ブランチをマージします。
最初のサーバーフェーズでは、依存関係、開発用スクリプト、ホームページ、動作確認が計画に含まれていました。エージェントはTypeScriptのチェックを実行し、ローカルのエンドポイントをテストしました。開発者も表示されたページを確認しました。レビュー中、開発者はエディターのリファクタリング機能を使い、ページの各セクションを別々のコンポーネントファイルに移しました。この手作業による改善で実装と計画書に食い違いが生じたため、ブランチをマージする前に機能の文書を更新しました。
この最後の作業は重要です。コードだけが変わり、仕様書が更新されなければ、次に起動したエージェントは古いプロジェクトの説明に従うかもしれません。Claude Codeでは、新しい機能フェーズに入る前に/clearで会話履歴を消すと、古いチャットの文脈ではなく、コミット済みのプロジェクトファイルを基に作業を始めやすくなります。
フェーズ間で計画を見直し、大きな変更は二度確認する
憲章は基準であって、変更を禁じるものではありません。機能ブランチの間に立ち止まり、現在のプロジェクトに何が必要かを見直します。診療所アプリの例では、計画を見直すフェーズでVitestによるテストを追加しました。これとは別に、関係者から最新情報が届いたという想定で、アプリケーションのユーザーの40％がモバイルブラウザーからアクセスしていることが示されたため、モバイルファーストのスタイル要件とビューポートの変更を加えました。こうした判断を技術標準に記録することで、後続の機能にも反映できました。
レビューにかける労力は、変更の規模に合わせるべきです。ある比較的大きな機能では、3つのエージェントが並行してTypeScript、データベースのアーキテクチャ、HTMLのアクセシビリティを確認しました。指摘には、SQLiteの外部キー制約を有効にする設定の欠落や、不要な実行時依存関係が含まれていました。エージェントは問題を修正しましたが、そのレビューが開発者の判断に取って代わるわけではありません。
その後の開発では、ロードマップの複数フェーズを10個のタスクからなる実用最小限の製品（MVP）の計画にまとめました。動作するアプリケーションは意図した予約フローに対応していましたが、要件に立ち返って照合すると、抜けが見つかりました。無効な予約入力に対し、仕様ではHTTP 400を返すべきところ、実際にはHTTP 200を返していたのです。画面が動くことだけでは、すべての受け入れ基準を満たした証明にはなりません。実装を仕様と改めて照らし合わせることで、最初の確認で見逃した点が明らかになりました。
既存のコードにも同じ方法を使う
新しいリポジトリは必要ありません。仕様書のない既存プロジェクトでは、エージェントにコード、パッケージ設定、README、タスクリストを調べさせます。そこから作成したミッション、技術構成、ロードマップの各ファイルを、アプリケーションの実際の動作と照らし合わせてからコミットします。その後は、次の保守作業にも同じ仕様策定・実装・検証のサイクルを適用できます。
再利用可能なAgent Skillsには、機能ブランチの準備や仕様ファイルの下書き作成といった反復作業をまとめられます。スキルはコマンドを実行する場合があるため、インストール前にコードを確認してください。プロジェクトの判断をMarkdownとGitに残しておけば、Claude CodeやOpenAI Codexなど、異なるエージェント間でも作業の進め方を引き継ぎやすくなります。チャット履歴だけをプロジェクトの記録にする必要はありません。
小さく始め、人によるレビューを続ける
憲章となる3つのファイルを作り、対象を絞ったロードマップのフェーズを一つ選びます。エージェントにコードを書かせる前に、要件、計画、検証基準を定めます。出来上がった差分と動作を確認し、受け入れた変更に文書を合わせ、次のフェーズに入る前に計画を見直します。SDDの実用的な価値は、エージェントが絶対に間違えなくなることではありません。開発者が作業を指示し、見落としを発見するための文書化された基準を持てることです。