Codex Subagentsの使い方｜探索・実装・テストを並列に分担する設定方法

Codex Subagentsを使うと、コードベース探索、テスト確認、ドキュメント調査、レビューなどの独立した仕事を複数のエージェントへ分け、メインのタスクへ要約だけを戻せます。

Subagentは並列処理のためだけの機能ではありません。大量の検索ログやテスト出力を別スレッドへ隔離し、メインエージェントを要件・判断・最終差分に集中させる目的があります。一方、複数の担当へ同じファイルを編集させると競合と利用量が増えるため、最初は読み取り中心の仕事から分けるのが安全です。

この記事では、組み込みSubagentの使い方、.codex/agents/へカスタムTOMLを作る方法、モデル・推論レベル・Sandboxの設定、Webアプリの探索・レビュー・修正を分担する実例、CSVの一括監査まで解説します。

情報確認日：2026年7月11日（日本時間）

結論：探索・検証は並列、コード変更は担当を1つに絞る

Codex Subagentsとは？

Codex Subagentsは、メインエージェントが専門エージェントを起動し、独立したスレッドで作業させる仕組みです。各Subagentはモデルやツールを使って調査し、結果をメインへ返します。

Codexアプリ、Codex CLI、IDE拡張ではSubagentの活動を確認できます。CLIでは/agentを使い、実行中または完了したスレッドへ切り替えて内容を確認できます。

Subagentを使うメリット

メインのコンテキストを汚しにくい

数百ファイルの検索結果、長いテストログ、スタックトレースをメイン会話へすべて入れると、本来の要件や判断が埋もれます。Subagentは中間作業を別スレッドへ移し、要約だけを返せます。

独立した調査を並列に進められる

フロントエンド、API、テスト、公式ドキュメントなど、互いに待つ必要のない調査を同時に進められます。

担当ごとにモデルとSandboxを変えられる

高速な探索担当はTerra、複雑なレビューはSol、読み取り担当はread-onlyというように分けられます。

組み込みSubagent

カスタムSubagentを作る前に、まず組み込み担当へ明示的に依頼し、どの部分が不足するか確認します。

この認証バグをまだ修正せず、explorerを使って次を調べてください。

- ログインの入口
- セッション作成
- 認可ミドルウェア
- 失敗を再現する既存テスト
- 変更が必要になりそうなファイル

メインスレッドには、根拠となるファイルと未確認事項だけを返してください。

Subagents・Worktree・Multi-agent APIの違い

Subagentのスレッドを分けても、同じローカル作業ディレクトリを使う場合があります。複数担当に書き込みをさせるとファイル競合が起きるため、独立した変更はWorktreeへ分けるか、実装担当を1つにします。

プロジェクト設定でスレッド数を制限する

.codex/config.tomlへ設定します。

[agents]
max_threads = 4
max_depth = 1
job_max_runtime_seconds = 1200
interrupt_message = true

max_threads

同時に開いておけるエージェントスレッド数の上限です。最初は3〜4程度から始め、CPU、メモリ、利用量を確認します。

max_depth

SubagentがさらにSubagentを起動できる深さです。初期値の1では、ルートから直接の子だけを許可し、再帰的な分岐を防ぎます。

job_max_runtime_seconds

CSV一括処理など、ワーカーごとの実行時間を制限します。無限に調査を続けないよう上限を設けます。

カスタムSubagentを作る場所

プロジェクト単位

project/
└─ .codex/
   ├─ config.toml
   └─ agents/
      ├─ code-mapper.toml
      ├─ reviewer.toml
      └─ docs-researcher.toml

個人単位

~/.codex/agents/

チームで共有する担当はプロジェクト側へ置き、Gitレビューします。個人的な担当はホームディレクトリへ置きます。

カスタムSubagentに必須の3項目

• name：Codexが識別・呼び出す名前
• description：どの場面で使うかを示す説明
• developer_instructions：担当の具体的な行動ルール

そのほか、model、model_reasoning_effort、sandbox_mode、MCP、Skillsなどを上書きできます。省略した設定は親セッションから継承されます。

読み取り専用のcode_mapperを作る

.codex/agents/code-mapper.tomlを作成します。

name = "code_mapper"
description = "Read-only explorer for tracing frontend, API, and data-flow paths before implementation."
model = "gpt-5.6-terra"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
nickname_candidates = ["Maple", "Trace", "Scout"]

