Codexの親子エージェント設計

約10分

Codexで高effortの親と軽量subagentを構成し、AGENTS.md・Skills・agent設定を分離したい開発者

オーケストレーションパターン
Codexをリポジトリで利用できること

Codexでは、親のthreadに要件と判断を残し、探索、限定実装、レビューを別のagent threadへ委譲できます。ここでは、親を高いreasoning effortで動かし、子を仕事に合わせて軽量化する構成を、リポジトリへ保存できる設定として作ります。

親のreasoningと子の実行コストを別々に設計する

Codexのagent threadは、subagentが独立した作業を進める会話と実行の単位です。親は子を起動し、追加指示を送り、完了を待ち、結果を統合します。子の途中ログを親へすべて入れず、要約だけを戻すことで、親を要件と判断へ集中させられます。[1]

このページで学べること

親へ残す設計判断とsubagentへ渡す仕事を分けられる
.codex/config.tomlと.codex/agents/でモデル、effort、並列数、権限を設定できる
AGENTS.mdと.agents/skills/の役割を分けられる
explorer、worker、reviewerのcustom agentを作成できる
総トークン、親のコンテキスト、並列競合を別々に管理できる

親を高性能にする理由は、すべてのコードを書かせるためではありません。曖昧な要件、依存関係、リスク、子の結果の採否を親へ集約するためです。子は、入力と完了条件を短く書ける仕事ほど軽量モデルと低いeffortへ寄せられます。

ディレクトリは常時方針・agent・Skillを分ける

Codex用の最小構成は、リポジトリ方針、agent設定、再利用手順の3層です。公式ドキュメントでは、project custom agentを.codex/agents/、repository Skillを.agents/skills/へ置きます。[1][2]

project/
├── AGENTS.md
├── .codex/
│   ├── config.toml
│   └── agents/
│       ├── explorer.toml
│       ├── worker.toml
│       └── reviewer.toml
├── .agents/
│   └── skills/
│       └── feature-delivery/
│           ├── SKILL.md
│           ├── references/
│           │   └── handoff-schema.md
│           └── scripts/
│               └── verify-changed-files.sh
└── src/

AGENTS.md: 変更禁止範囲、必須の検証、言語、承認条件など、親と子へ常時適用するリポジトリ方針
.codex/config.toml: 親のモデルとeffort、subagent全体の既定値、同時thread数
.codex/agents/: 子ごとの役割、モデル、effort、sandbox、専用ツール接続
.agents/skills/: 特定の依頼でだけ読み込む作業手順、参照資料、決定的なスクリプト

Skillは最初にnameとdescriptionだけが一覧へ入り、選ばれたときにSKILL.md本文が読み込まれます。この段階的な読み込みにより、使わない手順で初期コンテキストを埋めずに済みます。[2]

config.tomlで親とsubagentの既定値を設定する

.codex/config.tomlでは、親のmodelとmodel_reasoning_effortを上部へ、subagentの設定を[agents]へ置きます。次は、親に難しい判断を残し、子の既定を高速なworker向けにする例です。

model = "gpt-5.6"
model_reasoning_effort = "high"

[agents]
enabled = true
max_concurrent_threads_per_session = 4
default_subagent_model = "gpt-5.6-terra"
default_subagent_reasoning_effort = "low"

max_concurrent_threads_per_sessionは、親を除く同時subagent threadの上限です。並列数を固定すると、単純な依頼で子が増えすぎるのを防げます。明示的な起動指定やcustom agent側の値は、この既定値より優先されます。[1]

モデル名は固定の序列ではなく、仕事への適合で選びます。公式ガイドは、難しい多段作業の開始点にgpt-5.6、速さと効率を重視する探索や読み取り中心のworkerにgpt-5.6-terra、明確で反復的な大量作業にgpt-5.6-lunaを挙げています。[1] 利用できるモデルは環境で変わるため、設定時点のmodel一覧も確認します。

explorerは読み取り専用で短い根拠を返す

探索だけを行うagentは.codex/agents/explorer.tomlへ定義します。custom agentにはname、description、developer_instructionsが必須です。[1]

name = "explorer"
description = "Read-only codebase explorer. Use before planning changes to map execution paths, affected files, and existing tests."
model = "gpt-5.6-luna"
model_reasoning_effort = "low"
sandbox_mode = "read-only"
developer_instructions = """
Trace the requested behavior from its entry point.
Return affected files, the execution path, existing tests, and unknowns.
Cite files and symbols. Do not edit files or broaden the requested scope.
"""

探索結果の形式を固定すると、親は長いログを読まずに計画できます。Lunaで依存関係を追えない場合や、大規模なモジュール境界を判断する場合は、Terraまたは親と同等のモデルへ上げます。

workerは承認済み範囲だけを実装する

実装agentの.codex/agents/worker.tomlでは、変更範囲と停止条件を明確にします。workspace-writeは作業領域への書き込みを許可するため、親が対象ファイルと検証方法を確定した後にだけ使います。

name = "worker"
description = "Implementation worker for one approved, bounded change. Use only after the parent has fixed scope and completion criteria."
model = "gpt-5.6-terra"
model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"
developer_instructions = """
Implement only the assigned change.
Stop and report back if a product or architecture decision is still open.
Do not modify unrelated files.
Run only the validation named in the task and report changed files, results, and remaining risks.
"""

軽量workerに向くのは、変更対象、入力、期待結果、テストが決まった実装です。複数モジュールの設計や、仕様の矛盾解消までworkerへ含めると、親子の責務が逆転します。

