仕様駆動開発で Codex に任せる範囲の決め方と実践手順

仕様駆動開発とは何か — AI コーディング時代の「先に書く」習慣

仕様駆動開発（Specification-Driven Development、SDD）は、実装に先立って仕様を形式化するアプローチだ。テスト駆動開発（TDD）が「先にテストを書く」ことで実装を収束させるように、仕様駆動開発は「先に仕様を書く」ことで何を作るかを明確にする。もともとは大規模ソフトウェア開発でバグを減らすために体系化された手法だが、AI コーディングエージェントが普及した現在、その意義が改めて高まっている。

なぜ AI エージェント時代に仕様駆動開発が効くのか。理由は単純で、AI エージェントは仕様が曖昧なほど、確率的に間違った解釈をとる可能性が高まるからだ。人間のエンジニアなら「これは前のあの変更と合わせて考えれば、こういう意味だろう」と暗黙的に文脈を埋められる。しかし Codex のようなエージェントは、渡された情報のみを根拠に実装する。曖昧さがあると、それを「もっとも確率の高い解釈」で埋めてしまう。このズレが手戻りを生む。

「バイブコーディング（vibe coding）」という言葉が示すように、「なんとなくこんな感じにして」という漠然とした指示でも AI はそれっぽいコードを返す。しかし Goal Mode で Codex が数十のファイルにわたる変更を数時間かけて実行したあと、意図と違う実装が出てきたときの修正コストは大きい。特に長時間の自律実行では、最初の指示のズレが積み重なる。仕様を先に書くことは、このリスクを構造的に減らす投資だ。

TDD との違いも整理しておく。TDD はテストを「仕様の代わり」として使う面があり、Codex もテストを通過することを完了条件にできる。一方、仕様駆動開発は必ずしもテストを必要とせず、「こういう振る舞いを実現すること」を自然言語や構造化ドキュメントで記述する。TDD と組み合わせると相互補完になる。Codex は両方の情報を活用できるため、「テストは書く・仕様も書く」が最も精度が高い。Codex の公式ガイドも、テストスイートを完了確認の手段として活用することを推奨している（出典: https://openai.com/codex/ ）。

Codex が仕様を読む仕組み — 二層の指示設計

仕様をどう Codex に渡すかを理解するには、Codex の指示の読み方を把握しておく必要がある。Codex が参照する情報源は大きく「永続的な指示」と「その都度の指示」の二種類に分かれる。

永続的な指示の代表が AGENTS.md だ。 AGENTS.md は、Codex がリポジトリで作業を始める前に読み込むカスタム指示ファイルで、ビルドコマンド・テストの流し方・コード規約・触れてはいけない範囲をあらかじめ固定しておく（出典: https://developers.openai.com/codex/guides/agents-md ）。プロジェクト全体の「作法」を一度書いておけば、タスクごとに同じ前提を説明し直す手間がなくなる。仕様駆動開発の観点では、AGENTS.md はプロジェクトの恒久的な仕様の器として機能する。

その都度の指示は、タスクのプロンプトで渡す。 Goal Mode でタスクを依頼するとき、「○○を実装してください」だけでなく、「完了条件はこれで、タッチしてはいけない範囲はここで、検証方法はこのコマンドです」と付け加えると、Codex はその条件に沿って動く。プロンプトの仕様が詳しいほど、最初の実装が完了条件に近づく確率が上がる。

この二層の設計——AGENTS.md でプロジェクト共通仕様を固定し、プロンプトでタスク固有仕様を渡す——が、仕様駆動開発を Codex で実践するときの基本構造だ。どちらか一方でも欠けると、「毎回同じ説明をしなければならない」か「このタスクの完了条件が伝わらない」の問題が起きる。

AGENTS.md は「プロジェクト仕様書」として使う

AGENTS.md の本来の用途は「リポジトリの取扱説明書」だが、仕様駆動開発の観点では「プロジェクトの恒久仕様書」として位置づけるとわかりやすい。ビルドコマンドやコード規約は「Codex が守るべき仕様」であり、触れてはいけないファイルは「実装の禁止仕様」だ。

Codex はグローバルの ~/.codex から始め、Git ルートから現在の作業ディレクトリへと各階層を辿って AGENTS.md を探す。複数見つかった場合はルートから連結され、現在地に近いファイルが後勝ちで優先される。この仕組みを活かして、モノレポではリポジトリ全体の共通仕様をルートに、パッケージ固有の仕様を各サブディレクトリに置くことができる（出典: https://developers.openai.com/codex/guides/agents-md ）。