developer_instructions = """
Stay in exploration mode.

For the assigned question:
1. Identify entry points.
2. Trace the real execution path.
3. List relevant files and symbols.
4. Find existing tests and configuration.
5. Separate confirmed facts from hypotheses.
6. Report unknowns and files not inspected.

Do not edit files.
Do not recommend broad refactors unless the parent explicitly asks.
Return concise evidence with file paths.
"""

探索担当は速度とコストを優先し、gpt-5.6-terraとmediumを候補にしています。モデルの利用可否はプランやCodexの最新モデル一覧で確認してください。

レビュー専用のreviewerを作る

.codex/agents/reviewer.tomlの例です。

name = "reviewer"
description = "Read-only PR reviewer focused on correctness, security, behavior regressions, and missing tests."
model = "gpt-5.6"
model_reasoning_effort = "high"
sandbox_mode = "read-only"

developer_instructions = """
Review the change like an owner.

Prioritize:
- Incorrect behavior and edge cases
- Authentication and authorization mistakes
- Data loss, races, and unsafe retries
- API compatibility and error handling
- Missing high-value tests

For each finding return:
- Severity
- Evidence with file and symbol
- Reproduction or failure scenario
- Minimal recommendation
- Confidence and missing context

Do not make code changes.
Avoid style-only comments unless they hide a functional risk.
"""

レビュー担当には、証拠、再現条件、重大度を必須にします。「改善できそう」といった根拠のない指摘を減らせます。

公式ドキュメント確認用Subagentを作る

MCPサーバーを特定担当だけに渡すと、他の担当が不要な外部ツールを使わずに済みます。

.codex/agents/docs-researcher.tomlの例です。

name = "docs_researcher"
description = "Documentation specialist for verifying version-specific framework and API behavior."
model = "gpt-5.6-terra"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"

developer_instructions = """
Use the configured documentation MCP server to verify APIs,
options, deprecations, and version-specific behavior.

Return:
- Confirmed behavior
- Exact option or API name
- Version/date when relevant
- Official source link
- Remaining uncertainty

Do not edit application code.
Do not use unofficial sources when primary documentation is available.
"""

