Claude Codeの親子エージェント設計

約10分

Claude Codeで親エージェントと専門subagentを設計し、モデルとトークンの使い方を最適化したい開発者

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

Claude Codeでは、全体設計と最終判断を親エージェントに残し、探索、実装、レビューを別のコンテキストへ分けられます。ここでは、親を高性能モデル・高effortにし、子を仕事の難しさに応じて軽量化する構成を、実際にリポジトリへ追加できる形で作ります。

親は判断を持ち、子は境界の明確な仕事を担当する

親エージェントは、ユーザーと会話して要件、制約、分割方法、採否を決めるメインのClaude Codeセッションです。subagentは、親から1つの仕事を受け取り、別のコンテキストで調査や実装を行って要約を返します。Claude Codeでは、子ごとにシステム指示、モデル、effort、ツール、権限を定義できます。[1]

このページで学べること

親に残す判断とsubagentへ渡す実行を分けられる
.claude/agents/と.claude/skills/の役割を説明できる
探索、実装、レビューのagent定義を作成できる
model、effort、tools、worktreeを仕事のリスクに合わせて選べる
通常のsubagentとAgent Teamsを使い分けられる

「親は常に最上位、子は常に最軽量」という固定ルールにはしません。曖昧な判断は親へ残し、子の仕事が単純になるほどモデルとeffortを下げるのが基本です。実装やセキュリティレビューに必要な能力まで下げると、再作業が増えて総コストが上がります。

flowchart LR
    U["ユーザー"] --> P["親: 要件・分割・採否"]
    P --> E["explorer: 読み取り調査"]
    P --> W["implementer: 限定実装"]
    P --> R["reviewer: 差分検証"]
    E --> P
    W --> P
    R --> P

ディレクトリは方針・役割・手順を分離する

リポジトリへ保存する設定は、常時適用する方針、子エージェントの役割、必要時だけ読む手順へ分けます。Claude Codeはproject subagentを.claude/agents/、project Skillを.claude/skills/<name>/SKILL.mdから読み込みます。[1][2]

project/
├── CLAUDE.md
├── .claude/
│   ├── agents/
│   │   ├── explorer.md
│   │   ├── implementer.md
│   │   └── reviewer.md
│   └── skills/
│       └── feature-delivery/
│           ├── SKILL.md
│           ├── references/
│           │   └── handoff-schema.md
│           └── scripts/
│               └── verify-changed-files.sh
└── src/

CLAUDE.md: 変更禁止範囲、必須コマンド、言語方針など、セッション全体で常に必要な事実
.claude/agents/: 子の役割、model、effort、tools、権限、完了時の報告形式
.claude/skills/: 繰り返し使う作業手順。説明が依頼に一致したときだけ本文が読み込まれる
references/: Skill本文へ常時入れる必要がない詳細仕様
scripts/: 同じ結果を返す検証や変換をLLMではなくプログラムで実行する部品

Skill本文は呼び出した後のコンテキストへ残るため、短い入口と必要な参照先だけを置きます。[2] モデルの役割はagentへ、作業の順序と完了条件はSkillへ書くと、同じ手順を別のagentでも再利用できます。

読み取り専用のexplorerを軽量モデルで定義する

探索は大量の検索結果を生みやすいため、親のコンテキストから分離する効果が大きい仕事です。.claude/agents/explorer.mdを作り、編集ツールを与えず、結果をファイル参照付きの要約へ限定します。

---
name: explorer
description: 変更前のコード探索を担当する。影響範囲、実行経路、既存テストの場所を調べるときに使う。ファイルは変更しない。
tools: Read, Grep, Glob
model: haiku
effort: low
permissionMode: plan
maxTurns: 12
---

対象の実行経路を入口から追跡してください。

返す内容:
1. 関係するファイルと役割
2. 変更が伝播する経路
3. 既存テストと不足している確認
4. 未確認事項

推測で修正案を広げず、根拠となるファイルを示してください。

model: haikuとeffort: lowは、範囲が明確な読み取り調査を速く処理する例です。探索対象が巨大、依存関係が複雑、または出力品質が不足する場合は、sonnetやmediumへ上げます。Claude Codeはmodelにaliasまたは完全なmodel IDを使え、effortは対応モデルでlowからmaxまで指定できます。[1]

implementerはworktreeで変更範囲を隔離する

実装workerには編集権限が必要ですが、親の作業ディレクトリと同じ場所を並列に変更させると競合します。.claude/agents/implementer.mdでisolation: worktreeを指定すると、一時的なGit worktreeで作業させられます。[1]

---
name: implementer
description: 承認済みの計画から、境界が明確な1機能を実装して対象テストを実行する。設計判断が残る場合は実装せず親へ返す。
tools: Read, Grep, Glob, Edit, Write, Bash
model: sonnet
effort: medium
permissionMode: acceptEdits
isolation: worktree
maxTurns: 24
skills:
  - feature-delivery
---

親から渡された対象と完了条件だけを実装してください。
無関係なリファクタリングは行いません。

完了時に、変更ファイル、実行した検証、未解決事項を返してください。

実装には、探索より高い判断力が必要です。そのため、この例では軽量な探索agentと、バランス型の実装agentを分けています。Haikuで十分と評価できた単純変換だけをさらに軽量化し、仕様解釈を伴う変更はSonnet以上へ残します。

reviewerは編集せず高めのeffortで差分を検証する

レビューはコードを書き直す仕事ではなく、見落としを探して親へ判断材料を返す仕事です。.claude/agents/reviewer.mdでは編集ツールを外し、レビュー観点と重大度を固定します。

