Codex Subagentsで分担する前に決めること

3行まとめ

Research

読むだけ。

Build

変更を作る。

Review

リスクを見る。

Verify

結果を確認。

Integrate

統合する。

subagentを増やす前に、統合役と成果物を決めます。

• Codex Subagentsは、作業を並列化する前に、調査、実装、レビュー、検証、統合の役割を分けます。
• subagentへ渡す入力と返してほしい成果物を固定しないと、速く動いても統合時に手戻りが増えます。
• すべてのsubagentに同じ権限を渡さず、read-only調査、限定実装、レビュー専用、外部tool利用を分けます。

この記事では、OpenAI公式のSubagents、Hooks、Skills、Permissions、AGENTS.md、Config docsを確認し、2026年6月1日時点の情報として整理しています。Subagentsの挙動、設定、hook event、tool権限は更新され得るため、導入前に最新docsと手元のCodex設定を確認してください。

この記事でわかること

Task

何を任せるか。

Input

渡す情報。

Output

返す形式。

Owner

統合役。

速くするより、統合できる形で分担することが大事です。

• Codex Subagentsを使う前に分ける役割
• 調査、実装、レビューを同じsubagentに混ぜない理由
• subagentへ渡す入力と成果物の型
• 権限とtoolをsubagentごとに変える考え方
• 統合役を置く理由
• SubagentStop hookやskillsで分担を安定させる方法
• 導入初週に見るべき失敗条件

Subagentsは便利です。大きな調査を複数視点で進めたり、実装案を比較したり、レビューだけ別の目で見たりできます。ただし、subagentを増やすだけでは仕事は終わりません。最後に結果を統合し、採用判断をし、未検証を残す役割が必要です。

「速くなる」だけを期待してsubagentを使うと、結果がばらばらになります。あるsubagentは仕様を見ていて、別のsubagentは実装だけを見ていて、別のsubagentはテストを見ている。最後に人間や親agentがつなぎ直すなら、最初から成果物の型を決めたほうがよいです。

CodexのSkills、Plugins、Subagents、MCPの全体像は、公開済み記事のCodexのSkills・Plugins・Subagents・MCPをチームで使う前にでも整理しています。この記事では、Subagentsの分担設計だけに絞ります。

前提知識

項目	内容	見方
Subagents		分担の考え方。
Hooks		Stop確認。
Skills		手順化。
Permissions		権限。
AGENTS.md		repo指示。

subagent周りの仕様は導入時に最新docsを確認します。

OpenAI公式のSubagents docsでは、subagentを使って作業を分担する考え方が説明されています。Subagentsは、親の作業を補助する別のagentとして扱われ、調査、レビュー、独立した作業などに使えます。

Hooks docsでは、SubagentStartやSubagentStopのeventが扱われています。SubagentStopでは、subagentが止まったタイミングで追加確認を入れられます。Skills docsでは、繰り返し作業の手順をskillとして固定する考え方が説明されています。

公式情報で確認する範囲

確認先	見ること
Subagents	分担の考え方、使いどころ
Hooks	SubagentStart、SubagentStop、Stop
Skills	繰り返し手順の固定
Permissions	subagentに渡す権限、approval
AGENTS.md	repo固有の作業契約
Config	subagents、skills、MCP、project設定

注意点

この記事は、subagentを増やすこと自体を推奨するものではありません。作業が小さいなら、1つのagentで進めるほうが速く、読みやすい場合があります。Subagentsが効くのは、独立して調べられる範囲があり、成果物を統合できるときです。

また、subagentは責任の所在を消しません。最終判断、公開、merge、deploy、外部送信、顧客影響の判断は、親agentまたは人間が引き受けます。

まずsubagentに渡す仕事を分ける

1. 1Read

   調査。

2. 2Plan

   整理。

3. 3Edit

   実装。

4. 4Check

   レビュー。

同じsubagentに調査と実装とレビューを全部押し込まないようにします。

Subagentsへ渡す前に、仕事を4つへ分けます。

役割	例	成果物
調査	docs、issue、codeの確認	根拠付きメモ
実装	限定scopeの変更	diffとtest結果
レビュー	risk、bug、security確認	findings
検証	test、QA、公開確認	command結果

この分類をしないまま「並列でやって」と頼むと、同じことを複数subagentが調べたり、逆に誰も見ていない範囲が残ります。

調査

調査subagentは、read-onlyで十分なことが多いです。仕様、公式docs、issue、既存実装、類似PR、公開URLなどを確認し、根拠と判断を返します。

調査subagentの成果物

調査subagentには、次の型で返してもらいます。

項目	内容
結論	1から3行
根拠	URL、file、line、command結果
不確実性	変わり得る情報、未確認範囲
次の行動	実装、保留、追加調査

根拠がない調査メモは、統合時に使いにくいです。特にOpenAI製品やライブラリ、価格、権限、API仕様は変わるため、一次情報へのリンクや確認日を残します。

