OpenAI Codex CLI ワークフローパターン 2026 — セットアップから本番自動化まで

Codex CLIを動かすこと自体は難しくない。しかし、常に安定して有用な仕事をさせること — スケールさせること — には、ワークフロー設計が必要だ。

本記事は AGENTS.md セットアップガイド の続編だ。Codexがインストラクションファイルを探す仕組み、32 KiBの予算制約、AGENTS.mdに書くべき内容についてはそちらを先に読んでほしい。本記事はその基盤が整っていることを前提としている。

扱う内容は次の通り：経験者が収束した7つのワークフローパターン、各パターン向けのAGENTS.mdチューニング、Codex CLI・Claude Code・Cursorの実践的な比較、コスト最適化の実践手法、スケールしようとしたときに起きる失敗パターンとFAQ。

2026年に変わったこと

Codex CLIは2025年初頭にリサーチプレビューとして公開された。年央には本番ワークフローで使えるレベルに安定し、周辺エコシステム（AGENTS.mdツーリング、CI連携、モノレポパターン）も成熟してきた。

ワークフロー設計に影響する主な変化を押さえておく。

サンドボックス実行がデフォルトになった。 --sandbox=full を使うとCodexはネットワーク無効・書き込み制限付きのサンドボックス内で動く。2025年はオプトインで遅延も目立ったが、2026年のサンドボックスオーバーヘッドは通常タスクで300ms以下まで下がった。これにより、マルチステップの自動化で意図しないファイル変更がリポジトリ全体に広がるリスクを気にせずに長い処理を走らせられるようになった。

承認モデルの粒度が上がった。 「すべて自動承認」（--ask-for-approval never）と「すべてのシェルコマンドを承認」（always）の二択だったのが、~/.codex/config.toml で特定のコマンドクラスを自動許可するポリシーを定義できるようになった。CIでCodexを動かすチームはこれを積極的に使っている。

サブエージェントの引き継ぎが安定した。 CodexがAGENTS.mdで定義したサブエージェントを呼び出し、その出力を待って処理を続けることが可能になった。2025年はワークアラウンドが必要だったが、2026年ではAGENTS.mdの ## Agents セクションが一級機能として文書化されている。

チェックポイントをまたいだコンテキスト持続。 セッションがステップ間で状態をチェックポイントできるようになり、2025年ではタイムアウトやコンテキストドリフトで崩壊していた数時間にわたる自律実行が可能になった。

ワークフローパターンカタログ

パターン1: インラインレビュー

概要: コードを書いた後にCodexがレビューする。スタイルではなく正確性・エッジケース・論理的問題にフォーカスし、具体的なファイル位置と問題内容を構造化リストで出力する。

使いどころ: フィーチャー完成後またはリファクタ後、PRを開く前。自分で書いたコード（盲点が生じやすい）に対して最も効果が高い。

セットアップ:

レビュー用プロンプトテンプレート review.md を作成する。

[DIFF_PATH] のdiffを以下の優先順で確認する。

1. 論理エラー — 条件の誤り、オフバイワン、nullチェックの不備
2. 未処理のエッジケース — 既存テストスイートがカバーしていない入力
3. 境界違反 — AGENTS.mdで定義したアーキテクチャ境界を越えるもの
4. セキュリティ問題 — インジェクション経路、認証チェックの欠如

各問題について:
- ファイルと行番号
- 問題の一文説明
- 問題を修正する最小限のコード変更（全面書き換えは不要な限りしない）

スタイル問題は指摘しない。「Xの代わりにYを使うと良い」は
実際のバグに直結しない限り書かない。

実行:

git diff main > /tmp/current.diff
codex --approval-mode never \
  --model o4-mini \
  "$(cat review.md | sed 's|\[DIFF_PATH\]|/tmp/current.diff|')"

AGENTS.mdチューニング:

## レビュー境界

コードレビューを依頼された場合:
- 上記の「プロジェクト構造」で定義したアーキテクチャ層を参照する
- 違反はレイヤー名で指摘する（例:「ルートハンドラにビジネスロジック: servicesレイヤー違反」）
- テストカバレッジのギャップ: 「テストを増やせ」ではなく具体的なシナリオを列挙する
- セキュリティ: [プロジェクト固有のよくある問題リスト] を確認する

