2026/10/31
AI活用
Codexで長期開発をフェーズ化する――承認ゲート付き計画ファイルの作り方
対象読者：上級者向け
長期開発の着手前に起きる「計画の再解釈」
たとえば、中小企業向けSaaSに「操作履歴の検索・CSV出力・保存期間設定」を追加する案件を考えてみます。プロダクト責任者が要件をまとめ、テックリードが設計方針を決め、複数の開発者が実装とレビューを担当します。既存の道具は、Gitリポジトリ、課題管理票、設計メモ、テストコード、CIです。個々の道具は整っていても、数週間に及ぶ開発では、要件を実装単位へ変換する工程が担当者ごとに繰り返されがちです。
AIを使わない場合、テックリードは要件書と既存コードを読み、データモデル、API、画面、権限制御、移行処理、テストへ作業を分けます。各工程の前提条件と受け入れ条件を記載し、レビューを受けてから課題管理票へ転記します。別の開発者が着手するときには、要件書、設計メモ、過去の議論、関連テストを再び読み、今回の作業範囲を組み立て直します。担当交代や中断があると、判断の背景まで引き継げず、後続工程で同じ論点が再検討されることもあります。
ここで解決したい課題は、実装そのものをCodexへ一括委任することではありません。リポジトリ内の方針とロードマップを基に、独立して承認・実装・検証できる小さなフェーズへ分割し、各フェーズの開始前に人が止められる状態を作ることです。成果物は、`harness/build/`配下に置くフェーズ別の計画ファイルとします。入力資料、依存関係、対象範囲、Red・Green・Refactor、検証コマンド、受け入れ条件を同じ書式で残せば、担当者は「次に何を作るか」だけでなく、「何をまだ作ってはいけないか」も確認できます。
この記事で扱うのは計画作成と承認までです。アプリケーションコードの変更、コミット、プッシュ、デプロイは別の承認対象とします。Git、テスト設計、依存関係の判断、リポジトリ構成の読解を前提とするため、開発経験者向けの実践内容です。
工程分解で負荷が集中する五つの作業
長期開発の計画で時間を使うのは、文章を書く作業だけではありません。最初の負荷は資料探しです。ルートの開発方針、サブディレクトリ固有の規約、パッケージ定義、既存テスト、CI設定をたどり、今回の変更に適用されるルールを特定します。見落としがあれば、実装後に命名規則や境界設計を直す手戻りにつながります。
続いて、要件を実装可能な粒度へ分類します。「監査ログ機能」という一つの要求でも、保存形式、閲覧権限、検索条件、出力形式、障害時の扱いは異なる責任を持ちます。分類後には依存関係を並べます。データモデルより先にAPIを完成条件へ含めたり、権限制御が未確定のまま画面を作ったりすると、独立して検証できるフェーズになりません。
受け入れ条件の作成にも判断が必要です。「正しく動く」「十分にテストする」といった表現では、完了判定が担当者に依存します。入力、観測可能な出力、失敗条件、実行するテストを結び付ける必要があります。その後、課題管理票や引き継ぎ文書へ同じ情報を転記し、レビュー指摘が出るたびに複数箇所を修正します。最後に、次の担当者が計画とリポジトリの現状を照合し、未完了部分を判断します。
問題は、これらが単純作業と設計判断の混合になっている点です。資料名の列挙、共通見出しの作成、既存コマンドの転記、フェーズ間の参照整理は一定の型へ寄せられます。対して、機能境界、依存順序、セキュリティ要件、受け入れ可能なリスクは人が決めるべき領域です。Codexには前者の抽出と下書きを担当させ、後者は承認ゲートで止める設計が適しています。計画作成の自動化と、計画内容の自動承認を混同しないことが、この運用の前提になります。
従来工程とCodexを組み込んだ工程の対応
OpenAIの公式レシピでは、`AGENTS.md`はCodexが認識する任意のリポジトリ指示ファイルと説明されています。リポジトリの目的、コーディング規約、テスト基準、参照資料、スコープや境界などを持続的な指針として記載できます。`PLANS.md`やフェーズ別ファイルはCodexの必須仕様ではなく、チームが採用できる任意のワークフロー規約です（出典: OpenAI Developers）。この区別を理解しておけば、特定のファイル構成を製品の必須条件と誤解せず、自社の既存運用へ合わせられます。
同じ要件、同じリポジトリ、同じ品質条件から計画を作る場合、工程の対応は次のように整理できます。
| 工程 | AIを使わない場合 | Codexで補助する範囲 | 人が残す判断 |
| --- | --- | --- | --- |
| 資料確認 | 関連文書とコードを手で探索する | 適用される指示、計画、テスト、マニフェストを列挙する | 読むべき資料の過不足を確認する |
| フェーズ分割 | 要件を課題へ手作業で分解する | 依存順を含む分割案を作る | 境界と順序を承認する |
| 計画記述 | 各課題へ共通項目を転記する | 統一書式で計画ファイルを下書きする | 非目標と承認条件を確定する |
| 検証設計 | テスト名やコマンドを調査する | リポジトリから候補を抽出する | コマンドの妥当性と網羅性を判断する |
| 引き継ぎ | 状況を読み直して説明する | 停止条件と必要な証拠を明文化する | 完了証拠を確認して次工程を許可する |
Codexによって省略できる可能性があるのは、共通書式の再作成や複数資料からの転記です。資料探索と工程分解は完全には消えませんが、調査結果と分割案を一度に提示させれば、人はゼロから書く代わりに差分を審査できます。ただし、Codexが実在しない検証コマンドや未承認の要件を補ってしまえば、計画はかえって危険になります。分からない項目を「未解決」と記載させ、書き込み前に対象ファイルを提示させる必要があります。効率化の単位は人の判断を減らすことではなく、判断に必要な材料を一定の形へそろえることです。
計画生成前に整える二つの基準文書
実践には、Gitリポジトリの構造、使用言語、テストフレームワーク、CI、セキュリティ境界を説明できる担当者が必要です。開始前に、作業ツリーの変更状況も確認します。未コミットの変更がある場合は、それが今回の計画対象か、別作業かを識別できるようにします。Codexへ計画作成を依頼する前から、秘密情報、顧客データ、認証情報を入力対象に含めない運用も決めておきます。
`AGENTS.md`には、長期間変わりにくい実行規約を置きます。たとえば、アーキテクチャの境界、変更してよいディレクトリ、命名規則、テストの基本方針、禁止操作、外部書き込みに必要な承認です。公式レシピでも、リポジトリの概要、コーディング規約、テスト基準、関連コンテキスト、プロジェクト固有の振る舞い、スコープと境界が記載例として挙げられています（出典: OpenAI Developers）。一時的な進捗や個別フェーズの細かな手順まで詰め込むと、恒久ルールとの区別が曖昧になるため避けます。
`PLANS.md`には、今回の開発目的、ロードマップ、フェーズ順、主要な判断、受け入れ条件を記載します。これは提案する運用上の基準文書であり、Codexが必須とするファイルではありません。要件が未確定なら、Codexに推測させず、「権限モデルは責任者の判断待ち」「移行対象期間は未決定」のように未解決事項として残します。フェーズ番号や用語は既存の課題管理と合わせ、別名による混乱を防ぎます。
準備完了の条件は、文書が長いことではありません。リポジトリの目的、変更境界、テスト方針、ロードマップ、未決事項の所在を第三者が追えることです。`PLANS.md`が存在しない、または明確な順序を示していない場合には、Codexへファイル生成まで進ませません。分割案だけを提示させ、人が承認した後に計画ファイルを書かせます。これにより、AIが不足情報を埋めた案と、チームが承認したロードマップを区別できます。
読み取り専用の調査から承認ゲートを作る手順
最初の操作では、Codexにファイルを書かせず、リポジトリの現状と計画根拠を調査させます。公式レシピでも、フェーズ別ファイルを作る前に、適用される指示、計画文書、既存のビルドファイル、マニフェスト、テスト、検証コマンドを確認し、提案するパスを示して明示的な承認を待つ流れが例示されています（出典: OpenAI Developers）。画面名や特定の操作モードには依存せず、Codexへ渡す依頼文自体に「読み取り専用」「書き込み前に停止」を記載します。
主な操作は四段階です。第一段階では、対象ブランチと作業ツリーを人が確認します。第二段階では、Codexに適用される`AGENTS.md`、`PLANS.md`、既存計画、マニフェスト、テスト、CI設定を列挙させます。第三段階では、フェーズ名、依存関係、作成予定パス、各フェーズの目的、未解決事項を提示させます。第四段階で人が分割案を修正し、作成を許可するファイルだけを明示します。
コピーして使うお願い文の例です。実際のディレクトリ名や計画ファイル名は、自社リポジトリに合わせて置き換えてください。この依頼文は運用例であり、公式機能の追加仕様を示すものではありません。
このリポジトリについて、読み取り専用の調査を行ってください。
適用されるAGENTS.md、PLANS.md、既存のharness/build配下、
パッケージ定義、テスト、CI設定を確認してください。
書き込みを始める前に、次の内容だけを報告してください。
1. 確認した情報源と、それぞれが所有するルール
2. 現在の実装状態と未解決事項
3. 依存順を保った小さな実装フェーズ案
4. 作成または更新を提案する正確なファイルパス
5. 各フェーズの対象範囲、非目標、受け入れ条件
6. リポジトリから確認できた検証コマンド
根拠がない要件やコマンドは推測せず、未解決と表示してください。
計画ファイル、コード、テスト、設定はまだ変更しないでください。
私が対象パスを承認するまで停止してください。
回答を受け取ったら、フェーズ間の依存が循環していないか、後続機能が前段へ紛れ込んでいないかを確認します。提案されたコマンドが実際のマニフェストやCIに存在するかも照合します。「妥当そう」という印象だけで承認せず、根拠となるファイルと行動を追える状態にしてから書き込みへ進みます。
Red・Green・Refactorを含むフェーズ別ファイルの生成
承認後は、許可した`harness/build/`配下だけを作成・更新させます。公式レシピでは、フェーズ別ファイルに目的、追加コンテキスト、受け入れ条件、境界を持たせる構成が紹介され、`harness/build/
各ファイルでは、Redを「失敗することを確認できる最小のテストまたは検査」、Greenを「承認済みの挙動を通す最小実装」、Refactorを「挙動と範囲を変えずに行う整理」として具体化します。検証は、対象機能に絞ったコマンドと、リポジトリ全体への影響を見る広いコマンドを分けます。実在を確認できないコマンドは記入せず、決定待ちにします。計画段階ではテストに合格したと書かず、実装時に収集すべき証拠だけを定義します。
コピーして使う生成依頼の例です。`承認済みパス`の部分には、直前のレビューで許可したファイルだけを列挙してください。
先ほど承認した分割案に従い、承認済みパスの計画ファイルだけを
harness/build配下へ作成または保守的に更新してください。
アプリケーションコード、テスト、依存関係、設定、AGENTS.md、
PLANS.md、ログ、READMEは変更しないでください。
各フェーズには次を含めてください。
- フェーズ番号、名称、初期状態
- 根拠となる入力資料
- 目的、対象範囲、明示的な非目標
- 依存関係と前提条件
- 影響が想定されるファイルまたはコンポーネント
- 人の判断が必要な事項と承認ゲート
- Red、Green、Refactor、検証の計画
- 確認済みの限定テストと広範な検証コマンド
- セキュリティ、信頼性、観測性、復旧上の考慮事項
- 観測可能な受け入れ条件
- 完了時に残す証拠と停止条件
後続フェーズの実装を前倒ししないでください。
不明点は推測せず、未解決として記録してください。
計画の作成後も実装は開始しないでください。
最後に変更ファイルを列挙し、差分の形式検査結果と未解決事項を報告してください。
架空の監査ログ機能なら、フェーズ00を既存挙動とテスト基盤の確認、フェーズ01を保存モデル、フェーズ02を権限付き検索API、フェーズ03をCSV出力、フェーズ04を統合検証とする案が考えられます。ただし、これは提案例です。既存アーキテクチャで検索と出力が同じ境界に属する場合や、移行処理が先行する場合は分割を変えます。Codexが出した順序より、リポジトリの依存関係とチームのリリース戦略を優先してください。
人が承認する依存関係・境界・完了条件
生成後のレビューでは、文章の読みやすさより、計画が実装時の逸脱を防げるかを確認します。最初の観点はトレーサビリティです。各フェーズの目的と受け入れ条件が`AGENTS.md`または`PLANS.md`のどこに由来するかを追い、根拠のない機能、期限、保証、アーキテクチャ変更が追加されていないかを調べます。計画にもっともらしい要件が書かれていても、元資料に存在しなければ承認対象から外します。
依存関係では、先行フェーズが後続フェーズに必要なインターフェースや不変条件を提供するかを確認します。同時に、独立して検証できる粒度になっているかも見ます。一つのフェーズにデータモデル、API、画面、移行、監視が詰め込まれているなら、失敗時の切り分けと承認が難しくなります。反対に、ファイル一つずつの細分化で意味のある挙動を確認できない場合も、フェーズとしては小さすぎます。
受け入れ条件は、「テストを追加する」ではなく、どの入力に対して何が観測でき、どの失敗を拒否するかまで確認します。Redで予定するテストが現状で本当に失敗する理由、Greenが過剰実装を要求していないこと、Refactorが新しい仕様を持ち込まないことも審査対象です。検証コマンドは、実際のパッケージ定義、タスクランナー、CI設定と照合します。認証情報、外部API、インフラ変更、デプロイ、コミット、プッシュが必要なら、計画作成の承認と分離した許可を設けます。
承認後の実装依頼でも、対象フェーズを一つに限定します。Codexには、計画ファイルと関連資料を読み、書き込み前の確認結果を示し、承認されたRed・Green・Refactorと検証だけを進め、次のフェーズへ自動的に移らないよう依頼します。完了判定は会話上の報告だけで行いません。差分、テスト出力、静的解析結果、未解決事項を人が確認し、受け入れ条件との対応を記録します。Codexは証拠の収集と整理を補助できますが、リスクの受容と次フェーズの開始判断は責任者が行います。
効率化を計測し、最初の一フェーズで確かめる方法
この運用で期待できるのは、資料名や共通見出しの転記、計画書式の再作成、フェーズ間参照の整理といった繰り返しをまとめられることです。要件解釈、依存順序、セキュリティ境界、受け入れ判断は残ります。準備が不十分なリポジトリでは、未解決事項の整理や出力修正に手間がかかるため、Codexを使えば常に短縮できるとは限りません。効果は、実装速度ではなく計画工程全体を同じ条件で比較して確かめます。
比較時には、同じ規模の変更を対象に、資料探索、フェーズ分割、計画記述、レビュー修正、引き継ぎ準備へ費やした作業を記録します。時間だけでなく、レビューで見つかった根拠不明の要件数、検証コマンドの誤り、フェーズ間の重複、承認後の計画差し戻しも確認するとよいでしょう。Codex利用時は、`AGENTS.md`や`PLANS.md`を整備した時間、依頼文の作成、出力確認、修正の負荷も含めます。都合のよい工程だけを除外すると、実務上の効果を判断できません。
導入の最初の一歩は、進行中の大型案件を丸ごと変えることではありません。要件とテスト方針が比較的明確な一機能を選び、読み取り専用の調査と一つのフェーズファイル作成だけを試します。人が作った従来の計画と並べ、根拠、境界、Red・Green・Refactor、検証コマンド、停止条件に不足がないかをレビューしてください。差分から再利用できる項目が見つかったら、`AGENTS.md`の恒久ルールや計画テンプレートへ反映します。
次のフェーズへ進む基準は、Codexの提案が詳しいことではありません。担当者が根拠を追え、未知の項目が未知のまま表示され、承認した範囲だけを実装へ渡せることです。まず一つの計画ファイルでその状態を作り、修正負荷まで含めて記録すれば、自社の開発工程に広げる価値があるかを具体的に判断できます。