reviewerはread-onlyで難しい判断へeffortを使う

レビューagentは.codex/agents/reviewer.tomlへ定義し、変更を加えず具体的な不具合だけを返します。探索と同じread-onlyでも、複雑なロジックやセキュリティ条件を確認するためeffortを上げられます。

name = "reviewer"
description = "Read-only reviewer for correctness, security, regressions, and missing tests after implementation."
model = "gpt-5.6-terra"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
developer_instructions = """
Review the changed behavior and the smallest necessary surrounding context.
Lead with concrete findings ordered by severity.
Include file references and reproduction conditions.
Do not edit files, and omit style-only comments without behavioral impact.
"""

同じモデルでも、探索はlow、実装はmedium、レビューはhighと分けられます。モデルを増やす前に、同じモデルのeffort調整で品質とコストの折り合いがつくかを確認します。

Skillには親が実行するオーケストレーション手順を書く

.agents/skills/feature-delivery/SKILL.mdには、親が入力を検査し、子へ渡し、結果を統合する順序を書きます。Skillは手順の再利用単位であり、子エージェントそのものではありません。[2]

---
name: feature-delivery
description: Use when adding one bounded feature with separate exploration, implementation, and review phases. Do not use for one-line edits.
---

## Input gate

Confirm the target behavior, non-goals, allowed files, completion criteria, and validation.
Return for clarification if any item changes the implementation direction.

## Orchestration

1. Spawn explorer for read-only impact analysis.
2. Keep planning and trade-off decisions in the parent thread.
3. Spawn worker only after scope and file ownership are fixed.
4. Wait for implementation and validation results.
5. Spawn reviewer for a read-only diff review.
6. The parent accepts or rejects findings and reports the consolidated result.

## Parallelism

Parallelize independent read-only work first.
Do not assign the same file to multiple writing agents.
Wait for every required result before synthesis.

Codexはrepository Skillを現在の作業ディレクトリからリポジトリrootまで探索します。[2] monorepoでは、全体共通のSkillをroot、特定packageだけのSkillをそのpackage配下の.agents/skills/へ置くと、適用範囲を分けられます。

親への依頼は役割・順序・待機を明示する

custom agentを作成しても、すべての依頼で自動的に並列化するとは限りません。公式ドキュメントは、明示的な依頼、またはAGENTS.mdやSkillの指示によってCodexが委譲すると説明しています。[1]

$feature-deliveryを使って設定画面の保存不具合を修正してください。

親threadは要件、計画、採否を担当します。
explorerで実行経路、別のexplorerで関連テストを並列調査してください。
両方を待って変更範囲を確定し、workerへ1つの実装を渡します。
実装後はreviewerがread-onlyで確認し、親が最終結果を統合してください。

良い委譲文には、目的、対象、非対象、期待する出力、完了条件、待機条件が含まれます。親が子の結果を待たずに次へ進むと、古い前提で実装やレビューを始める原因になります。

並列化は読み取り中心から始める

Codexの公式ガイドは、探索、テスト、トリアージ、要約などの読み取り中心の仕事を並列化の開始点として推奨し、複数agentによる同時編集には競合と調整コストがあると説明しています。[1]

flowchart TD
    P["親: 要件と完了条件"] --> A["explorer: 実行経路"]
    P --> B["explorer: テスト範囲"]
    A --> C["親: 計画を確定"]
    B --> C
    C --> W["worker: 限定実装"]
    W --> R["reviewer: 差分確認"]
    R --> S["親: 採否と統合"]

実装を並列にする場合は、別module、別file、または別worktreeのように所有範囲を分けます。同じ設定ファイルや共通schemaを複数workerが編集する作業は、順次実行へ戻すほうが安全です。

トークン管理は子の数を減らすだけでは不十分

subagent workflowは親のコンテキストから中間出力を分離しますが、子ごとにモデルとツールを動かすため、同等の単一agent実行より総トークンが増える場合があります。[1] 「軽量モデルを使ったから安い」と判断せず、重複探索と失敗後の再実行も含めて評価します。

管理対象	増える原因	制御方法
親の入力	生ログ、重複した調査結果	子の出力schemaを短い根拠付き要約にする
子の入力	大きすぎる委譲文、不要なSkill	対象、非対象、必要なSkillだけを渡す
子の出力	終了条件がなく探索を続ける	最大範囲、完了条件、未確認の返し方を決める
再実行	低すぎるmodel/effort、曖昧な境界	昇格条件と入力gateを定義する
並列競合	同じfileや共有状態の同時変更	読み取りを並列化し、書き込み所有者を1人にする

コストを下げる順序は、不要なagentを起動しない、重複をなくす、出力を圧縮する、その後にmodelとeffortを下げる、です。モデルを先に下げて成功率を落とすと、再試行で総量が増えます。

設定後はthreadと権限を確認する

次の確認が通れば、親子構成を実務で試せます。

AGENTS.mdに常時必要な制約だけがある
Skillのdescriptionから使う場面と使わない場面が分かる
explorerとreviewerがread-onlyで動く
workerは承認済みの1つの変更だけを担当する
[agents]の同時thread数が作業規模に合っている
並列の書き込み担当が同じfileを所有していない
親が全結果を待ち、採否を判断してから完了を報告する
子の結果をagent threadで開き、要約と根拠が一致することを確認できる

参考文献

OpenAI, Subagents
OpenAI, Build skills

最新のリリースやアップデートの詳細は、公式サイト・公式ドキュメントを確認してください。