指摘しない:
- フォーマット（eslint/prettierが担当）
- 変数名（曖昧さによるバグがなければ）
- 「シンプルにできる」という観察（バグにならない限り）

ポイント: ほとんどの開発者はCodexを生成に使い、レビュアーとしての価値を見逃している。正確性にフォーカスした構造化レビュープロンプトは、論理エラー発見において人間のコードレビューより効果的なことが多い。

パターン2: スペック駆動生成

概要: 実装前に仕様書（構造化された散文、疑似コードではない）を書き、Codexがそれを満たす実装を生成する。仕様書がソースオブトゥルースとなり、生成されたコードは仕様をテストとして走らせてから初めてコミットする。

使いどころ: 実装方法より先に振る舞いが明確な新機能。APIエンドポイント、データ変換、複雑な状態ロジックに特に有効。

仕様書フォーマット:

# スペック: レートリミッター

## 振る舞い

- 入力: userId (string), action (string), windowMs (number), limit (number)
- 出力: { allowed: boolean, remaining: number, resetAt: Date }
- (userId, action) ペアごとに指定ウィンドウ内の試行回数を追跡する
- ウィンドウはリクエストごとにスライドする（固定カレンダーウィンドウではない）
- 同一userIdの並行リクエストは安全に処理する（競合状態なし）

## エラーケース

- userId が空文字: ValidationError("userId required") をthrow
- limit < 1: ValidationError("limit must be positive") をthrow
- windowMs < 100: ValidationError("window too narrow") をthrow

## 制約

- 外部依存なし（Redis等）— インメモリで動作すること
- ロックなしでスレッドセーフ（アトミックなMap操作を使う）
- メモリ: リーク防止のため2x windowMs より古いエントリを削除する

## テストケース（必須合格）

- 新規リミッター: { allowed: true, remaining: limit - 1 } を返す
- 上限に達した: { allowed: false, remaining: 0 } を返す
- ウィンドウ経過後: カウンターリセット、{ allowed: true, remaining: limit - 1 }
- 上限時の並行リクエスト: ちょうどlimit件のみ許可、それ以上は不可

実行:

codex --approval-mode files-only \
  --model o4-mini \
  "specs/rate-limiter.md のスペックを実装する。
   実装: src/utils/rateLimiter.ts
   テスト: tests/rateLimiter.test.ts
   生成後にテストを実行し、失敗があれば修正してから完了とする。"

AGENTS.mdチューニング:

## スペック駆動生成ルール

スペックファイルから実装する場合:
1. コードを書く前にスペックを全文読む
2. スペックに記述された内容のみ実装する — 便利なメソッドの追加や
   要件外の振る舞いの追加はしない
3. 記載されたテストケースと、明示されていない境界条件もカバーするテストを生成する
4. 完了報告前にテストを実行する
5. スペックに曖昧または矛盾がある場合は、推測で実装せず
   具体的な問題を報告して止まる

スペックファイルは specs/ に置く。実装は src/ の既存構造に従う。
テストは src/ の構造をミラーする。

「レートリミッターを書いて」との違い: スペックアプローチは、生成を始める前に正確な振る舞いを言語化することを強制する。これによりAI生成コードの最も一般的な失敗モード—技術的には動くが実際に必要だったことをしていないコード—を防ぐ。

パターン3: テストファーストリファクタ

概要: 既存コードに触れる前に、Codexが現在の振る舞いに対する包括的なテストスイートを生成する。その後のリファクタリングはこのスイートをリグレッションハーネスとして進める。全テストが通り、カバレッジが下がっていない状態で初めてリファクタ完了とする。

使いどころ: 既存テストカバレッジが薄いレガシーコードのリファクタ。モノリスからのサービス抽出。外部APIを変えずにデータモデルを変更する場合。

2フェーズ実行:

フェーズ1 — キャラクタリゼーションテスト生成:

