TL;DR
- Codex の subagents は、単なる並列化ではなく、探索やログのノイズを親スレッドから切り離すための設計として理解したほうが本質に近い
- 公式仕様では、subagents は自動起動ではなく明示トリガー前提で、最初は exploration・tests・triage・summarization のような read-heavy タスクから始めるのが安全
- 2026年3月時点の実務観察としては、Skill に書くだけでは起動判断に効きにくい場面があり、AGENTS.md や明示プロンプトのほうが分業意図を通しやすい
はじめに
Codex の subagents を「マルチエージェント機能」とだけ理解すると、だいたい途中でズレます。
本当に効いているのは、並列数そのものではありません。効いているのは、探索メモ、テストログ、スタックトレース、コマンド出力のようなノイズを親スレッドから切り離し、メインエージェントを要件整理と意思決定に戻すことです。
OpenAI の公式ドキュメントでも、subagent workflows はメインエージェントを requirements, decisions, final outputs に集中させるための仕組みとして説明されています。2026年3月30日時点で読む限り、ここが出発点です。
この記事では、Codex の subagents を単体で理解します。似た話題として、構造比較は CodexのMulti-Agentsは何が違うのか？、運用設計は AIをチームメンバーとして働かせる運用、人間の承認設計は 人間が承認だけする半自動ワークフロー をあわせて読むとつながります。
1. subagents が解決するのは「速さ」より「コンテキスト汚染」
OpenAI の Subagent concepts では、メイン会話に探索ノートやテストログを流し込みすぎると、重要な要件や制約が埋もれてセッションの信頼性が落ちると説明されています。ここで出てくるのが context pollution と context rot です。
要点はシンプルです。
- 親スレッドには、要件、制約、意思決定、最終出力の文脈を残したい
- 途中のログや探索は、必要だがノイジーなので別スレッドに追い出したい
- 親には raw log ではなく要約だけ返したい
この設計にすると、メインエージェントは「何を決めるか」に集中しやすくなります。並列化は副次効果であって、本丸は判断品質を落としにくくすることです。
2. Subagents とは何か
公式の Subagents ページでは、Codex は specialized agents を parallel に走らせ、結果を 1 つの返答に集約できると説明されています。役割分担で見ると、こんな理解がしっくりきます。
| 役割 | 主な責務 |
|---|---|
| メインエージェント | 要件整理、優先順位づけ、最終判断、最終出力 |
| サブエージェント | 探索、テスト、ログ解析、観点別レビュー、要約 |
つまり、subagent は「親の代わりに全部やる別人格」ではなく、ノイズの多い補助作業を隔離して持つ作業スレッドです。
ここを外すと、「全部 subagent に投げればよい」という誤解になります。実際には、親の役割はむしろ重いです。何を分割し、何を最後に統合するかは親が握ります。
3. いちばん重要な前提: 自動起動ではない
これはかなり大事です。
OpenAI の公式仕様では、Codex は subagents を自動では起動しません。使いたいなら、ユーザーが明示的に「spawn two agents」「delegate this work in parallel」「use one agent per point」のように指示する必要があります。
たとえば PR レビューなら、次のように切ると扱いやすいです。
このブランチを parallel subagents でレビューしてください。
1つ目は security risks、2つ目は test gaps、3つ目は maintainability を担当。
3つとも終わるまで待って、カテゴリ別に file references 付きで要約してください。
この仕様から言えるのは、subagents は「賢く自動分業してくれる機能」ではなく、こちらが分業設計して初めて効く機能だということです。
4. 使い方は 3 パターンで押さえる
built-in agents
Codex には最初から次の built-in agents があります。
| Agent | 役割 |
|---|---|
default | 汎用フォールバック |
worker | 実装・修正向けの execution-focused agent |
explorer | read-heavy な探索向け agent |
最初はこの 3 つで十分です。特に explorer を「読むだけ」、worker を「手を動かす」と切り分けると、親スレッドに戻す情報の粒度を整えやすくなります。
custom agents
もっと実務的なのが custom agents です。公式では、~/.codex/agents/ か .codex/agents/ に TOML を置き、name、description、developer_instructions を必須として定義できます。model、model_reasoning_effort、sandbox_mode、mcp_servers、skills.config なども設定できます。
しかも OpenAI は、良い custom agent は narrow and opinionated だと明言しています。責務を狭くし、隣の仕事をしないようにしたほうがブレにくい、という思想です。
たとえば、こんな 3 分割はかなり扱いやすいです。
pr_explorer: 影響範囲と実行経路だけを追うreviewer: correctness / security / test coverage だけを見るdocs_researcher: 公式ドキュメントや MCP 経由の仕様確認だけに寄せる
その場での明示指示
TOML を作らなくても、その場で「2つ起動して、片方でテスト、片方で関連ファイル探索」のように明示すれば使えます。1 回限りの調査やレビューなら、これが最も軽いです。
5. まずどこで使うべきか
Subagent concepts では、parallel agents の出発点として read-heavy tasks が推奨されています。具体的には次のような作業です。
- exploration
- tests
- triage
- summarization
- 観点別 PR review
一方で write-heavy な並列実行は慎重に扱うべきとされています。複数の agent が同時にコードを書き換えると、競合や調整コストが増えやすいからです。
この方針はかなり現実的です。subagents の価値は「人数を増やして雑に速くすること」ではなく、観点ごとの推論密度を上げながら、親の文脈を守ることにあります。
より広いチーム運用として見たいなら、実践！マルチエージェント・デザインパターン も補助線になります。
6. モデル・設定・権限は役割ごとに分けて考える
公式ドキュメントでは、agent ごとに model と model_reasoning_effort を変えられます。例として、強い判断役には gpt-5.4、探索や supporting docs の処理には gpt-5.4-mini、低遅延の実行寄りには gpt-5.3-codex-spark を割り当てる例が出ています。
考え方は次のとおりです。
| 役割 | 向いている設定の考え方 |
|---|---|
| メインエージェント | gpt-5.4 など、判断と統合を重視 |
| 探索・読取担当 | gpt-5.4-mini など、広く軽く拾う |
| 小さな修正担当 | gpt-5.3-codex-spark など、低遅延の反復を重視 |
設定面では、まず次の 3 つを押さえれば十分です。
| 設定 | 役割 | 公式デフォルト / 目安 |
|---|---|---|
agents.max_threads | 同時に開ける agent thread 数の上限 | 6 |
agents.max_depth | ネスト深度の上限 | 1 |
agents.job_max_runtime_seconds | CSV fan-out jobs の既定タイムアウト | 必要に応じて調整 |
特に max_depth = 1 が大事です。親が子を起動するところまでは許しつつ、その先の深い再帰を抑えます。これはトークン消費、待ち時間、ローカルリソース消費、そして予測不能性を増やしすぎないためのガードレールと見るのが自然です。
さらに安全面では、subagents は親の sandbox / approvals の実行時設定を引き継ぎます。必要なら個別 agent を read-only に上書きできますが、基本は親子で一貫した権限モデルで動く設計です。
7. AGENTS.md と Skills は何が違うのか
ここは混ざりやすいので分けて考えたほうがよいです。
AGENTS.md
OpenAI の AGENTS.md ガイドでは、Codex はグローバルからプロジェクト、そしてカレントディレクトリに至るまで AGENTS.md を探索し、近い階層ほど後勝ちで指示を結合すると説明されています[公式値]（OpenAI Codex AGENTS.md 公式）。つまり AGENTS.md は、作業前から効く永続ルールです。
Skills
Skills は reusable workflows の形式です。公式では、Codex はまず各 skill の metadata だけを見て、必要だと判断したときだけ SKILL.md 本文を読みます[公式値]（OpenAI Codex Skills 公式）。起動方法は 2 つあり、明示呼び出しと、description に基づく implicit invocation です。
この差をざっくり言い切るなら、こうです。
AGENTS.md: 最初から読み込まれる運用ルールSkills: 関連性があるときに追加で読み込まれるワークフロー
ここを整理すると、「なぜ AGENTS.md の一言は効くのに、Skill の本文に書いた subagent 方針は効いたり効かなかったりするのか」という実務上の違和感を説明しやすくなります。
Claude Code との対比
Claude Code 側は同等の役割を Hooks / Subagents / Skills の 3 層で提供しています[公式値]（Claude Code 公式）。Codex の AGENTS.md は Claude Code の CLAUDE.md に対応し、Skills は両者でほぼ同じ意味で、Subagents もコンテキスト隔離という思想で揃っています。役割対比表は CLAUDE.md 最適化 - 役割分担表 と Skills対Subagents使い分け5軸 を参照。Claude Code 固有の Hook（deterministic 制御）に対応する仕組みは Codex 側ではまだ標準化されておらず、permission profiles や app-server の policy で代替している段階です（経験則）。ツール選定軸は 2026 年の AI コーディング自動運転最前線 を参照。
8. 2026年3月時点の観察として面白い点
ここから先は、公式仕様ではなく観察ベースです。再現条件やバージョンで変わりうるので、仕様として断言せずに読むのが安全です。
1. Skill に「必要なら subagent を起動」と書くだけでは効きにくい場面がある
これは説明可能です。Skills はまず metadata の description で暗黙起動され、本文は必要時にだけ読まれます。したがって、subagent を起動するかどうかの判断時点より後で本文が効いている可能性があります。少なくとも 2026年3月時点の運用では、会話文脈からの暗黙参照だけに期待すると分業意図が通りにくい場面があります。
2. AGENTS.md のほうが分業方針を通しやすく見える
これも AGENTS.md が作業開始前に結合される仕様と整合します。明示指示なしでも AGENTS.md に書いた方針が起動判断へ影響しているように見えるケースがありますが、これは公式に保証された「自動起動ルール」ではありません。実務では、AGENTS.md とユーザープロンプトを両方使って補強するくらいがちょうどよいです。
3. ネストを許すと、意図しない再分割が起きうる
たとえば backend 担当の子が、さらに frontend/backend に切ってしまうようなケースです。これは公式が max_depth=1 をデフォルトにしている理由と矛盾しません。再帰的に賢くなるというより、再帰的に予測しづらくなるからです。
9. 可視化すると理解が一気に進む
CLI だけだと、親が誰に何を委譲し、どの子が何を返したかは少し追いづらい場面があります。
その点、OpenAI の App Server ドキュメントでは、app-server は rich clients や独自統合向けのインターフェースで、authentication、history、approvals、そして streamed agent events を扱えると説明されています。つまり、親子の委譲や返却を観測するビューを自作できる余地があります。
もし subagents の理解を 1 段深めたいなら、「どう使うか」だけでなく「どう観測するか」をセットで考えるのが有効です。エージェント運用の可観測性は、結局あとから効いてきます。
10. 最初に試すならこの 3 ステップ
最後に、最小構成だけ置いておきます。
- PR レビューや不具合調査のような read-heavy タスクを 1 つ選ぶ
explorerとworkerを混ぜず、まずは「読む担当」だけを 2〜3 本に切るmax_depth=1のまま、親に返す出力形式を「要約 + file references」に固定する
たとえばこんな prompt から始めると安全です。
この変更を parallel subagents で確認してください。
1つ目は影響範囲の探索、2つ目はテスト不足、3つ目はドキュメント整合性を担当。
3つとも終わるまで待って、各担当の要点を file references 付きで要約してください。
コード修正は行わないでください。
このくらいの狭さなら、親の統合コストも暴れません。
FAQ
subagents は速くする機能ですか
速くなる場面はありますが、本質はそこではありません。公式仕様に沿って読むなら、主目的は noisy intermediate output を親スレッドから切り離し、メインエージェントを requirements, decisions, final outputs に集中させることです。
最初から custom agent を作るべきですか
最初は built-in agents で十分です。explorer と worker の違いが運用で見えてきてから、責務の狭い custom agent を足すほうが失敗しにくいです。
write-heavy な並列実装にも使えますか
使えますが、最初の適用先としてはおすすめしません。競合や調整コストが増えやすいので、まずは read-heavy な探索・レビュー・要約から始めるほうがメリットを取りやすいです。
Claude Code の Subagent と何が違いますか
設計思想（コンテキスト隔離 + 並列）は同じですが、起動仕様が異なります[公式値]。Codex は AGENTS.md + permission profiles + path-based 通信（/root/agent_a 等）で MultiAgentV2 をサポート、Claude Code は /agents コマンド + Markdown + YAML frontmatter で Subagent を定義します。役割分担と機能対比表は 2026 年の AI コーディング自動運転最前線 と Skills対Subagents使い分け5軸 を参照。
subagents 観測のために何を入れればよいですか
OpenAI の app-server の streamed agent events を活用すると、親子の委譲・返却を可視化できます[公式値]（App Server 公式）。観測基盤の設計全般は AIエージェントの可観測性と障害解析、durable workflow との統合は agent loop を durable workflow で安定化する実装 を参照。
まとめ
Codex の subagents は、「複数動くからすごい機能」ではありません。
本質は、探索や検証のノイズを親会話から切り離し、メインエージェントを賢いまま保つためのコンテキスト設計にあります。
だから最初に考えるべき問いは、「何本に分けるか」より先にこれです。
この作業のどこがノイジーで、どこを親に残したいのか。
この問いで分割すると、subagents はかなり扱いやすくなります。
参考リンク
- OpenAI Developers: Subagent concepts
- OpenAI Developers: Subagents
- OpenAI Developers: AGENTS.md guide
- OpenAI Developers: Agent Skills
- OpenAI Developers: App Server
- OpenAI Developers: Codex changelog
- OpenAI Developers: Codex CLI
- Claude Code 公式 docs（対比用）
- Claude Code Subagents 公式（対比用）
