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

> Codex の subagent に向く作業の見分け方、依頼文の作り方、App・CLI・IDE での監視、権限継承、custom agent と最終検証までを実務目線で解説します。

- Source: https://www.aifreeapi.com/ja/posts/codex-subagents
- Language: ja
- Published: 2026-08-16
- Updated: 2026-08-16
- Publisher: AI Free API (https://www.aifreeapi.com)

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

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

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

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

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

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

![Codex の探索・診断・実装・検証を依存関係に沿って受け渡す設計](https://www.aifreeapi.com/posts/ja/codex-subagents/img/relay-design.webp)

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

「複数の 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 の制御マップ](https://www.aifreeapi.com/posts/ja/codex-subagents/img/approval-map.webp)

実務では、探索・レビュー・ドキュメント確認は 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 ガイド](/ja/posts/codex-config-toml)を参照してください。

## 最後はメインスレッドが証拠を開く

統合された文章が整っていても、正しいとは限りません。実行した test target、到達可能な security path、探索範囲、参照した一次資料をメインスレッドが確認します。事実、推論、提案を分け、相反する指摘は多数決ではなく証拠で解消します。

良い subagent workflow では、要求・決定・最終責任がメインスレッドに残り、ノイズの多い中間作業だけが限定された thread に移ります。並列化は独立性があるときに経過時間を減らせますが、統合結果の検証を省く機能ではありません。

委譲方法ではなく coding agent 自体を選んでいる段階なら、[Claude Code と Codex の比較](/ja/posts/claude-code-vs-codex)で作業スタイルの違いから判断できます。