codex --approval-mode never \
  --model o4-mini \
  "src/legacy/orderProcessor.ts のキャラクタリゼーションテストを生成する。
   
   カバレッジ要件:
   - すべてのpublicメソッド
   - すべてのエラーパス（try/catchブロックと条件throwを探す）
   - パラメータ型に基づいた各メソッドの最低3つのエッジケース
   
   ソースファイルは変更しない。
   テストは tests/legacy/orderProcessor.test.ts に書く。
   テストスイートを実行し、現在の実装に対してすべて通ることを確認する。
   報告: 生成したテスト数、達成したカバレッジ率"

フェーズ2 — テストスイートに対してリファクタ:

codex --approval-mode files-only \
  --model o4-mini \
  "src/legacy/orderProcessor.ts を以下の方針でリファクタする:
   1. DBクエリを src/repositories/orderRepository.ts に抽出する
   2. すべての console.log を削除する（src/utils/logger.ts を使う）
   3. コールバック形式の非同期をすべて async/await に変換する
   
   制約:
   - tests/legacy/orderProcessor.test.ts はコード変更なしで通り続けること
   - publicメソッドのシグネチャは変更しない
   - ファイルの外部エクスポートは変更しない
   
   大きな変更のたびにテストを実行する。
   テストが失敗している状態で次のリファクタステップに進まない。"

AGENTS.mdチューニング:

## リファクタルール

リファクタ前:
- 対象ファイルの既存テストカバレッジを確認: npm run test:coverage -- [file]
- カバレッジ < 70% の場合は先にキャラクタリゼーションテストを生成する

リファクタ中:
- 最後にまとめてではなく、論理的なステップごとにテストを実行する
- テストが失敗したら実装を修正する — テストが明らかに間違っていない限り
  テストを変更しない
- カバレッジの変化を報告する

リファクタリングは振る舞いを保持する変更。
新しい振る舞いはフィーチャーであり、スペックが必要。

テストファーストが優れている理由: リファクタ後に生成したテストはリファクタ後の実装をテストしがちだ。元のコードに対して書いたキャラクタリゼーションテストは実際の振る舞いを捕捉する—呼び出し元が依存しているかもしれない、ドキュメント化されていない振る舞いも含めて。

パターン4: マルチステップ計画

概要: 複数のファイル・サブシステム・順番に行う意思決定が必要なタスクに対して、Codexが実行前に明示的な計画を作る。各計画ステップは個別に検証可能。計画が承認されるまで実行は始まらない。

使いどころ: フルスタックアプリに新しいエンティティ型を追加する（スキーマ・マイグレーション・モデル・サービス・API・テスト・ドキュメント）。あるライブラリから別のライブラリへの移行。横断的なアーキテクチャ変更。

計画→実行プロトコル:

ステップ1 — 計画のみ生成:

codex --approval-mode never \
  --model o3 \
  "[機能の説明] の実装を計画する。
   
   出力フォーマット:
   - 実行順に番号付きのステップ
   - 各ステップ: 対象ファイル、変更の種類（作成/変更/削除）、
     前のステップへの依存関係、検証方法
   - 外部情報が必要なステップにフラグを立てる
   
   コードを書かない。ファイルを変更しない。計画のみ。"

ステップ2 — エディタで計画をレビューし、必要なら編集する。

ステップ3 — ステップごとの承認付きで実行:

codex --approval-mode files-only \
  --model o4-mini \
  "/tmp/feature-plan.md の実装計画を実行する。
   
   番号付きステップごとに:
   - 関連するテストを実行する
   - ステップの検証方法が通ることを確認する
   - 次のステップに進む前に何をしたか簡潔に述べる
   
   ステップが検証に失敗した場合は、失敗を報告して止まる。
   失敗したステップを補うために他のステップを変更しない。"

AGENTS.mdチューニング:

## 計画プロトコル

計画を依頼された場合（実装ではない）:
- 番号付きステップリストのみを出力する
- 各ステップ: ファイル、変更の種類、依存関係、検証を指定する
- 人間の判断が必要なステップには [DECISION REQUIRED] をマークする
- 計画中はコードを書かず、ファイルを変更しない