---
name: reviewer
description: 実装後の差分を正しさ、セキュリティ、回帰、テスト不足の観点でレビューする。ファイルは変更しない。
tools: Read, Grep, Glob, Bash
model: sonnet
effort: high
permissionMode: plan
maxTurns: 18
---

変更差分と関係する実行経路だけを確認してください。
具体的な不具合を重大度順に返し、各項目に根拠ファイルと再現条件を付けます。
根拠のない懸念、好みだけの指摘、直接の編集は行いません。

同じSonnetでも、実装はmedium、複雑な検証はhighにできます。モデル名だけでなくeffortも仕事に合わせることで、難しいレビューへ推論量を集中できます。

Skillには分割・引き継ぎ・終了条件を書く

.claude/skills/feature-delivery/SKILL.mdには、親が何を確定してから子を起動し、何を受け取って次へ進むかを書きます。Skillは、依頼が説明と一致したときに読み込まれる再利用手順です。ファイルを開くと、入力、工程、完了条件をチームで確認できます。[2]

---
name: feature-delivery
description: 既存リポジトリへ限定的な機能を追加し、探索、実装、レビューを分担するときに使う。
---

## Input gate

- 変更する振る舞い
- 変更しない振る舞い
- 完了条件
- 実行を許可された検証

不足があれば親へ返し、実装を始めない。

## Workflow

1. explorerへ影響範囲の調査を委譲する。
2. 親が調査結果から計画とファイル所有範囲を確定する。
3. 独立した変更だけをimplementerへ渡す。
4. implementerの検証結果を受け取る。
5. reviewerへ差分レビューを委譲する。
6. 親が指摘を採否判断し、最終結果を統合する。

## Completion

- 完了条件と検証結果が対応している
- 未解決事項が明示されている
- 同じファイルを複数agentが同時編集していない

Skillからsubagentへ事前に知識を渡したい場合は、agent定義のskillsへSkill名を列挙できます。Claude CodeはそのSkill本文を子の開始時に読み込みます。[1] ただし、すべてのSkillを読み込ませると子の初期コンテキストが増えるため、その役割に必要なものだけを指定します。

親への依頼は分割条件と統合条件を含める

設定を作った後は、親へ次のように依頼します。

Opusとhigh effortで親として作業してください。
最初に要件、非対象、完了条件を確定し、まだ設計判断が残る間は実装を委譲しないでください。

1. explorerで影響範囲を調べる
2. 独立した変更だけをimplementerへ渡す
3. 実装後にreviewerで差分を確認する
4. 親が結果を統合し、未確認事項と検証結果を報告する

同じファイルを複数agentへ同時に編集させないでください。

親のモデルとeffortはセッションで選び、agent定義では子の設定を固定します。子が親の会話履歴をそのまま受け取るわけではないため、委譲文には目的、対象、非対象、期待する出力、完了条件を含めます。[1]

Agent Teamsは子同士の協調が必要な場合だけ使う

Agent Teamsでは、team lead、複数のteammate、共有タスクリスト、mailboxによるメッセージを使います。[3] 通常のsubagentより適するのは、途中結果を交換する調査、競合仮説を試すデバッグ、フロントエンドとバックエンドの担当が契約を調整する実装です。

Agent Teamを作り、architect、frontend、backendの3 teammateを起動してください。
architectはAPI契約と完了条件を確定し、frontendとbackendは別ファイルを所有します。
契約変更はmailboxで全員に共有し、統合前にteam leadが差分を確認してください。

Agent Teamsは実験的で既定では無効です。また、各teammateが独立したコンテキストを持つため、トークン使用量は人数に応じて増えます。[3] 結果だけを返せばよい仕事でTeamsを使わないことが、最初のコスト管理になります。

トークン管理は総量・親の文脈・再作業を分けて測る

subagentは親のコンテキストを節約できますが、システム全体の総トークンを必ず減らすわけではありません。子はそれぞれ独立してモデルとツールを使うため、並列数を増やすほど総量は増えます。AnthropicのResearch事例でも、multi-agentは通常のchatより多くのトークンを使うと報告されています。[4]

設計の評価では、次の3つを分けます。

指標	確認すること	改善方法
総トークン	親と全subagentが使った合計	agent数、turn上限、重複調査を減らす
親のコンテキスト	親へ戻る中間出力の量	生ログではなく根拠付き要約を返す
再作業	誤った分割や低すぎるモデルでやり直した量	入力gate、完了条件、model/effortの昇格条件を決める

軽量化は、成功率を維持できる範囲で行います。explorerの結果が不足したら、haiku/lowからsonnet/mediumへ上げます。reviewerの指摘が表面的な場合はeffortを上げます。このような昇格条件をSkillへ追加すると、運用が安定します。

設定後は役割・権限・競合を確認する

次の確認がすべて通れば、親子構成の最小形ができています。

親だけが要件、分割、最終採否を担当する
各agentのdescriptionから起動条件と非対象が分かる
explorerとreviewerに不要な編集権限がない
implementerの変更範囲と完了条件が1つに絞られている
並列実装は別ファイルまたはworktreeへ分離されている
Skillが入力不足、失敗、昇格、終了の条件を持つ
subagentの要約だけで親が採否を判断できる

参考文献

Anthropic, Create custom subagents
Anthropic, Extend Claude with skills
Anthropic, Orchestrate teams of Claude Code sessions
Anthropic, How we built our multi-agent research system, 2025-06-13

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