Codex サブエージェントの使い方：並列化より先に決めること

AI Free API Team

•2026年8月16日•8 min read•AI Development Tools

サブエージェントを増やす前に、依存関係、書き込み範囲、権限、返却する証拠、最終判断者を決めます。

Codex のメインスレッドから探索、テスト、レビューの独立した作業へ委譲し、要約を戻す流れ

Codex のサブエージェントが効くのは、大きい仕事ではなく、独立して終えられる仕事です。リポジトリ探索、テスト失敗の分類、ログの要約、観点別レビューは分けやすい一方、同じ型定義を前提に複数の呼び出し元を同時編集する作業は、見た目ほど独立していません。

現行のローカル Codex では subagent workflow は標準で有効です。App、CLI、IDE で直接委譲を頼めるほか、適用される AGENTS.md や skill の指示からも起動できます。ただし、各 subagent は自分のモデル処理と tool call を行うため、同等の single-agent 実行より token 消費は増えます。OpenAI の公式 Subagents ドキュメントも、最初は探索、テスト、triage、要約など read-heavy な仕事を推奨し、並列書き込みには注意を求めています。

分ける基準は「役職」ではなく依存関係

reviewer や explorer という名前を付けただけでは、仕事は独立しません。委譲前に次の五つを決めます。

その agent だけで読める入力範囲
他の agent の未確定判断を待たずに終えられるか
変更するなら、どのファイルを単独で所有するか
何を返せば完了か
返却後の判断を誰が持つか

たとえば UI 保存失敗の調査なら、browser で再現する仕事、frontend と backend の実行経路を読む仕事、関連 API の仕様を確認する仕事は並行しやすいでしょう。しかし、原因が分かる前から三者に修正を許可すると、状態管理、API、テストが別々の仮説で変わり始めます。探索は並列、修正は診断後に一人へ、というリレーの方が安全です。

依頼文には待機条件と証拠の形も書く

「複数の agent で調べて」だけでは、重複と生ログが増えます。以下のように、分担、権限、待機、返却を一つの契約にします。

text
現在の branch を main と比較し、3つの subagent に委譲してください。

- explorer: 変更が通る実行経路を read-only で特定する
- reviewer: correctness、security、missing tests を確認する
- test_agent: 関連 test target だけを実行し、失敗を再現性別に分類する

全員が終わるまで待つこと。ファイルは変更しないこと。
最終回答では、確認済みの事実、仮説、file reference、実行コマンド、
未確認範囲を分け、重複した指摘を統合してください。

重要なのは agent 数ではありません。メインスレッドが比較できる同じ証拠形式と、「全員を待つ」「書かない」「未確認範囲を残す」という停止条件です。実装が必要なら、その後に worker へ狭いファイル範囲と検証コマンドを渡します。

権限は親から引き継がれる

ローカル subagent は現在の sandbox または permission mode を継承します。App と IDE では、委譲を頼む前に composer 下の permission mode を確認します。対話型 CLI では、表示中でない agent thread から approval が出ることがあり、overlay に発生元が表示されます。o でその thread を開いてから許可・拒否を判断できます。新しい approval を表示できない non-interactive 実行では、許可が必要な action は失敗し、エラーが親へ戻ります。

custom agent ファイルに sandbox_mode を書いても、親の live override を無視できるわけではありません。session 中の /permissions 変更や起動時の権限選択は spawn 時に再適用されます。したがって、subagent は自動的な隔離境界ではありません。

親スレッドの権限、subagent の実行、approval、結果確認を結ぶ Codex の制御マップ

実務では、探索・レビュー・ドキュメント確認は read-only、実装は必要最小限の write scope とし、同じファイルを複数 worker に持たせません。外部送信、削除、credential、software install は、並列化とは別の明示的な判断として残します。

進捗を見る場所はクライアントごとに違う

Codex App：メインチャットの activity から subagent thread を開き、Codex に steer、stop、close を頼めます。
Codex CLI：/agent で active な agent threads を切り替え、進行中の内容や結果を確認します。
IDE extension：background-agent panel が利用できる場合、状態表示、停止、個別 thread の表示ができます。

agent が依頼外のファイルを触り始めた、証拠ではなく大量の出力を返している、前提となる仕様が別 agent の発見で崩れた、という時点で介入します。完成した要約まで待つ必要はありません。

Custom agent は繰り返す責任だけに作る

Codex には default、worker、explorer が組み込まれています。毎回同じ責任を持たせ、モデル、reasoning effort、sandbox、MCP、指示を安定させたい場合に custom agent を定義します。個人用は ~/.codex/agents/、project 用は .codex/agents/。各 TOML には name、description、developer_instructions が必須です。

toml
name = "api_contract_reader"
description = "変更対象 API の契約と実装利用箇所を読む agent。"
model = "gpt-5.6-terra"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
developer_instructions = """
公式仕様と実際の call path を確認する。
file reference、根拠、未確定事項、親が決める点を返す。
コードは変更しない。
"""

現在の公式ガイダンスでは、難しい多段判断は gpt-5.6、速い read-heavy 支援は gpt-5.6-terra、明確で反復的な狭い仕事は gpt-5.6-luna が出発点です。利用可否は account、認証経路、client によって変わるため、保存した model ID は定期的に見直します。

[agents] では有効化、同時 thread 数、subagent の既定 model と reasoning effort などを設定できます。一般的な user/project/profile/CLI の優先順位まで確認したい場合は、別の Codex config.toml ガイドを参照してください。