なお AGENTS.md の読み込みには project_doc_max_bytes（既定 32 KiB）の上限がある。この上限を超えると後半の指示が読まれなくなるため、仕様書は簡潔さを保つことが仕組み上の要請でもある。

Codex に任せてよい作業と人間が担うべき作業

仕様駆動開発の実践において、「何を任せるか」の判断は仕様書の書き方と同じくらい重要だ。全部を任せようとしても、全部を人間でやろうとしても、効率は落ちる。境界線は「仕様が完全に定義できるか」と「出力の検証コストはどうか」で決まる。

Codex に任せやすい作業の特徴

仕様が明確で、完了条件が客観的に確認できる作業は Codex に向く。たとえば「このユーザーストーリーを実装してください。条件は：入力バリデーション・エラーメッセージの表示・単体テストの追加です」のように、完了条件をリストアップできる作業だ。既存コードのリファクタリング（規約に沿った変数名の統一、型アノテーションの追加、デッドコードの削除）も、変更前後の挙動が等価かどうかをテストで確認できるため委任しやすい（出典: https://github.com/openai/codex ）。

また、ドキュメントの生成・更新、テストケースの追加、依存ライブラリのアップデートに伴う修正も、仕様が固定しやすく Codex の得意領域だ。繰り返し発生する定型作業はとくに向いている。プロジェクトの初期セットアップや、既存機能への新しいエンドポイントの追加なども、仕様書を整えれば Codex に任せやすい。

人間が担うべき作業の特徴

仕様そのものを決める判断、アーキテクチャ上のトレードオフ、ステークホルダーとの合意形成は人間の役割だ。「このデータをどのモデルで持つか」「キャッシュ戦略はどうするか」といった設計判断は、プロダクトの方向性・チームの運用能力・コストなどの文脈を総合的に考える必要があり、Codex に丸投げすると決定の根拠が曖昧なコードが生まれる。

また、出力の検証コストが高い作業も注意が必要だ。たとえば自然言語の品質評価（「この文章は読みやすいか」）や、意図した UX が実現されているか（「このフォームは直感的か」）は、Codex の完了基準にしにくい。テストで機械的に確認できない作業は、Codex に委任するより人間がレビューを兼ねて担う方が速いことが多い。判断の基準として「自動テストで完了を確認できるか」という問いが使いやすい。

仕様書の書き方 — Codex が迷わない形式と必要項目

仕様書の品質がそのまま Codex の実装の質に反映される。ここでは、Codex が読んで迷いにくい仕様書の要素を整理する。

必ず書く三要素

どんな仕様書にも最低限含めるべき三要素がある。

第一は「何を実現するか」だ。実装対象の機能や変更の意図を、実装の詳細ではなく振る舞いの観点で書く。「React コンポーネントを作る」ではなく「ユーザーが名前と email を入力して送信すると、確認モーダルが表示される。モーダルで OK を押すと API を呼ぶ」という形だ。実装手段ではなく「結果として何が起きるか」を言葉にすることで、Codex は実装の選択肢を広く持てる。

第二は「完了条件」だ。「何をやればこのタスクは完了か」を箇条書きで書く。可能であれば、自動で検証できる条件（「テストが全件 pass する」「型エラーが 0 件」「Lint エラーなし」）を含める。Codex は自律実行中にこれらを自分で確認できるため、完了条件を満たしたかを自己検証しながら進む（出典: https://openai.com/codex/ ）。完了条件は 3〜7 個に収めると、優先度の境界が明確になる。

第三は「やってはいけないこと」だ。影響範囲を制限する禁止事項を明示する。「auth/ ディレクトリのファイルを変更しない」「既存のデータベーススキーマを変更しない」「本番環境向けの設定ファイルは更新しない」のような形だ。禁止範囲が曖昧だと、Codex は善意で関係するファイルを修正し、想定外の変更が入ることがある。

Codex が処理しやすい形式

Codex は Markdown を高精度で処理できる。見出し（##）で構造を作り、箇条書きで条件を列挙し、コードブロックで具体的な例を示すと、最も確実に指示が伝わる。自然言語のみの長文段落より、構造化された Markdown の方が Codex の解釈精度が安定する傾向がある。

次のような最小テンプレートを使うと、書き始めのハードルが下がる。

## タスク仕様

### 目標
（振る舞いの観点で何を実現するかを 2〜3 文で書く）

