3行まとめ
誰が何を読み、何を返すかを狭く決めます。
最初はread-onlyで調査とレビューに閉じます。
並列数、深さ、実行時間に上限を置きます。
subagentsは人数を増やす機能ではなく、調査の幅を広げる機能として扱います。
- Codex subagentsは、チームの人数を増やす機能というより、PRレビューやコードベース探索の観点を並列に広げる機能として使うと扱いやすいです。
- 最初に決めるべき境界は、role、permission、budgetです。役割が曖昧なまま並列化すると、レビュー対象、承認判断、利用量、失敗時の統合コストも増えます。
- 2026年6月7日にOpenAI公式DocsとHelp Centerを確認した範囲では、subagentsは明示的に依頼した時に起動し、親セッションのsandbox/approval設定を前提に動きます。
Xや検索結果ではCodex subagentsやparallel coding teamsへの関心が見えましたが、この記事ではSNS上の投稿を仕様説明の根拠にしません。本文の事実確認はOpenAI公式Docs、Help Center、ローカルの短いバージョン確認に限定しています。
この記事でわかること
PRレビューやコードベース探索に向く範囲を判断します。
explorer、worker、custom agentの分け方を決めます。
sandbox、approval、read-only開始の理由を確認します。
max_threads、max_depth、実行時間を上限として扱います。
PRテンプレートに承認、テスト、採否を残します。
機能紹介ではなく、チームで使い始める前の判断に絞ります。
- Codex subagentsを、並列PRレビューやコードベース探索に使う時の判断軸
explorer、worker、custom agentをチーム運用でどう分けるか- 親スレッド、子agent、AGENTS.md、custom agent、worktreeの役割の違い
- sandbox/approvalの継承を前提に、read-onlyから始める理由
agents.max_threads、agents.max_depth、実行時間、再試行回数を使用量の上限として扱う方法- 導入しない方がよいケース、失敗時の見分け方、PRテンプレートに残すべき記録
すでにAIコーディングエージェント全体の選定軸を整理したい場合は、先にAIコーディングエージェントを比べる前にを読むと位置づけがつかみやすくなります。この記事は、その中でもCodexのsubagentsをチーム運用に入れる直前の判断に絞ります。
前提知識
- 1親スレッド
何を並列化するか、期待出力、停止条件を決めます。
- 2子agent
指定された範囲だけを調査し、短い結果を返します。
- 3統合
親が矛盾、重複、未確認事項をまとめます。
- 4承認
追加権限や書き込みが必要な操作は人間に戻します。
明示的に依頼した時だけ起動し、単一agentより多くのtokenを使う前提で設計します。
subagentsは、親が設計して子が狭く動く
OpenAIのCodex Subagents docsでは、Codexが専門化したagentを並列に起動し、その結果を親側で集められると説明されています。対象として挙げられているのは、複雑で並列化しやすいタスク、たとえばコードベース探索や複数段階の機能計画です。
ここで大事なのは、subagentsが勝手に万能なチームになるわけではない点です。Codex docsでは、Codexは明示的に依頼した時にだけsubagentを起動し、各subagentは自分のモデル作業とtool作業を行うため、単一agentの実行よりも多くのtokenを使うと説明されています。
つまりチーム運用では、親スレッドに次の責任を残す必要があります。
- 何を並列化するかを決める
- 各subagentの入力、期待出力、停止条件を決める
- 結果を統合して、PRコメントや修正方針に落とす
- 追加承認が必要な操作を人間に戻す
- 調査が重複したり、矛盾した結論が出たりした時に止める
built-in agentとcustom agentを混ぜすぎない
Codex docsでは、built-in agentとしてdefault、worker、explorerが紹介されています。defaultは汎用、workerは実装や修正向き、explorerはread-heavyなコードベース探索向きという位置づけです。
チームで最初に試すなら、explorer相当のread-only調査から始めるのが無難です。レビュー観点を分けて、子agentには「直す」ではなく「根拠を集める」ことを頼みます。実装修正まで任せるのは、調査結果を人間が読み、方針を選んだ後で十分です。
custom agentを使う場合、個人用は~/.codex/agents/、プロジェクト用は.codex/agents/配下のTOMLファイルとして定義します。必須項目はname、description、developer_instructionsです。必要に応じてmodel、model_reasoning_effort、sandbox_mode、mcp_servers、skills.configなども入れられます。
worktreeは編集場所の分離であって、権限設計そのものではない
Codex appのWorktrees docsでは、worktreeにより同じGitリポジトリ内で複数の独立タスクを並行して進められると説明されています。background worktreeを使えば、手元のLocal checkoutを乱さずにCodexへ作業を走らせられます。
ただし、worktreeは権限の境界ではありません。どのコマンドを許可するか、network accessを許すか、秘密情報を読ませるか、人間承認を挟むかは、sandbox/approval、AGENTS.md、チームのレビュー運用で決めます。worktreeは「どこで作業するか」を分ける仕組みであり、「何をしてよいか」を自動で安全化する仕組みではありません。
結果：最初はread-heavyな並列レビューに閉じる
最初の成果は、レビューコメント候補、テスト不足、互換性リスク、影響範囲、未確認事項です。
結論として、Codex subagentsをチームに入れる最初の用途は、実装よりも並列レビューと探索に寄せるのが扱いやすいです。
| タスク | subagents向きか | 最初の権限 | 停止条件 |
|---|---|---|---|
| PRのsecurity観点レビュー | 向いている | read-only | 重大度、根拠ファイル、再現条件を出したら終了 |
| テスト不足の洗い出し | 向いている | read-only | 不足テストと確認コマンドを出したら終了 |
| 大きなリファクタの影響範囲調査 | 条件付き | read-only | 依存箇所と危険な変更面を列挙したら終了 |
| 同じファイルを複数agentで修正 | 向かない | なし | 親スレッドで分割し直す |
| DB migrationの実行 | 向かない | なし | 人間承認と別runbookへ戻す |
| 外部APIやMCPで書き込みを伴う操作 | 条件付き | 原則read-only | write権限の必要性を人間が確認するまで止める |
subagentsで最初に得たい成果は、変更そのものではなく判断材料です。レビューコメントの候補、テスト不足、互換性リスク、影響範囲、未確認事項が短く出れば十分です。
速さより、統合しやすさを見る
並列化の成果は、単に「早く終わったか」では判断できません。チーム導入で見るべきなのは、人間が最終判断しやすくなったかです。
たとえば、5つのsubagentが別々に長い感想を書いてきても、親スレッドやレビュー担当者は統合作業で疲れます。反対に、3つのagentがそれぞれ「重大度」「該当ファイル」「再現条件」「推奨対応」「未確認事項」の形式で返せば、PRコメントに落としやすくなります。
導入可否は5軸で見る
チームでpilotを始める前に、次の5軸で対象タスクを見ます。
評価基準
| 評価軸 | 見ること |
|---|---|
| 独立性 | 観点ごとに分けても重複が少ないか |
| 統合しやすさ | 子agentの出力を短いレビュー結果にできるか |
| 承認頻度 | 子agentごとに人間承認が頻発しないか |
| 戻しやすさ | 誤った調査や変更を止めやすいか |
| 使用量の予測 | max_threadsやruntimeで上限を説明できるか |
この5軸のうち、承認頻度と使用量の予測が弱いタスクは、subagentsに広げる前に手順を分けた方がいいです。
Codex subagentsの基本：役割は狭く切る
- 1入力
PR差分、対象ファイル、確認したい観点を渡します。
- 2読む範囲
対象外のファイルや論点を明示します。
- 3返すもの
根拠、重大度、確認コマンド、次の行動を返します。
- 4しないこと
review-onlyでは編集や外部接続をしません。
- 5上限
max_threads、max_depth、runtimeを小さく始めます。
max_depthは深い委譲を防ぐ設定として扱い、特別な理由がなければ深くしません。
custom agentは「専門家」ではなく「狭い作業者」として定義する
custom agentを作る時に避けたいのは、senior engineer、security expert、architectのような広すぎる役割名だけを置くことです。そうではなく、何を読んで、何を返し、何をしないかをTOMLに書きます。
たとえばPR探索用なら、最初はこの程度の狭さで十分です。
[agents]
max_threads = 3
max_depth = 1
# .codex/agents/pr-explorer.toml
name = "pr_explorer"
description = "Read-only agent for mapping changed files and gathering evidence before PR review."
sandbox_mode = "read-only"
developer_instructions = """
Stay in exploration mode.
Do not edit files.
Read the diff, identify affected code paths, cite files and symbols,
and return only risks, missing tests, and open questions.
"""これは完成形ではなく、チームで最初に合意する粒度の例です。実際にはモデル設定、MCP、skills、許可するコマンド、リポジトリ構成に合わせて調整します。
max_threadsとmax_depthは、速度ではなく暴走防止の設定
OpenAIのSubagents docsでは、global subagent settingsとしてagents.max_threads、agents.max_depth、agents.job_max_runtime_secondsが説明されています。agents.max_threadsは同時に開けるagent thread数、agents.max_depthは子agentのネスト深さです。
docsでは、agents.max_threadsは未設定なら6、agents.max_depthは未設定なら1とされています。max_depth = 1は直接の子agentを許し、それ以上の深い委譲を防ぐ設定です。深い再帰的委譲はtoken使用量、latency、ローカルリソース、予測可能性を悪化させるため、特別な理由がなければ最初は深くしない方がいいです。
初期設定の目安
チーム導入のpilotでは、次のように小さく始めます。
| 項目 | 初期値の考え方 |
|---|---|
agents.max_threads | 2から3。レビュー観点を絞る |
agents.max_depth | 1。子agentにさらに委譲させない |
| 実行時間 | 1観点あたり10分から15分を上限にする |
| 再試行 | 同じ観点の再実行は1回まで |
| 出力量 | 重大な指摘を最大5件に絞る |
親スレッドに残すべきこと
子agentに渡してよいのは、独立して調べられる範囲です。親スレッドに残すべきなのは、最終判断と統合です。
具体的には、親が次を担当します。
- PR全体の目的を説明する
- 観点ごとのsubagentを選ぶ
- 調査範囲を限定する
- 子agentの結果を重複排除する
- 誤指摘や根拠不足を落とす
- 修正するか、PRコメントにするか、人間に戻すかを決める
subagentsを使うほど、親の設計品質が結果に出ます。親が曖昧なら、子agentの数を増やしても曖昧さが並列に増えるだけです。
並列PRレビューで使うなら、観点を先に切る
review-onlyの知見とworkerの変更を混ぜると、人間が承認した判断を追いにくくなります。
依頼文は「1 agent 1観点」にする
PRレビューでsubagentsを使うなら、1つのagentにPR全体の品質判断を任せるより、観点ごとに切る方が結果を比較しやすくなります。
依頼文は、たとえば次のようにします。
このPRを review-only で確認してください。
3つのsubagentを起動し、それぞれ security risk、missing tests、API compatibility だけを見てください。
各agentはファイルを編集せず、次の形式で最大5件だけ返してください。
- severity
- file
- reason
- reproduction or confirmation command
- suggested next action
全員の結果がそろったら、重複をまとめ、親スレッドで採用候補と保留候補に分けてください。ポイントは、「PRを直して」ではなく「根拠を集めて」です。最初から修正まで渡すと、review-onlyの知見とworkerの変更が混ざり、どの判断を人間が承認したのか追いにくくなります。
review-onlyとfix権限を混ぜない
PRレビューのpilotでは、review-onlyとfixを分けます。
| 役割 | やること | やらないこと |
|---|---|---|
| security reviewer | 危険な入力、認可漏れ、秘密情報の扱いを見る | 攻撃手順の実行、外部サービスへの接続 |
| test reviewer | 変更面と不足テストを対応づける | テストコードの直接修正 |
| compatibility reviewer | 公開API、schema、型、migration影響を見る | 方針未決定の破壊的変更 |
| worker | 親が選んだ小さな修正を実装する | 独断で仕様を広げる |
修正が必要なら、親スレッドが「この1件だけ直す」と決めてからworkerへ渡します。レビュー担当の子agentが自分で直し始めると、レビュー結果と変更理由が混ざります。
PRに残す記録を決める
subagentsを使ったPRでは、本文かコメントに次の情報を残します。
- 使ったagentの役割
- 対象範囲
- 各agentの未確認事項
- 人間が承認した操作
- 実行したテスト
- 実行しなかったテストと理由
- 残したリスク
これは監査のためだけではありません。次のPRで同じ運用を再現できるようにするためです。AIレビューをチームに入れるなら、「どのagentが何を見たか」より、「人間が何を採用したか」を残す方が効きます。
権限境界：子agentは親のsandbox/approvalを前提に動く
- 1read-only
PR差分と関連ファイルを調べます。
- 2workspace-write
必要な修正を親が1件ずつ選びます。
- 3network access
外部調査が必要な時だけ別途承認します。
- 4外部API・MCP・秘密情報
pilot対象外にして、人間の判断へ戻します。
- 5approval request
source thread labelを確認して承認または拒否します。
親で強い権限を開いたまま起動すると、子agentもその前提で進みます。
親セッションの設定を先に固定する
OpenAIのSubagents docsでは、subagentsは現在のsandbox policyを継承すると説明されています。また、interactive sessionで/permissionsを変えたり、--yoloのようなruntime overrideを使ったりした場合、その親turnの設定も子に再適用されます。
この仕様は便利ですが、チーム運用では注意が必要です。親で強い権限を開いたままsubagentsを起動すれば、子agentの作業もその前提で進みます。custom agent側でread-onlyを指定しても、親turnのruntime overrideが絡む場合は、実際の挙動をチームで確認しておくべきです。
確認順
最初のpilotでは、次の順にします。
- read-onlyでPR差分と関連ファイルを調べる
- workspace-writeが必要な修正は親が1件ずつ選ぶ
- network accessが必要な調査は別途承認にする
- 外部API、MCP、秘密情報を含む操作はpilot対象外にする
inactive threadからのapprovalも見落とさない
Codex docsでは、interactive CLI sessionでは、見ていないagent threadからapproval requestが出る可能性も説明されています。approval overlayにはsource thread labelが表示され、必要なら該当threadを開いてから承認、拒否、回答できます。
これは小さなUI上の話に見えますが、チームルールとしては重要です。複数agentを走らせると、「誰のどの操作を承認しているのか」が見えにくくなります。承認の前に見るべき項目を決めておきます。
承認前の確認項目
| 承認前に見る項目 | 理由 |
|---|---|
| source thread | どのagentの操作か確認する |
| command | 何を実行するか確認する |
| working directory | worktreeかLocalか確認する |
| network access | 外部通信が発生するか確認する |
| file write | どのファイルが変わるか確認する |
| secret exposure | .envやcredentialに触れないか確認する |
network accessは別枠で扱う
OpenAIのAgent approvals & security docsでは、Codex CLIやIDE extensionの既定ではnetwork accessがオフであり、workspace内の書き込みに制限されると説明されています。Codex cloudでも、setup phaseとagent phaseの違いや、agent phaseが既定ではofflineである点が説明されています。
subagentsに外部Docsを読ませたい場合でも、network accessを常時開く必要があるとは限りません。先に人間が公式Docsを確認して記事やPRに引用し、子agentにはローカルの差分と既存コードを読ませるだけで足りる場合もあります。MCPや外部APIを絡める時は、prompt injection対策の観点も合わせて見てください。
AGENTS.mdとcustom agentは別物として設計する
AGENTS.mdはリポジトリ全体の契約、custom agentは特定の役割を持つ子agentの設定です。
AGENTS.mdは全員に読ませる作業契約
OpenAIのAGENTS.md guideでは、Codexが作業前にAGENTS.mdを読み、global scope、project scope、nested directoryの順にinstruction chainを作ると説明されています。近いディレクトリの指示ほど後ろに連結されるため、より具体的な指示として効きます。
また、Codexは空ファイルを飛ばし、combined sizeがproject_doc_max_bytesに達すると追加を止めます。既定値は32 KiBです。チームでAGENTS.mdを育てる時は、長く書きすぎるより、subagentsに必要な禁止操作、テスト、レビュー基準を短く残す方が向いています。
たとえば、subagents用には次のような方針を入れます。
AI agent review rules
- Start PR review in read-only mode.
- Do not edit files during review-only tasks.
- Do not read `.env`, secrets, private credentials, or production dumps.
- Return findings with severity, file, reason, confirmation command, and suggested next action.
- Ask before using network, external APIs, MCP tools with write access, or destructive commands.
- Run only documented test commands. If tests are not run, explain why.このような指示は、subagentsだけでなく、通常のCodex作業にも効きます。チームでAGENTS.mdの書き方を整えるなら、公開済みのチーム向けAGENTS.mdテンプレートも合わせて使えます。
custom agentは狭い役割定義
custom agentは、AGENTS.mdの代わりではありません。AGENTS.mdはリポジトリ全体の作業契約、custom agentは特定の役割を持つ子agentの設定です。
| 置き場所 | 書くこと | 書かないこと |
|---|---|---|
| AGENTS.md | 禁止操作、テスト、レビュー基準、秘密情報の扱い | agentごとのモデル選択 |
.codex/agents/*.toml | agent名、説明、developer instructions、sandboxなど | チーム全体の最終承認ルール |
| 親prompt | 今回の対象PR、観点、期待出力、停止条件 | 恒久的なポリシー |
| PRテンプレート | 使ったagent、テスト結果、残リスク | 長い運用マニュアル |
AGENTS.mdを変えた時は、それ自体もレビュー対象です。instruction driftや権限競合を避ける観点は、AGENTS.mdを変更レビューに入れる前にで整理しています。
「書けば安全」ではなく、実行ゲートと組み合わせる
AGENTS.mdに「危険操作は禁止」と書くだけでは、実行を物理的に止める仕組みにはなりません。sandbox、approval、CI、CODEOWNERS、人間レビュー、credential分離と組み合わせて初めて運用になります。
subagentsを使うと、同時に走る作業が増えます。自然文のルールだけに頼ると、レビュー担当者が承認や出力を追いきれません。禁止事項は文章に書き、実行できないようにし、例外時は人間承認に戻す。この3段で考えるのが現実的です。
worktree分離：並列化するほどLocalと背景作業を分ける
- 1Local
review-onlyでPR差分を読み、結果をまとめます。
- 2worktree
背景で実装修正、テスト、依存関係更新を進めます。
- 3Handoff
threadをLocalとWorktreeの間で移します。
- 4制約確認
同じbranchの複数checkoutや.gitignore対象に注意します。
- 5人間確認
PR化前にLocalで変更を確認します。
worktreeは編集場所の分離であり、権限管理の代替ではありません。
review-onlyならLocalでも足りる
PR差分を読むだけなら、必ずしもworktreeは必要ありません。read-onlyで調査し、結果を親スレッドにまとめるだけなら、Local checkoutでも混線は少ないです。
worktreeが効くのは、背景で実装修正、テスト、依存関係更新、複数branchの比較を進めたい時です。Codex appのWorktrees docsでは、worktreeがGit repositoryで使われ、同じproject内の独立タスクを並列に進められると説明されています。
Handoffの制約を知っておく
Worktrees docsでは、HandoffによりthreadをLocalとWorktreeの間で移せると説明されています。Git操作を使うため、branchは同時に複数checkoutできず、.gitignoreに含まれるファイルはHandoffで移りません。
注意点
これは、実務では次の注意になります。
.env.localや生成物に依存する検証は、worktree側で再現できるようにする- Localでしか動かない開発サーバーがある場合は、Handoffしてから確認する
- 未追跡ファイルや秘密情報をworktreeへ渡す前提で設計しない
- background worktreeで進めた変更は、PR化前に人間がLocalで確認する
worktreeは便利ですが、秘密情報や未追跡ファイルの扱いまで肩代わりしません。CIで再現できる状態に寄せるほど、subagentsの結果もレビューしやすくなります。
コスト境界：利用量は「後で見る」では遅い
大きなコードベース、長時間タスク、長いsessionはより多く消費します。
subagentsは使用量を増やしやすい
OpenAI Help Centerでは、Codex usage limitsはplanに依存し、agentic usage limitに数えられると説明されています。送れるCodex message数は、モデル、タスクの大きさ、複雑さ、ローカルかcloudかによって変わります。大きなコードベース、長時間タスク、長いsessionはより多く消費します。
Pricing docsでは、plan別のusage limit例も示されています。ただし、料金や利用枠は変わりやすいため、この記事では固定の価格比較表にはしません。チーム導入で重要なのは、公式pricingを見ながら、自分たちのpilotに上限を置くことです。
budgetは金額だけでなく、並列数と時間で決める
subagentsのbudgetは、月額料金だけでは決まりません。実際には、次の運用値で制御します。
制御項目
| 制御項目 | 決め方 |
|---|---|
| 並列数 | 1PRあたり2から3観点まで |
| 深さ | max_depth = 1から始める |
| runtime | 1agentあたり10分から15分で止める |
| 再試行 | 同一観点の再実行は1回まで |
| 出力件数 | 重大指摘は最大5件 |
| network | 原則off。必要時だけ承認 |
| write権限 | review-onlyでは渡さない |
| 記録 | PRテンプレートに使ったagentと未確認事項を残す |
この表をチームのPRテンプレートやAGENTS.mdに移すと、subagentsを使った時の説明責任が軽くなります。料金面の導入判断は、公開済みのAIコーディングツール料金改定の見方も参考になります。
Business/Enterpriseでは監査とデータ扱いを見る
OpenAI Help Centerでは、Codex usageにはlocal clientsやcloud-delegated usageを含むCompliance APIのlog surfaceがあると説明されています。また、Business、Enterprise、Eduでは、既定では入力や出力をモデル改善に使わないと説明されています。一方、ProやPlusでは、ChatGPT data controlsをoffにしない限り会話がモデル改善に使われる場合があります。
チーム導入では、単に「使えるか」ではなく、次を確認します。
- plan上のusage limitと追加creditの扱い
- Business/Enterpriseの管理機能、SSO、MFA、RBAC
- data controlsとtraining利用の扱い
- Compliance APIやusage monitoringで追える範囲
- API key利用時に使えないcloud-based feature
ここは会社ごとに判断が分かれます。公式Help Centerと契約条件を確認し、必要なら法務やセキュリティ担当を含めて決める領域です。
失敗点：subagentsに任せるほど、人間の設計不足が見える
各agentの見る範囲と見ない範囲を分け直します。
承認が多発するならread-onlyへ戻します。
review-onlyでは編集しない指示とsandboxを確認します。
重大度、根拠、次の行動だけに絞って返します。
親スレッドが根拠を比較し、未確認事項を残します。
調査、判断、修正、検証を一つの子agentに混ぜるほど、後からPRを説明しにくくなります。
同じ調査が並列に重複する
PRレビューでよくある失敗は、security、test、compatibilityのつもりで分けたのに、全員が同じファイルを読み、同じ曖昧な指摘を返すことです。これはagentの能力不足だけでなく、親promptの分割不足です。
避けるには、各agentに「見る範囲」と「見ない範囲」を書きます。たとえばsecurity reviewerには認証、認可、秘密情報、外部入力だけを見るように頼み、test reviewerには変更面とテスト不足だけを見てもらいます。
approval待ちで止まる
複数agentが同時に動くと、承認待ちも増えます。non-interactive flowで新しいapprovalを出せない場合、承認が必要なactionは失敗し、親workflowにerrorが戻ります。これ自体は安全側の挙動ですが、長い自動実行を期待していると失敗に見えます。
pilotでは、approvalが出た件数を記録します。1PRでapprovalが多発するなら、権限を開くのではなく、対象タスクをread-onlyに戻すか、事前に許可するコマンドを絞った方がいいです。
子agentが直し始める
review-onlyのはずが、子agentが修正まで始めると、人間のレビュー境界が崩れます。これを防ぐには、custom agentとAGENTS.mdの両方に「review-onlyでは編集しない」と書き、sandboxもread-onlyに寄せます。
「よい指摘だからその場で直してほしい」という気持ちはわかります。ただ、チーム導入初期は分けた方が事故が少ないです。調査、判断、修正、検証を一つの子agentに混ぜるほど、後からPRを説明しにくくなります。
長い結果で親が溺れる
subagentsが返す結果が長すぎると、親スレッドの統合が難しくなります。子agentには、件数上限と出力形式を指定します。
たとえば、次のようにします。
Return at most 5 findings.
Do not include style-only comments.
For each finding, include severity, file, reason, confirmation command, and next action.
If you are unsure, mark it as "open question" instead of a finding.「不確かなものはopen questionにする」と決めておくと、誤指摘を重大バグのように扱う事故を減らせます。
実務で使うなら
- 1. 対象を絞る
1リポジトリ、1PRだけで試します。
- 2. 観点を選ぶ
security risk、missing tests、API compatibilityに絞ります。
- 3. review-onlyで実行
根拠、確認コマンド、未確認事項を集めます。
- 4. PRに記録
利用agent、承認、テスト、採用した指摘を残します。
- 5. 標準化を判断
重複、承認待ち、利用量を見て次の範囲を決めます。
UIの好み、命名、軽微なリファクタ提案はpilotから外します。
1リポジトリ、1PR、3観点でpilotする
最初のpilotは小さくします。対象は1リポジトリ、1PR、3観点です。
おすすめの3観点は次です。
- security risk
- missing tests
- API compatibility
この3つは独立しやすく、結果も人間が判断しやすいです。UIの好み、命名、軽微なリファクタ提案はpilotから外します。style-only commentが増えると、subagentsの価値が見えにくくなります。
PRテンプレートにsubagent利用欄を作る
PRテンプレートには、次の欄を追加します。
AI review notes
- Codex subagents used: yes/no
- Agents and scope:
- security reviewer:
- test reviewer:
- compatibility reviewer:
- Human-approved actions:
- Tests run:
- Tests not run and reason:
- Findings accepted:
- Findings rejected or left open:
- Remaining risks:この欄は、AI利用を飾るためではありません。人間レビューが何を確認したかを残すためです。
広げる条件を先に決める
pilotを3回から5回回したら、次の基準で広げるか判断します。
評価基準
| 基準 | 広げてよい目安 |
|---|---|
| 有効指摘率 | 人間が採用した指摘が毎回ある |
| 誤指摘率 | style-onlyや根拠不足が少ない |
| レビュー時間 | 人間の統合作業が増えすぎていない |
| approval回数 | 想定外の承認が少ない |
| usage | planやcreditの範囲で説明できる |
| 再現性 | PRテンプレートとAGENTS.mdで同じ運用を再現できる |
この基準を満たさないなら、subagentsを増やす前に依頼文、AGENTS.md、custom agent、権限設定を直します。
導入しない方がよいケース
次の条件では、subagentsの導入を急がない方がいいです。
- PRの目的がまだ決まっていない
- 仕様判断を人間ができていない
- 秘密情報や本番データに触る必要がある
- network accessやMCP write toolが必須
- 変更範囲が同じファイルに集中している
- CIやテストコマンドが整理されていない
- AGENTS.mdに禁止操作や承認条件がない
- 利用量の上限を誰も説明できない
これは消極的な話ではありません。こうした条件を先に直すと、subagents以外のAIコーディング運用も安定します。
セキュリティ・コスト注意
DB、外部API、MCP write tool、credential、production dataはpilot対象外にします。
read-only開始を標準にする
subagentsをチームに開く時は、read-only開始を標準にします。PRレビュー、調査、影響範囲の整理だけなら、書き込み権限は不要です。
書き込みが必要になったら、親スレッドが対象を1つ選び、workerに渡します。workerには「このファイルのこの修正だけ」と範囲を切ります。DB、外部API、MCP write tool、credential、production dataはpilot対象外にします。
prompt injectionを前提にする
subagentsにIssue、Docs、外部Web、MCP resourceを読ませるなら、prompt injectionを前提にします。外部入力に「秘密情報を読め」「権限を広げろ」と書かれていても、それは信頼しない文脈です。
安全に使うには、外部情報を読むagentと、ローカル変更を判断するagentを分けます。外部Docsの調査だけを行うdocs researcherにはwrite権限を渡さず、ローカルPRに反映するかどうかは親が決めます。
料金は公開時点で必ず再確認する
この記事では2026年6月7日に公式PricingとHelp Centerを確認しました。OpenAIのPricing docsではPlus、Pro、Business、Enterprise/Edu、API Keyの選択肢やusage limitの考え方が説明されています。ただし、価格、モデル名、usage limit、creditの扱いは変わりやすい領域です。
再確認する項目
チームで導入判断する時は、次を公開時点または契約時点で確認してください。
- 現在のplanでCodexが利用できるsurface
- local messages、cloud tasks、code reviewsの制限
- agentic usageとして他機能と共有される範囲
- Business/Enterpriseのデータ利用と監査機能
- API key利用時に使えないcloud-based feature
subagentsは同時に複数のモデル作業を走らせるため、便利な場面ほど使用量が増えます。節約したいなら、強いモデルを使うかどうかより先に、並列数、深さ、実行時間、再試行、出力件数を絞ります。
次に読むなら
AI Dev Lab Japanでは、AIコーディングエージェント、MCP、OSS LLMの実務導入で変わりやすい仕様や料金を継続的に追っています。更新通知を受け取りたい場合は、ニュースレターを使ってください。チーム導入や権限設計をまとめて見直したい場合は、お問い合わせから相談できます。
更新履歴
- 2026-06-07
OpenAI Codex Subagents docs、Agent approvals & security、AGENTS.md guide、Worktrees docs、Pricing、OpenAI Help Centerを確認しました。
- ローカル確認
codex-cli 0.137.0、Node v25.9.0、git version 2.41.0を確認しました。
- 需要シグナル
Xのtracked accountページは仕様説明の根拠に使わず、需要シグナルとしてのみ扱いました。
仕様、料金、usage limitは変わりやすいため、公開時点の確認履歴を残します。
- 2026-06-07: OpenAI Codex Subagents docs、Agent approvals & security、AGENTS.md guide、Worktrees docs、Pricing、OpenAI Help Centerを確認。ローカルでは
codex-cli 0.137.0、Node v25.9.0、git version 2.41.0を確認しました。 - 2026-06-07: Xのtracked accountページは未認証取得では本文を確認できなかったため、需要シグナルとしてのみ扱い、記事内の仕様説明には使っていません。
参照した主な情報源
- https://developers.openai.com/codex/subagents
- https://developers.openai.com/codex/agent-approvals-security
- https://developers.openai.com/codex/guides/agents-md
- https://developers.openai.com/codex/app/worktrees
- https://developers.openai.com/codex/pricing
- https://help.openai.com/en/articles/11369540-codex-in-chatgpt