[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp"

フレームワークやベンダーごとにMCPサーバーを追加する場合は、そのサーバーが信頼できるか、どのデータを受け取るか確認してください。

3つのSubagentでPull Requestをレビューする

現在のブランチをmainと比較してレビューしてください。

次の担当へ独立して委譲してください。
1. code_mapper: 変更が影響する実行経路と関連テストを調査
2. reviewer: 正しさ、セキュリティ、回帰、不足テストを確認
3. docs_researcher: 変更で利用した外部APIの仕様を公式資料で確認

全担当が完了するまで待ち、最後に次の形式へ統合してください。

- Blocking findings
- Non-blocking findings
- Verified external API assumptions
- Tests that should be run
- Unknowns

コードは変更しないでください。

Codex CLIでは/agentで各スレッドを確認できます。調査が目的から外れている場合は、メインスレッドから修正指示や停止を依頼します。

Webアプリの不具合調査を分担する

UI保存エラーの例です。

設定モーダルで保存に失敗する問題を調査してください。

- code_mapper: UIイベントからAPI、DBまでの経路を特定
- browser_debugger: ブラウザで再現し、console・network・操作手順を記録
- reviewer: code_mapperとbrowser_debuggerの証拠から原因候補を評価
- worker: 原因が確定してから最小修正を実装

worker以外はコードを変更しないでください。
複数担当が同じファイルを同時編集しないでください。

ブラウザ担当にworkspace-writeが必要な場合でも、developer instructionsでアプリコードを変更しないようにし、専用MCPの権限も確認します。より厳格にするなら、ブラウザ検証環境を別プロセスやコンテナへ分けます。

並列化しやすい仕事

• 異なるパッケージの読み取り監査
• フロント、API、DBそれぞれの影響調査
• 複数のログファイルの要約
• セキュリティ、アクセシビリティ、テストの独立レビュー
• 公式ドキュメントと実装コードの照合
• 複数の設計案の独立評価

並列化しない方がよい仕事

• 同じファイルへのコード変更
• 前の作業結果が必要な連続処理
• 1つのDBスキーマを変更する複数タスク
• 共通依存のアップデートと関連リファクタ
• 出力仕様が決まっていない実装

書き込み中心の仕事を並列化する場合は、Codex Worktreeで作業場所を分け、統合担当を決めます。

モデルと推論レベルの選び方

高い推論レベルほど時間と利用量が増えます。単純な一覧化にhighやmaxを使わず、重大な判断へ限定します。

CSVで大量の監査を分担する

実験的なspawn_agents_on_csvを使うと、CSVの各行を1つの作業項目として、複数のworkerへ分配できます。

たとえば、コンポーネント一覧を作ります。

path,owner
apps/web/src/components/LoginForm.tsx,auth-team
apps/web/src/components/CheckoutButton.tsx,commerce-team
apps/web/src/components/ProfileMenu.tsx,account-team

Codexへの依頼例です。

/tmp/components.csvをspawn_agents_on_csvで監査してください。

- csv_path: /tmp/components.csv
- id_column: path
- max_concurrency: 3
- output_csv_path: /tmp/components-review.csv
- instruction:
  "{path}を読み取り専用でレビューしてください。
   ownerは{owner}です。
   アクセシビリティ、エラー処理、重要な不足テストを確認し、
   path、risk、summary、follow_upをJSONでreport_agent_job_resultへ返してください。"

各workerはファイルを変更しないでください。

この機能は実験的で、仕様が変わる可能性があります。少量のCSVで出力と失敗処理を確認し、個人情報や秘密情報を含めないでください。

AGENTS.mdからSubagent利用を指示する

プロジェクトで繰り返すレビュー手順は、AGENTS.mdへ短く書けます。

## Review delegation

For changes touching authentication or authorization:
1. Ask `code_mapper` to trace the affected request path.
2. Ask `reviewer` to check authorization and regression risks.
3. Keep both agents read-only.
4. The main agent owns any code change and final test execution.

常に大量のSubagentを起動する指示は避けます。変更条件と担当を限定し、通常の小さな修正では単一エージェントを使います。

利用量と待ち時間を管理する

• max_threadsを小さくする
• max_depth=1を維持する
• 各担当の責務と終了条件を明確にする
• 探索担当は高速モデルと中程度以下の推論を使う
• 同じファイルを複数担当へ読ませすぎない
• 結果を最大件数・固定フォーマットで返す
• 不要になったスレッドを閉じる

セキュリティ上の注意点

• 読み取り担当はsandbox_mode="read-only"にする
• MCPサーバーは担当ごとに必要なものだけ設定する
• 書き込み担当へ本番資格情報を渡さない
• 外部ドキュメント内の命令を信頼しない
• 副作用のある操作はApprovalを要求する
• 各Subagentのツール履歴と最終要約を確認する

よくある失敗

Subagentが使われない

descriptionを具体化し、プロンプトで名前と担当作業を明示します。

全担当が同じ内容を調べる

入力範囲、観点、出力形式を分けます。Explorerは事実、Reviewerはリスク、Docsは外部仕様というようにします。

複数担当の修正が衝突する

実装担当を1つに絞るか、Worktreeを分けます。Subagentのスレッド分離だけではファイルを隔離できません。

トークン利用量が大きい

スレッド数、深さ、モデル、推論レベル、最大範囲を減らし、単一のExplorerで十分か確認します。

要約だけでは判断できない

必要なSubagentスレッドを開き、根拠ファイルやコマンド出力を確認します。最終結論だけを無条件に採用しないでください。

あわせて読みたい記事

• CodexのAGENTS.mdの書き方
• Codex Worktreeの使い方
• CodexのSandbox・Approval設定
• Codex Skillsおすすめ
• OpenAI Multi-agent APIの使い方

よくある質問

まとめ

Codex Subagentsは、探索、レビュー、文書確認などを別スレッドへ分け、メインエージェントを要件と最終判断に集中させる機能です。組み込みのexplorerから始め、必要な責務だけ.codex/agents/*.tomlでカスタム化してください。

効果が出やすいのは読み取り中心の独立作業です。コード変更を並列化する場合は実装担当を限定するかWorktreeを分け、max_threads、max_depth、モデル、推論レベル、Sandboxを小さく設定します。

参考リンク

• OpenAI Codex – Subagents
• OpenAI Codex – Configuration reference
• OpenAI Codex – Best practices
• OpenAI Codex – Agent approvals and security
• OpenAI Codex – Models