### 完了条件
- （自動確認できる条件）
- （自動確認できる条件）
- （手動確認が必要な条件）

### 禁止範囲
- （触れてはいけないファイルやディレクトリ）
- （変更してはいけない設定や構造）

### 検証方法
（完了確認に使うコマンドや手順）

このテンプレートを使い回し、プロジェクトの AGENTS.md に「タスク仕様のテンプレートはこの形式を使う」と書き加えると、チーム全体で仕様の書き方が統一される。

ただし、過度に冗長な仕様書は逆効果だ。AGENTS.md の読み込みには 32 KiB の上限があり、それを超えると後半の指示が読まれなくなる。タスクプロンプトも長すぎると本質的な条件が埋もれる。「完了条件が明確に伝わる最小の仕様」を目指すのが、実用上の最適解だ（出典: https://developers.openai.com/codex/config-advanced ）。

実践手順 — 仕様書から PR までの 4 ステップ

実際の開発フローで、仕様書を起点に Codex を動かして PR を得るまでの手順を 4 ステップで解説する。

Step 1: 要件を仕様書に変換する

開発の起点は要件や課題だ。ここで重要なのは、要件を「Codex に渡せる仕様書の形」に変換してからエージェントを起動することだ。変換の際に確認するチェックポイントは三つある。

「なぜやるのか（背景）」を短く書いているか。Codex は文脈を理解した上で実装するため、背景があると関連する考慮点を拾いやすくなる。ただし背景は長くなりすぎず、1〜2 文で済ませる。次に「完了条件が箇条書きで 3〜7 個以内に収まっているか」を確認する。多すぎる条件は優先度の境界を失い、少なすぎると基準が曖昧になる。最後に「禁止範囲を明記しているか」。この段階でなければ忘れがちなため、仕様書のテンプレートに禁止事項の欄を設けておくと漏れを防げる。

仕様書を書く作業そのものに Codex を使うこともできる。「この issue の説明を読んで、仕様書のテンプレート形式で完了条件と禁止範囲を整理してください」と依頼すると、叩き台が得られる。叩き台を人間がレビューして修正する方が、白紙から書くより速いことが多い。

Step 2: Codex に仕様書を渡して実装を依頼する

仕様書が固まったら、Goal Mode でタスクを開始する。このとき、プロンプトの冒頭に「以下の仕様に基づいて実装してください」と明示し、その後に仕様書の内容を貼り付ける形が最も確実だ。AGENTS.md でプロジェクト共通の前提がすでに固定されている場合、タスクプロンプトには「タスク固有の仕様のみ」を書けばよい。重複を避けることで、プロンプトの長さを削減でき、Codex が注目すべき条件が際立つ（出典: https://developers.openai.com/codex/guides/agents-md ）。

Goal Mode が動作中は、Codex は自律的にコードを読み込み・実装・テスト実行・修正を繰り返す。途中で人間が細かく指示を送る必要は基本的にない。ただし、Codex がインタラクティブモードで確認を求めてくる場合は、仕様書に書いた完了条件を根拠に判断して返答する。判断に迷った場合は「仕様書の完了条件に照らして」という基準で答えを選ぶと一貫性が保てる。

Step 3: 実装を仕様と照合する

Codex が実装を終えたら、まず自動テストの通過を確認し、次に仕様書の完了条件と照合する。この作業は機械的でよい。完了条件を一つずつ確認し、満たされているかをチェックする。テストでカバーされていない完了条件（「UI の表示が正しいか」など）は、手動で確認する。このステップが「仕様書が検証の基準として機能する」瞬間だ。

照合の結果、完了条件を満たしていない項目があった場合は、次のステップに進む。仕様書が正確だったにもかかわらず実装が条件を満たしていない場合は、Codex に具体的なフィードバックを渡す。「仕様の完了条件 X が満たされていません。現在の実装では Y の挙動になっています。Z に変えてください」という形で差分を具体的に伝えると修正効率が上がる。

Step 4: 差分を指示して再実装させる

修正が必要なときは、仕様書を更新するか、追加指示を渡す。ここで重要なのは「仕様書に反映してからフィードバックする」ことだ。その都度のフィードバックで仕様書が更新されないままだと、同じ問題が次のタスクで再発する。AGENTS.md に恒久的なルールを追記し、タスク固有の仕様はタスクプロンプトのテンプレートに落とし込む。この積み重ねが、Codex への指示品質を継続的に上げていく。

