Codex Cookbook: コードベースをモダナイズする実践レシピ
OpenAI 公式 Cookbook の Code Modernization 例をもとに、レガシーコードベースを Codex で段階的に近代化する進め方を 2026 年 5 月時点の仕様で整理。AGENTS.md / PLANS.md 起点のパイロット選定、インベントリ調査、設計と検証計画、実装と検証までの 5 フェーズを実例ベースでまとめます。
要点
- 大規模なモダナイゼーションは 小さなパイロットから始める
AGENTS.md（恒久ルール）とPLANS.md（実行計画）を最初に用意- Phase 0〜4 の 5 段階で進める：作業ガイド整備 → パイロット選定 → インベントリ調査 → 設計と検証計画 → 実装と検証
- Codex に任せるのは 調査 / 整理 / 移行計画 / 実装 / テスト補助。判断・優先順位・リスク確認は人間が担当
- 「大きな変更を一気に任せる」ではなく「相棒として一緒に進める」感覚で使う
このレシピの一次ソースは OpenAI Cookbook の Code Modernization 例 です。
なぜモダナイゼーションに Codex が向くのか
コードベースの近代化は、単純な置換作業ではありません。既存の設計、依存関係、テスト、運用上の制約を理解した上で、少しずつ変えていく必要があります。
Codex は大きなコードベースを読み、関連ファイルを探し、変更候補を整理できるため、モダナイゼーションの 初期調査と反復作業に向きます。一方で、業務上の優先度や移行戦略の最終判断は人間が担うべき領域です。
両者を混ぜず、フェーズで分けるのがこのレシピの肝です。
Phase 0: 作業ガイドを用意する
最初に、Codex が守るべきルールを明文化します。
AGENTS.md（恒久ルール）
- プロジェクトの言語・フレームワーク
- ビルド / テスト / lint コマンド
- 禁止事項（破壊的変更禁止、特定 API への直アクセス禁止など）
- レビュー方針
PLANS.md（今回の実行計画）
- 今回の目的
- パイロット範囲
- マイルストーン
- 検証方法
- 未解決の判断事項
この 2 ファイルを分けると、恒久ルールと一時的計画が混ざらず、Codex が毎回同じ前提で作業できます。
Phase 1: パイロットを選ぶ
最初から全体を変えるのではなく、小さく検証できる範囲を選びます。
良いパイロットの条件:
- 影響範囲が限定されている（独立モジュール、特定ディレクトリ）
- 既存テストや手動確認がしやすい
- 成功したときに横展開しやすい（他の似たモジュールが残っている）
- チームが変更内容をレビューできる
Codex への依頼例:
本リポジトリで、以下の条件に合うモダナイゼーション候補領域を3つ提案してください。
条件:
- 影響範囲が他モジュールに広く波及しない
- 既存テストがある
- 古いAPIや非推奨パターンを使っている
- 横展開しやすい
各候補について、対象ファイル、現状の問題、リスク、検証方法を簡潔にまとめてください。
まだ実装の変更はしないでください。Phase 2: インベントリと発見
次に、対象領域の現状を整理します。
Codex に任せられる調査:
- 関連ファイルの一覧化
- 古い API や依存関係の使用箇所調査
- テストの有無確認
- 変更時に壊れそうな箇所の洗い出し
- 外部呼び出し元の特定
@src/legacy-auth/ ディレクトリのインベントリを作ってください。
調べてほしい内容:
1. ファイル一覧と各ファイルの役割（1-2行）
2. このディレクトリ外から参照されている関数・型のリスト
3. テストファイルとカバレッジ概観
4. 削除されている依存ライブラリ・非推奨APIの使用箇所
5. 変更時のリスクが高そうな箇所
実装変更はせず、結果を整理して PLANS.md に追記してください。ここでは「実装よりも何があるかを正確に把握する」のが目的です。
Phase 3: 設計と検証計画
移行方針を決める段階では、Codex に 複数案を出させます。ただしどの案を採用するかは人間が判断します。
設計時の確認:
- 既存の外部仕様を変えないか
- テストで確認できるか
- ロールバックしやすいか
- 一度に変更しすぎていないか
PLANS.md のインベントリを踏まえて、移行アプローチを 3 案出してください。
各案について:
- アプローチの概要
- 段階的な変更ステップ
- 各ステップの検証方法
- 想定リスクとロールバック手順
- 工数の感覚（小・中・大）
人間が選びやすい形でまとめてください。実装はまだしないでください。採用案を PLANS.md の Milestones セクションに書き込み、各 milestone のスコープを 1〜2 日で終わる粒度に切ります。
Phase 4: 実装と検証
計画が固まったら、Codex に 小さな単位で実装させます。
PLANS.md の Milestone 1（auth helper の関数分割）を実装してください。
制約:
- public な関数シグネチャは変えない
- 既存テストはすべて通す
- 新規テストを追加（境界値ケースを含む）
- 1 PR で完結する粒度に収める
完了後、変更ファイル一覧と実行したテストコマンド・結果を報告してください。実装後は テスト / 型チェック / lint / 手動確認を組み合わせて検証します。失敗時はログを渡して再調査:
このテスト失敗を分析してください。
[ログ貼付]
期待していた挙動と実際の差分を整理し、原因の仮説を 2-3 個出した上で、
最も可能性が高いものから検証手順を提案してください。アンチパターン
- 大きな PR を 1 つで済まそうとする: レビュー不能になる。Milestone ごとに分ける
PLANS.mdを作らずに会話だけで進める: 同じ前提を毎回説明することになる- 破壊的変更を Codex 任せ: API 互換性の判断は人間が行う
- テストなしで進める: 検証可能性が下がり Codex の判断もブレる
横展開フェーズ
パイロットが成功したら、同じパターンを他の領域へ横展開します。このとき:
- パイロットで得た 学び（うまくいった prompt、失敗パターン）を
PLANS.mdの付録に残す - 横展開時は
AGENTS.mdを更新（「auth/ 配下は新パターン、legacy-* 配下は旧パターン」のような移行期の二重ルールが必要なら明記） - 大きすぎる横展開は再度パイロットから
まとめ
Codex を使ったモダナイゼーションは、作業を小さく分け、計画と検証を明示するのが安全です。
「大きな変更を一気に任せる」ではなく、「調査 / 計画 / 実装 / 検証を一緒に進める相棒」として使うと、Codex の強みが活きます。