OpenAI Codex応用 自律開発エージェント

full-autoモードの設計と安全運用

full-autoの仕組み

Codex CLIには3つの実行モードがあります。suggest(提案のみ)、auto-edit(ファイル編集を自動承認)、full-auto(全操作を自動実行)。full-autoモードではCodexがサンドボックス内でシェルコマンドの実行からファイル編集までを一気に行います。人間の承認ステップを飛ばすため速度は劇的に向上しますが、その分だけ運用設計が問われます。

安全性の基盤

full-autoが「自由にやりたい放題」にならない理由は、サンドボックスの存在です。

• ネットワーク隔離 -- 外部への通信を遮断。悪意のあるコードが実行されても情報流出しない
• ファイルシステム隔離 -- codex.tomlの writable_roots で書き込み可能なディレクトリを明示的に制限
• プロセス隔離 -- ホストOSへの影響を最小化するコンテナ技術

それでも必要な注意点

サンドボックスがあっても万能ではありません。意図しないファイルの大量削除、src配下の想定外の書き換え、テストコードの上書きといったリスクは残ります。APIコール数が膨れ上がるケースもあるため、トークン消費のモニタリングは欠かせません。

承認フローの設計

すべてのタスクにfull-autoを適用するのは危険です。タスクの性質に応じて実行モードを使い分ける判断基準を持つことが運用の要になります。

ロールバック手順

full-autoで意図しない変更が起きた場合、gitが最後の砦です。コマンドの引き出しを整理しておきます。

full-auto適用の判断フロー

%%{init:{'theme':'dark','themeVariables':{'primaryColor':'#00A5BF','primaryBorderColor':'#007A8F','primaryTextColor':'#e8e8e8','lineColor':'#00A5BF','secondaryColor':'#1a1a1a','background':'#141414','mainBkg':'#1a1a1a','nodeBorder':'#00A5BF'}}}%%
flowchart TD
  A["タスクを受領"] --> B{"既存コードへの\n影響は?"}
  B -->|大きい| C{"テストは\n存在する?"}
  B -->|小さい/新規| D["full-auto OK"]
  C -->|ある| E["auto-edit\n差分確認後コミット"]
  C -->|ない| F["先にテスト生成\nfull-autoでOK"]
  F --> E
  B -->|設定/インフラ| G["suggest\n手動確認必須"]

監視とログ

full-auto実行中はターミナルにリアルタイムでログが流れます。--watchフラグを付けると、Codexが実行した各ステップとその結果を逐一表示します。想定外のファイルに触れていないか、エラーが発生していないかをログで追えるようにしておくのが運用の基本です。

実行ログの読み方

full-autoモードの実行後に「何が行われたか」を把握する方法は複数あります。

AGENTS.md高度設計 -- マルチエージェント指示

階層的AGENTS.md

AGENTS.mdはプロジェクトルートに1つ置くだけでも効果がありますが、サブディレクトリごとに配置するとCodexの精度が格段に上がります。ルートにはプロジェクト全体の方針、サブディレクトリにはその領域固有のルールを書く。人間のチームで言えば、全社ルールと部門ルールの関係に近い構造です。

ファイルスコープ制御

サブディレクトリのAGENTS.mdに「このディレクトリ以下のファイルだけを対象にする」と明記すると、Codexが別ディレクトリのファイルを勝手に触るリスクを抑えられます。マイクロサービス構成やモノレポで特に効果的です。

マルチエージェント指示

複数のCodexインスタンス(あるいはClaude CodeやCopilot)が同時に同じリポジトリを編集する場面が出てきます。衝突を防ぐために、AGENTS.mdにロック対象ファイルや編集優先順位を定義しておくと混乱が減ります。

AGENTS.md設計パターン集

CLAUDE.mdとの差異と互換性

大規模リファクタリング

AIによるリファクタリングが有効な場面

人間が嫌がる定型的な修正こそAIの得意領域です。

• 命名統一 -- camelCaseとsnake_caseの混在を一括修正
• コードスタイル統一 -- セミコロン有無、インデント幅の統一
• フレームワーク移行 -- Express to Fastify、Options API to Composition API
• 言語変換 -- JavaScript to TypeScript、Python 2 to Python 3
• 非推奨APIの置換 -- ライブラリのバージョンアップに伴うAPI変更

リファクタリング戦略

2つのアプローチがあります。段階的(ファイルを1つずつ処理)と一括(full-autoで一気に実行)。どちらを選ぶかはテストの充実度で決まります。

安全にリファクタリングするための前提

テストがないコードのリファクタリングは、目隠しで走るのに等しい。まずテストを書き、それからリファクタリングに入る。この順番は絶対です。Codexに「まずテストを書いて、その後リファクタして」と一度に指示できるのが、AIリファクタリングの強みでもあります。

%%{init:{'theme':'dark','themeVariables':{'primaryColor':'#00A5BF','primaryBorderColor':'#007A8F','primaryTextColor':'#e8e8e8','lineColor':'#00A5BF','secondaryColor':'#1a1a1a','background':'#141414','mainBkg':'#1a1a1a','nodeBorder':'#00A5BF'}}}%%
flowchart LR
  A["テスト確認"] --> B{"テストは\n十分?"}
  B -->|No| C["テスト自動生成"]
  C --> D["ブランチ作成"]
  B -->|Yes| D
  D --> E["リファクタリング\n実行"]
  E --> F["テスト実行"]
  F --> G{"全テスト\nパス?"}
  G -->|No| H["差分確認\n修正"]
  H --> E
  G -->|Yes| I["コードレビュー"]
  I --> J["マージ"]

段階的リファクタリングアプローチ

一度にすべてを変えると何が壊れたか特定できません。フェーズを分けて、各フェーズでテストを通す運用が安全です。