計画を実行する場合:
- 計画は不変として扱う（ステップが明示的に失敗した場合を除く）
- 各ステップ後に検証を実行する
- 失敗時はステップ番号と失敗の詳細を報告して止まる — 
  自律的に回復しようとしない

計画フェーズのモデル選択が重要: 計画にはo3（依存関係とエッジケースの識別に優れた幅広い推論）、実行にはo4-mini（高速・安価、明確に定義されたタスクに十分）を使う。フェーズ間でモデルを切り替えることは、Claude CodeやCursorが同等にサポートしていない実質的な最適化だ。

パターン5: 継続的インテグレーションゲート

概要: CodexがCIチェックとしてPRを自動レビューする。スタイルではなく（それはリンターが担当）、論理・セキュリティ・アーキテクチャ境界違反に特化。失敗したチェックはマージをブロックする。

使いどころ: 複数の開発者がAIツールでコードを生成するチームで、人間のレビュー前に2度目のAIパスが欲しい場合。

CIの実装（GitHub Actions）:

name: Codex Review Gate

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  codex-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Generate diff
        run: git diff origin/${{ github.base_ref }}...HEAD > /tmp/pr.diff

      - name: Run Codex review
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: |
          npm install -g @openai/codex
          codex \
            --ask-for-approval never \
            --sandbox=full \
            --model o4-mini \
            "$(cat .codex/ci-review-prompt.md)" < /tmp/pr.diff

      - name: Check review output
        run: |
          if grep -q "\[CRITICAL\]" /tmp/codex-review.md; then
            echo "Critical issues found:"
            cat /tmp/codex-review.md
            exit 1
          fi

ci-review-prompt.md は、そのコードベースで何がCRITICALな問題かを定義する。アーキテクチャ違反、SQLインジェクション経路、認証チェックの欠如など、チームが最も重視することを記述する。それ以外は助言として扱う。

パターン6: インクリメンタルドキュメント

概要: コードが変わるタイミングでCodexがドキュメントを生成する。後でまとめてではなく、変更直後に。これでドキュメントと実装の乖離を防ぐ。

使いどころ: ドキュメントが陳腐化しやすいチーム。APIサーフェスの変更が多いプロジェクト。「あとでドキュメント書く」が実現していないプロジェクト。

Gitフック（post-commit）:

#!/bin/bash
CHANGED=$(git diff HEAD~1 --name-only | grep -E '\.(ts|tsx|py|go|rs)$')

if [ -n "$CHANGED" ]; then
  codex \
    --ask-for-approval never \
    --model o4-mini \
    "以下のファイルで変更した関数のJSDoc/docstringを更新する:
     $CHANGED
     
     ルール:
     - 実装が変わった関数のドキュメントのみ更新する
     - まだ正確なdocブロックは変更しない
     - 新しい関数: 完全なdocblock生成（params, returns, throws, example）
     - 変更された関数: 関連セクションのみ更新
     
     実行: git add -u && git amend --no-edit" 
fi

パターン7: スキャフォールド→実装

概要: 大きな新機能に対して、Codexがまずファイル・ディレクトリ構造とインターフェース定義（空の実装）を生成し、その後各コンポーネントを個別に実装する。一気に大きな実装を埋めようとするときにAIエージェントが起こすコヒーレンス崩壊を防ぐ。

使いどころ: 新しいマイクロサービス。大きな新モジュール。5〜7ファイル以上をまたぐ機能。

フェーズ1 — スキャフォールド:

codex --approval-mode files-only \
  --model o3 \
  "[機能名] モジュールをスキャフォールドする。
   
   作成するもの:
   - AGENTS.mdの規約に従ったディレクトリ構造
   - すべてのデータ型のTypeScriptインターフェースファイル
   - 関数シグネチャと戻り値の型（本体は // TODO: implement）
   - describeブロックとit()スタブを持つテストファイル（空）
   - モジュールが適切に接続されるexport文
   
   関数本体を実装しない。ロジックを書かない。
   スキャフォールドは tsc --noEmit でコンパイルが通ること。"

フェーズ2 — 依存関係順に実装:

# 依存関係が少ないモジュールから順に実装する
codex --approval-mode files-only \
  --model o4-mini \
  "src/[feature]/repository.ts を実装する。
   
   インターフェースは src/[feature]/types.ts に定義されている。
   テストスタブは tests/[feature]/repository.test.ts にある —
   実装と並行してテストも埋めていく。
   実装後にテストを実行し、失敗があれば修正する。"

AGENTS.md チューニング総論

上記のパターンは、コマンド・プロジェクト構造・規約といった基本的なAGENTS.mdの上に、ワークフロー固有の指示レイヤーを追加する。

ユニバーサルとワークフロー固有を分ける:

# AGENTS.md

## Commands
[ユニバーサル]

## Project Structure
[ユニバーサル]

## Conventions
[ユニバーサル]

---

## ワークフロー指示

各プロンプトが参照する専用セクション。
プロンプトがセクションを参照していない場合は
上記のユニバーサル指示のみ適用する。

### レビューモード
[パターン1参照]

### スペック駆動モード
[パターン2参照]

### リファクタモード
[パターン3参照]

### 計画モード
[パターン4参照]

32 KiB予算問題:

ユニバーサル + 全ワークフロー指示でAGENTS.mdが8〜12 KBになっても、デフォルト32 KiBの制限内にはまだ余裕がある—ただしグローバルの ~/.codex/AGENTS.md が軽ければの話。

グローバルAGENTS.mdのルール: 3 KB以下。個人の設定とデフォルトのみ。プロジェクト固有の内容を書かない。

指示の有効性を測る:

codex --ask-for-approval never \
  "このセッションで読み込んだ指示をセクション別にまとめよ。
   次に、この指示を踏まえてプロジェクトで私が変えるべき
   上位3つを教えよ。"

Codexが主要な制約を正確にまとめられない場合、指示が届いていない。よくある原因: ファイルが見つかっていない（パスの誤り）、サイズ超過によるトランケーション（グローバルファイルが大きすぎる）、制約として解析できないほど曖昧な指示。

Codex CLI vs Claude Code vs Cursor

スペックシートの比較ではなく、実際のワークフローパターンでどのツールが優れているかで比較する。

Codex CLIが最も得意なこと: 長時間の自律タスク、CI統合、構造化した計画→実行ワークフロー、自動承認の粒度を細かく制御したいケース。o3計画→o4-mini実行のモデル切り替えは、Claude CodeやCursorが同等にサポートしていない実質的なコスト・品質の最適化だ。

Claude Codeが最も得意なこと: 広大なリポジトリコンテキストが必要なタスク（大規模コードベースに対して1Mコンテキストウィンドウは実質的な差になる）、Claude固有のフックとメモリシステムを使ったCLAUDE.md設定、Anthropicのスタック上のチーム。

Cursorが最も得意なこと: 変更をコンテキストで確認しながらのインタラクティブな編集、IDEとの統合がオートメーション以上に重要なチーム、ターミナル出力よりエディタ内ヒントが有益な開発者。

実用的な答え: Codex CLIとClaude Codeは競合よりも補完の関係にある。Codex CLIが自律的な自動化とCIゲートを担い、Claude Codeが開発者がループ内にいる探索的なセッション作業を担う。AGENTS.mdとCLAUDE.mdは重複する役割を持ち、内容を共有することも合理的な選択だ。

コスト最適化

Codex CLIのコストはサブスクリプション料金ではなくAPIコール量でスケールする。そのためコスト最適化はより重要で、かつ制御しやすい。

パターン別モデル選択

最大のコストレバーはタスクにモデルを合わせること:

本当に価値があるところだけo3を使い、それ以外はo4-miniにすると、一様にo3を使う場合と比べてコストを60〜70%削減できることが多い。

コンテキストを積極的にスコーピングする

Codexは指定されたファイルを読む。ファイルが多いほどトークンが増える。

• インラインレビュー: diffのみを渡す。ファイル全体は不要
• スペック駆動生成: スペックとそれが依存するインターフェースのみ
• テストファーストリファクタ: 対象ファイルと直接的なimportのみ
• マルチステップ計画: 影響範囲のファイルリスト。全ファイルではない