実装

実装subagentには、範囲を狭く渡します。対象file、変更してよいdirectory、触らない領域、test command、完了条件を渡します。

実装subagentへ「いい感じに直して」と頼むと、差分が大きくなりがちです。subagentに任せる実装は、独立した小さな作業にします。

向いている実装	向いていない実装
1つのcomponent修正	全体設計の作り直し
test追加	複数package横断refactor
docsの限定更新	product仕様の最終判断
parserの小さなbugfix	migrationとdeployを伴う変更

レビュー

レビューsubagentは、実装subagentとは別の役割にします。同じsubagentが自分の変更をレビューすると、見落としやすくなります。

レビューsubagentには、次の観点を渡します。

観点	見ること
bug	例外、edge case、回帰
security	secret、権限、外部送信
tests	未検証、テスト不足
scope	依頼範囲を超えていないか

Codexに実装前レビューを頼む手順は、公開済み記事のCodexに実装前レビューを頼むでも扱っています。Subagentsでは、このレビュー役を独立させるのがポイントです。

入力と成果物を固定する

項目	内容	見方
Input		範囲と制約。
Evidence		根拠。
Output		要約と差分。
Risk		未検証。

成果物の型が揃うと、統合役が判断しやすくなります。

Subagentsを使うなら、入力と成果物の型を固定します。ここが揃っていないと、親agentが結果を統合できません。

渡すcontext

subagentへ渡すcontextは、広すぎても狭すぎても困ります。

渡すもの	理由
目的	何のための作業か
対象範囲	file、URL、issue、PR
制約	触らない場所、禁止操作
完了条件	何ができたら終わりか
報告形式	親agentが統合しやすい

特に、禁止操作や未検証時の報告形式は明確にします。subagentが「完了」とだけ返すと、親agentは検証状態を判断できません。

入力を短く保つ

subagentへ渡す入力は、必要な範囲に絞ります。すべての背景情報を渡すより、目的、対象、制約、期待成果物を短く渡したほうが動きやすくなります。

詳しいrepoルールはAGENTS.md、繰り返し手順はskill、外部tool接続はMCPやpluginに寄せます。promptだけで全部説明しようとしないことが大切です。

返してほしい形式

成果物は、次の型にします。

Summary:
- ...

Evidence:
- file or URL:
- command:

Changes:
- ...

Risks:
- ...

Not run:
- ...

Next:
- ...

この型は、PRレビューや公開前QAにも使えます。親agentが複数subagentの結果を比較しやすくなります。

権限とtoolを分ける

Read-only

調査だけ。

Scoped edit

限定変更。

Review

diff確認。

External

接続先確認。

すべてのsubagentに同じ権限を渡さないほうが安全です。

すべてのsubagentに同じ権限を渡さないほうが安全です。調査だけのsubagent、実装するsubagent、レビューするsubagent、外部toolを使うsubagentでは、必要な権限が違います。

read-only調査

調査subagentは、read-onlyを初期値にします。fileを読む、docsを確認する、issueやPRを見る、公開URLを確認するだけなら、変更権限は不要です。

read-onlyで十分な作業は、次のようなものです。

作業	必要な権限
公式docs確認	web read
repo構成調査	file read
PR diff確認	GitHub read
既存テスト確認	file read、shell read系

ここで変更権限を渡す必要はありません。

変更を許す作業

実装subagentへ変更を許す場合は、scopeを限定します。