テスト自動生成と品質保証

テストカバレッジ目標の設定

カバレッジは高ければ良いというものではありませんが、低すぎるとリファクタリングの安全網が機能しません。プロジェクトの性質に応じた現実的な目標値を設定する必要があります。

• 行カバレッジ(Line Coverage) -- コードの何%が実行されたか。最もポピュラー
• ブランチカバレッジ(Branch Coverage) -- if/elseの各分岐がテストされたか。行カバレッジより厳格
• 関数カバレッジ(Function Coverage) -- 各関数が少なくとも1回は呼ばれたか

テスト種別とAI適性

Codexが生成するテストの品質

Codexはユニットテストの生成精度が高く、関数のシグネチャと実装を読み取ってhappy pathとエッジケースの両方を出してきます。ただし限界もあります。

• ビジネスロジックの意図理解 -- 「なぜこの計算式なのか」まではAIが理解できない。仕様書や要件定義をコンテキストに含める必要がある
• 複雑な状態遷移 -- ステートマシンのような複雑な状態管理のテストは、人間が遷移パターンを指定するのが確実
• 外部依存のモック -- DB接続やAPI呼び出しのモックは生成できるが、モックの粒度が粗い場合がある

マルチリポジトリ運用

モノレポでの活用

モノレポ(monorepo)では複数のパッケージが1つのリポジトリに同居します。ルートAGENTS.mdでプロジェクト共通ルールを定義し、各パッケージディレクトリにはパッケージ固有のAGENTS.mdを配置する。Section 02で学んだ階層構造がここで活きてきます。

マイクロサービスでの活用

マイクロサービスアーキテクチャでは各サービスが独立したリポジトリを持つ場合が多いですが、API仕様書(OpenAPI/Swagger)を共有コンテキストとしてAGENTS.mdから参照させることで、Codexがサービス間のインターフェースを理解できるようになります。

リポジトリ横断の変更

バックエンドのAPIインターフェースを変更したら、フロントエンドのAPIクライアントも更新が必要です。モノレポであればCodexに「APIの変更に合わせてクライアントも更新して」と指示するだけで、両方のコードを整合性を保って修正できます。

%%{init:{'theme':'dark','themeVariables':{'primaryColor':'#00A5BF','primaryBorderColor':'#007A8F','primaryTextColor':'#e8e8e8','lineColor':'#00A5BF','secondaryColor':'#1a1a1a','background':'#141414','mainBkg':'#1a1a1a','nodeBorder':'#00A5BF'}}}%%
sequenceDiagram
  participant Dev as 開発者
  participant Codex as Codex CLI
  participant API as api/
  participant Web as web/
  participant Shared as shared/

  Dev->>Codex: "ユーザーAPIにemailフィールドを追加して"
  Codex->>Shared: 型定義を更新(User型にemail追加)
  Codex->>API: APIエンドポイント更新
  Codex->>API: バリデーション追加
  Codex->>Web: APIクライアント更新
  Codex->>Web: フォームにemailフィールド追加
  Codex->>Dev: 全ファイルの変更完了
  Dev->>Dev: テスト実行で整合性確認

ツール横断ワークフロー -- Copilot/Claude Code併用

3ツールの得意領域

Copilot、Codex CLI、Claude Codeはそれぞれ異なる強みを持ちます。1つのツールに固執するより、場面に応じて使い分けたほうが生産性は確実に上がります。

実践的な併用パターン

ツール間のコンテキスト共有

3つのツールは互いの設定ファイルを読みません。共通ルールを別ファイルに切り出し、各ツールの設定ファイルから参照する形が現実的な運用です。

1日の開発フローにおけるツール使い分け

3ツールを時間帯やタスクの性質で使い分けると、それぞれの強みを最大限に引き出せます。

ポイントは「考える作業」にClaude Code、「大量処理」にCodex full-auto、「手を動かす作業」にCopilotという棲み分けです。

本番環境への適用 -- CI/CD統合、レビュー自動化

CI/CDパイプラインでのCodex利用

Codex CLIはターミナルで動くため、GitHub Actionsのワークフローに組み込めます。PR作成時に自動レビュー、コード品質チェック、テスト生成の提案をCodexに実行させるパイプラインが構築可能です。

GitHub ActionsでのCodex実行

APIキー管理

CI環境でCodexを動かすにはOpenAI APIキーが必要です。リポジトリのSettings > Secrets and variables > ActionsでOPENAI_API_KEYを登録してください。コードに直書きは厳禁。.envファイルをコミットするのも厳禁です。

コスト管理

CI実行ごとにトークンを消費します。PRが頻繁に作られるリポジトリでは、月あたりのAPI費用がかさむ可能性があります。

PRレビュー自動化の設計

%%{init:{'theme':'dark','themeVariables':{'primaryColor':'#00A5BF','primaryBorderColor':'#007A8F','primaryTextColor':'#e8e8e8','lineColor':'#00A5BF','secondaryColor':'#1a1a1a','background':'#141414','mainBkg':'#1a1a1a','nodeBorder':'#00A5BF'}}}%%
flowchart LR
  A["PR作成"] --> B["GitHub Actions\nトリガー"]
  B --> C["Codex CLI\nレビュー実行"]
  C --> D["レビューコメント\n自動投稿"]
  D --> E{"人間が\n最終判断"}
  E -->|Approve| F["マージ"]
  E -->|Request Changes| G["修正"]
  G --> A

総合ハンズオン: 既存プロジェクトのフルリファクタリング

ゴール

このコースで学んだ全要素を組み合わせ、1つのプロジェクトに対してCodexでフルリファクタリング + テスト生成 + ドキュメント作成 + CI/CDワークフロー構築を実行します。Section 01-07の集大成です。