AI Tools 2026年5月9日

Codex Cookbook: PLANS.mdで長時間タスクを安定して進めるExecPlan運用

OpenAI 公式 Cookbook の Codex Exec Plans 例をもとに、`PLANS.md` を使って数十分〜数時間の複雑タスクを Codex に進めさせる運用を 2026 年 5 月時点の仕様で整理。AGENTS.md との使い分け、ExecPlan に書く項目、生きた計画として更新する考え方、レビュー性を上げるテクニックをまとめます。

#Codex #cookbook #PLANS.md #ExecPlan #long-running #AGENTS.md

要点

  • 数十分〜数時間の長時間タスクは、会話だけでなく PLANS.md ファイルとして計画を残す
  • AGENTS.md（恒久ルール）と PLANS.md（実行計画）を使い分ける
  • ExecPlan に書く要素：目的 / 背景 / マイルストーン / 検証方法 / 未決事項 / 作業ログ
  • 計画は固定文書ではなく「生きた計画」として作業中に更新する
  • 人間が 途中レビューしやすくなるのが最大のメリット

このレシピの一次ソースは OpenAI Cookbook の Codex Exec Plans 記事 です。

なぜ ExecPlan が必要か

Codex に長い作業を任せると次の問題が起きやすくなります。

  • 文脈が膨らむ: ターンが増えるとモデルの context が圧迫され、compaction で重要情報が落ちる
  • 判断が見えなくなる: なぜこの実装になったのかが、会話履歴を遡らないと追えない
  • 再開できない: 作業を中断してから戻ると、Codex も人間も前提を忘れている
  • レビューしにくい: 全体像が把握できず、ピンポイントで気になる箇所を確認しづらい

ファイルとして計画を残しておくと、Codex も人間も同じ前提に戻れるため、これらが大幅に改善します。

AGENTS.md と PLANS.md の役割分担

ファイル役割寿命
AGENTS.mdプロジェクトで常に守るべきルール（テストコマンド、コードスタイル、禁止事項、レビュー方針）恒久
PLANS.md特定タスクの進め方（目的、変更対象、マイルストーン、進捗、判断ログ）タスク完了まで

このように分けると、恒久的なルールと一時的な計画が混ざらずに済みます。タスクが完了したら PLANS.md は削除またはアーカイブ。AGENTS.md は残す。

ExecPlan に書くとよい内容

長時間タスクで効果的なテンプレ:

# PLANS.md - <タスク名>

## 目的
何を達成したいのかを 1〜2 文で。

## 背景
なぜこの変更が必要なのか、どの制約があるのか。
（業務要件、技術的負債、外部要因）

## スコープ
- やる: ...
- やらない: ...

## マイルストーン
1. **M1: 〇〇の調査**
   - スコープ: ...
   - 検証: ...
2. **M2: △△の実装**
   - スコープ: ...
   - 検証: ...
3. **M3: ××のリリース**
   - ...

## 検証方法
- 単体テスト: `npm test ...`
- 統合テスト: `...`
- 手動確認: `...`
- ロールバック手順: `...`

## 未決事項
- [ ] DB スキーマ変更を伴うか（要 PM 確認）
- [ ] 既存 API バージョンを維持するか

## 作業ログ
### 2026-05-09 M1 開始
- インベントリ作成完了。対象ファイル数 47
- 想定外: legacy-api/ にも依存箇所あり
- 判断: M1 のスコープに legacy-api/ の調査も含める

生きた計画として更新する

ExecPlan は最初に作って終わりではありません。作業中の発見を書き戻すのが本質です。

更新のタイミング:

  • 調査で新しい事実が出た
  • 方針を変更した（理由も書く）
  • マイルストーンを完了した
  • 未決事項に答えが出た
  • 想定外のリスクが見つかった

これにより、あとからレビューする人が **「なぜこの実装になったのか」**を追いやすくなります。コミットメッセージや PR 本文にも転記すると、レビュアー体験がさらに上がります。

Codex への依頼パターン

計画を立てさせる

$plan

以下の作業を進めるための実行計画を PLANS.md として作ってください。

タスク: ユーザー認証を OAuth2 から OIDC へ移行する

含めてほしい内容:
- 目的、背景、スコープ
- マイルストーン（各 1〜2 日で終わる粒度）
- 検証方法（テスト、手動確認、ロールバック）
- 未決事項

ファイル変更はせず、PLANS.md だけ作成してください。

マイルストーンを実装させる

PLANS.md の Milestone 2 を実装してください。

完了条件:
- M2 のスコープに書かれた変更がすべて完了
- M2 の検証コマンドがすべて通る
- 作業ログを PLANS.md の「作業ログ」セクションに追記
- 想定外の発見があれば「未決事項」に追記

中断後に再開する

PLANS.md を読み、作業を再開してください。

確認してほしい点:
- 完了済みのマイルストーン
- 進行中のマイルストーンと現状
- 未決事項
- 次にやるべきこと

再開前に「現状把握」のサマリを返し、人間の確認を待ってください。

Goals 機能との関係

Codex App / CLI には Goals という長期タスク管理機能があります（workflows-goals 参照）。

両者の違い:

観点GoalsPLANS.md
形式Codex 内部の構造化データリポジトリ内の Markdown ファイル
共有個人のセッション内チーム全員が git 経由で見える
バージョン管理なしgit で履歴管理
Codex 以外からの参照困難エディタで普通に開ける

**Goals は「Codex のセッション継続用」、PLANS.md は「人間 × Codex の共通文書」**と覚えるとよいです。両方併用して、Codex の Goals が進行中の作業状態を持ち、PLANS.md がチーム共有のドキュメントになる構成も自然です。

レビュー性を上げるテクニック

マイルストーンごとに PR を分ける

PLANS.md のマイルストーンと PR を 1:1 対応させると、レビュアーが粒度を予測しやすくなります。

コミットメッセージに M番号を含める

feat(auth): M2 - OIDC discovery endpoint 統合

PLANS.md の M2 を完了。OAuth2 callback ルートを OIDC 標準に置換。

PLANS.md 自体も PR の差分に含める

PLANS.md の更新も同じ PR に入れると、レビュアーが「実装と意図」を一画面で見られます。

アンチパターン

  • PLANS.md を作らずに長時間タスクを始める: 途中で context が膨らんで失敗する
  • マイルストーンが大きすぎる: 1 マイルストーン = 1 PR の粒度に切れていない
  • 作業ログを書かない: 後から再開できない
  • AGENTS.md に一時情報を入れる: タスクが終わってもルールに残ってしまう

まとめ

PLANS.md は、Codex に長時間タスクを任せるための 作業地図です。

複雑なタスクほど、計画 / 進捗 / 判断理由をファイルに残すことで、Codex との協働が安定します。最初は手間に感じても、中断・再開・レビューの場面で必ず効いてきます。

関連リンク