制約	例
path	src/foo/**だけ
command	npm testまで
禁止	deploy、secret表示、DB操作
test	必須commandを指定

Codexの権限や設定の分け方は、公開済み記事のCodex設定を増やす前に決めることと組み合わせて考えると整理しやすくなります。

外部toolを使うsubagent

MCP、GitHub、browser、computer useのような外部toolを使うsubagentは、さらに慎重にします。接続先、read/write、認証scope、ログ、失敗時の扱いを確認します。

外部通信やMCPの境界は、公開済み記事のCodexにインターネットアクセスを許可する前にも参考になります。

統合役を必ず置く

項目	内容	見方
Conflict		矛盾を見る。
Coverage		抜けを見る。
Tests		検証を見る。
Decision		採用を決める。

subagentの数より、最後に判断する役割が重要です。

Subagentsを使うときに一番大事なのは、統合役です。親agentが統合役になる場合もあれば、人間が統合役になる場合もあります。どちらにせよ、最後に判断する人やagentを明確にします。

結果の矛盾を見る

複数subagentの結果は矛盾することがあります。あるsubagentは「仕様上問題ない」と言い、別のsubagentは「既存テストと矛盾する」と言うかもしれません。統合役は、矛盾を潰します。

確認	見ること
根拠	URL、file、line、commandがあるか
範囲	見た範囲が重なっているか
時点	情報の確認日が合っているか
結論	採用、保留、追加調査を分ける

根拠の弱い結論は採用しません。subagentの自信ではなく、証跡で判断します。

未検証を残す

統合役は、未検証を消さないことも大事です。subagentがtestを走らせていない、外部APIを確認していない、UIを見ていないなら、そのまま未検証として残します。

「未検証だけどたぶん大丈夫」を完了に混ぜると、後で事故になります。親agentの最終報告にも、Not run、Risk、Next actionを残します。

Hooksとskillsで手順を補強する

SubagentStop

終了時確認。

Skill

手順固定。

AGENTS

repo契約。

Rules

実行境界。

subagentだけでなく、hooksやskillsで成果物の型を揃えます。

Subagentsは単体でも使えますが、Hooksやskillsと組み合わせると安定しやすくなります。

SubagentStop

Hooks docsでは、SubagentStop eventが扱われています。subagentが止まった時点で、成果物が足りているか、根拠があるか、未検証を書いているかを確認する補助にできます。

たとえば、SubagentStopで次のような警告を出します。

条件	警告
Evidenceなし	根拠を追加してから統合
Not runなし	未検証がないか確認
URLなし	公式情報の根拠不足
変更ありでtestなし	検証不足

Hooksの設計は、公開済み記事のCodex Hooksで止める前に決めることも合わせて読むと整理しやすいです。

skill化する作業

同じsubagent分担を何度も使うなら、skill化します。たとえば、「公式docs調査subagent」「差分review subagent」「QA証跡確認subagent」のように、入力と成果物の型をskillへ寄せます。

skill化する候補は次の通りです。

作業	skill化する理由
公式docs調査	source policyを固定できる
PR review	findings形式を固定できる
QA確認	commandと証跡を固定できる
公開前監査	PASS条件を揃えられる

skillは、subagentを増やすためではなく、subagentの成果物を揃えるために使います。

導入初週の進め方

1. 1日目

   read-only調査。

2. 2日目

   レビュー分担。

3. 3日目

   小さな実装。

4. 5日目

   SubagentStop確認。

5. 7日目

   型を固定。

最初は大規模並列ではなく、統合しやすい小さな分担から始めます。

Subagentsは、最初から大きな並列実装に使わないほうがよいです。小さな分担から始め、統合のしやすさを見ます。

日	やること	見ること
1日目	read-only調査を1つ任せる	根拠付きで返るか
2日目	reviewだけ別subagentにする	findingsが使えるか
3日目	小さな実装を限定scopeで任せる	diffが狭いか
4日目	統合役の報告形式を固定する	矛盾や未検証が残るか
5日目	SubagentStopで不足を警告する	成果物の型が揃うか
7日目	skill化する分担を選ぶ	再利用できるか

初週に見るべきなのは、同時に何個動かせるかではありません。subagentの結果が統合できるか、親agentや人間の確認負荷が下がるかです。

継続判断の基準

次の4つを満たすなら、subagent運用を広げます。

判断	継続条件
独立性	作業を分けても衝突しない
証跡	根拠、変更、test、未検証が残る
安全性	権限とtoolが役割ごとに分かれる
統合性	親agentが採用判断できる

満たさない場合は、subagentを減らします。並列化より、統合できる形が優先です。

FAQ

Parallel?

独立なら。

Edit?

範囲限定。

Review?

別役割。

Handoff?

統合役へ。

迷ったら、最後に誰が判断するかへ戻ります。

Subagentsはいつ使うべきですか

独立して進められる調査、レビュー、検証、限定実装があるときです。1つの小さな修正なら、subagentを使わないほうが速い場合もあります。

実装subagentとレビューsubagentは分けるべきですか

分けるほうがよいです。自分の変更を自分でレビューすると見落としやすいため、実装とレビューは別役割にします。

subagentに広い権限を渡してもよいですか

最初は避けます。調査はread-only、実装は限定scope、外部tool利用は接続先とread/writeを確認します。必要な権限だけ渡します。

SubagentStop hookは必須ですか

必須ではありません。ただし、subagentの成果物がばらつく場合は役立ちます。Evidence、Not run、Risks、Next actionがあるかを確認する補助にできます。

skillsとsubagentsはどう分けますか

skillは手順の型、subagentは作業の分担です。繰り返し使う調査やレビューの型をskill化し、そのskillをsubagentに使わせる、という分け方が自然です。

次に読むなら

参照した主な情報源

• https://developers.openai.com/codex/subagents
• https://developers.openai.com/codex/hooks
• https://developers.openai.com/codex/config/skills
• https://developers.openai.com/codex/permissions
• https://developers.openai.com/codex/guides/agents-md
• https://developers.openai.com/codex/config-advanced

更新履歴

1. 2026年6月1日

   OpenAI公式Codex docsを確認して初版を作成しました。

導入時には最新のSubagents docsと権限設定を確認してください。

• 2026年6月1日: OpenAI公式Codex docsを確認し、Subagentsを調査、実装、レビュー、検証、統合に分ける記事として初版を作成しました。