修正が 3 回を超える場合は、仕様書の曖昧さが原因であることが多い。完了条件を再確認し、必要なら「この条件を満たすとはどういう状態か」の具体例（Before/After の状態など）を追記する。具体例は仕様書の中で最も理解を補う要素の一つで、Codex が解釈のズレを起こしにくくなる（出典: https://github.com/openai/codex ）。

よくある失敗と対策

仕様駆動開発を Codex に適用するとき、よく見られる失敗パターンと対策を整理しておく。

失敗 1: 仕様書が「何を作るか」しか書いていない

「ログイン機能を実装してください」だけでは、仕様書ではなく要望書だ。完了条件が書かれていないため、Codex はそれなりのログイン機能を作るが、チームが期待するバリデーション・エラーハンドリング・テストカバレッジが揃わないことが多い。対策は、完了条件の列挙を仕様書の必須要素にすることだ。「この機能が完成したと言えるのは、これらの条件を全て満たすとき」という書き方に慣れると、自然に仕様書の形が整ってくる。

失敗 2: 禁止範囲が不明確で想定外の変更が入る

Codex が善意でリファクタリングしたり、関連する別のファイルを修正したりすることがある。これは Codex の問題ではなく、「どこまでが今回のタスクの範囲か」が仕様に書かれていないことが原因だ。対策は、タスクの scope（触ってよいファイルの範囲）を明記することだ。AGENTS.md に「常に変更してはいけないファイル」を書いておき、タスクプロンプトには「今回のタスクで変更するのは src/feature/ 配下のみ」のように scope を制限する（出典: https://developers.openai.com/codex/guides/agents-md ）。

失敗 3: 仕様書を更新せずに口頭指示で修正を繰り返す

Codex とのやり取りの中で「ここをこう変えて」という追加指示を繰り返すと、仕様書と実装の間に乖離が生まれる。次のタスクで同じ範囲を再度依頼すると、Codex は更新されていない仕様書を読んで古い実装に戻すことがある。対策は、追加指示をした場合は必ず仕様書（AGENTS.md またはタスクプロンプトのテンプレート）に反映することだ。仕様書は一度書いたら変えないものではなく、実装の変化とともに育てるドキュメントとして扱う。

失敗 4: 仕様書が長くなりすぎて重要条件が埋もれる

仕様書に完璧を求めると肥大化する。AGENTS.md の読み込みには 32 KiB の上限があり、超えると後半の指示が読まれなくなる。タスクプロンプトも長くなるほど、Codex の注意が分散してしまう。対策は「この仕様書から最も重要な完了条件は何か」を問い直し、冗長な記述を削ることだ。詳細な背景や参考情報は外部ドキュメントへのリンクで補い、仕様書本体は「Codex が迷わないための最小情報」に絞る（出典: https://developers.openai.com/codex/config-advanced ）。

失敗 5: Codex の出力を仕様書と照合せずにそのまま使う

Codex が「完了しました」と報告しても、仕様書の完了条件と照合しないままマージするのは危険だ。Codex は自己報告の精度が高い一方で、ごく稀に「完了条件の見落とし」や「隣接する問題への過剰な対応」が起きることがある。仕様書との照合を省略しないことが、仕様駆動開発のサイクルを成立させる最後の歯止めになる。レビューの観点も「このコードは正しいか」だけでなく「仕様書の完了条件を満たしているか」に移すと、レビューの効率と精度が同時に上がる。

まとめ — 仕様を「先に書く」ことが自律実行の精度を決める

仕様駆動開発は、AI コーディングエージェントが長時間自律実行する時代において、「何をやるか」の明確さが手戻りを構造的に減らす有効な手段だ。Codex に任せる作業を「仕様が定義できるもの」に限り、AGENTS.md とタスクプロンプトの二層で仕様を渡し、完了後に仕様と照合する。このサイクルを回すことで、Codex をコードの生成器ではなく「仕様を実装に変えるエージェント」として扱えるようになる。

まず試すなら、次のタスクを Codex に渡す前に「完了条件を 3 つ箇条書きで書いてみる」ことから始めるとよい。条件を書こうとする過程で、自分が何を期待しているかが明確になり、それ自体が仕様書になっていく。仕様書の質を上げる習慣は、Codex の精度を上げる習慣と同義だ。

出典

• OpenAI Codex 製品ページ
• Custom instructions with AGENTS.md – Codex | OpenAI Developers
• Advanced Configuration – Codex | OpenAI Developers
• openai/codex — GitHub リポジトリ