.codexignore を使って常にコンテキストから除外するものを指定する: ビルド成果物、生成ファイル、大容量データファイル。

よくある失敗パターンとFAQ

Q: AGENTS.mdの指示をCodexが守らない

頻度順の一般的な原因:

1. ファイルが見つかっていない: サマリーチェックを実行する（codex --ask-for-approval never "読み込んだ指示をまとめよ"）。AGENTS.mdの内容が出てこなければ、ファイルが検索されていない — パス、作業ディレクトリ、Codexホームを確認する。

2. サイズ制限によるトランケーション: グローバルAGENTS.mdが大きすぎてプロジェクトレベルの指示が32 KiBの制限を超えている。wc -c ~/.codex/AGENTS.md を確認して3 KB以下に保つ。

3. 指示が曖昧すぎる: 「ベストプラクティスに従え」は指示ではない。「完了報告前にnpm run lintを実行せよ」は指示だ。曖昧なルールは具体的で確認可能なアクションに書き換える。

Q: 長時間のマルチステップタスクでドリフトが起きて一貫性がない結果になる

パターン4（マルチステップ計画）とパターン7（スキャフォールド→実装）で最も多い失敗モードだ。2つの修正策:

まずチェックポイントを使う。各フェーズを状態ファイルを書くCodexコールで終了させる: "現在の実装状態を .codex/checkpoint.md に書く — 完了したこと、残ったこと、行った仮定。" 次のフェーズはこのチェックポイントを読むことから始める。

次に制約を前倒しにする。実行全体を通じて重要な制約はAGENTS.mdに入れる。最初のプロンプトだけにある制約は、コンテキストが中間出力で埋まるにつれて「忘れられる」ことがある。

Q: 指示しなかったファイルをCodexが変更することがある

対処法を侵襲性の低い順に:

1. --sandbox=files-only はカレントディレクトリ内のファイルへの書き込みを制限する。ほとんどのワークフローにはこれで十分。
2. AGENTS.mdに明示的な境界を追加する: "明示的に指示されない限り src/ と tests/ 以外のファイルを変更しない。" サンドボックスと組み合わせると効果的。
3. レビューフェーズを使う: パターン1（インラインレビュー）をCodex自身の出力に対して実行する。これで意図しない変更をコミット前に捕捉する。

Q: 自動化されたCodexワークフローで認証情報を扱う方法は？

認証情報をAGENTS.mdやプロンプトに書かない。上記のパターンで --sandbox=full フラグを使っているのは、ネットワークアクセスを無効にするためだ。プロンプトインジェクション攻撃が発生しても、これによりCodexがデータを外部送信することを防げる。

CIワークフローでサービス認証情報が必要な場合は環境変数として渡し、AGENTS.mdでは変数名で参照する: "DB接続: $DATABASE_URL（環境変数に設定済み、ハードコード禁止）" Codexは実際の値をコンテキストに持たずに変数名を生成コードに反映できる。

Q: テストファーストリファクタが遅い。もっと速い方法はないか

キャラクタリゼーションテスト生成フェーズは中規模モジュール（200〜500行）で通常2〜5分かかる。それが遅すぎる場合の代替: 既存のカバレッジツールで既テストのものを見つけ（npm run test:coverage）、カバーされていない行だけCodexにテストを追加させる。これは速いが振る舞いのベースラインとしてはより不完全になる。

長い答え: その遅さに意味がある。徹底的なキャラクタリゼーションテストのみが、あなたもCodexも気づかない形でリファクタが振る舞いを変えることを防ぐ。より速いターンアラウンドが必要なら、テストではなくリファクタのスコープを小さくする。

上記のパターンは網羅的なリストではない—実際のワークフローに組み込めるほど信頼性が確認されたものを選んでいる。Codex CLIの進化に伴って実行パターンは変化するが、根本的な原則は変わらない: タスク・制約・検証方法を精密に定義するほど、Codexは一貫して有用な結果を出す。

実際のリポジトリからのAGENTS.mdの例は ルールギャラリー で。本記事のすべての基盤となる設定の基本は AGENTS.md セットアップガイド で確認してほしい。