Claude Code v2.1.172：サブエージェント5階層ネスト完全ガイド
「Capped at depth=5 to start. Lmk what you think!（深さ5で始めました。使ってみて感想を教えてください）」。Claude Codeのリード開発者Boris Chernyが2026年6月9日にX（旧Twitter）でこう投稿した翌日、v2.1.172が正式リリースされた（Boris Cherny on X）。
Claude Codeのサブエージェントが、サブエージェントを呼び出せるようになった。最大5階層まで。2026年の大半を通じて「サブエージェントはネストできない」と公式ドキュメントに明記されていたルールが、v2.1.172で覆された。
- Claude Codeでサブエージェントを日常的に使っているエンジニア
- マルチエージェントの設計コストと落とし穴を把握したいPM・テックリード
- Agent Teams、Dynamic Workflowsとの使い分けを整理したい方
何が変わったか。ネスト禁止からネスト許可へ
v2.1.172以前、Claude Codeのサブエージェントには一つの絶対ルールがあった。「サブエージェントは別のサブエージェントを呼び出せない」。公式ドキュメントにも明確に記載されており、Agentツールをサブエージェントのtools配列に含めることは禁止されていた（公式サブエージェントドキュメント）。
この設計は意図的なものだった。無限ループによるコスト爆発を防ぐ仕組みとして機能していた。ところが6月10日のリリースで、Anthropicはその制約を外した。ネストを許可しつつ、深さ5というハードキャップをサーバー側で強制する方式に切り替えた。
注意点がある。リリース時点で公式ドキュメントは更新されておらず、code.claude.com/docs/en/sub-agentsのPlanサブエージェントタブには「サブエージェントはネストできない」という旧記述が残っている（2026年6月12日時点）。機能の確認はGitHubリリースノートと公式changelogで行うべきだ（公式changelog）。
ネストの技術的な仕様
各階層のサブエージェントについて、公式ドキュメントで以下の動作が確認されている。
- コンテキストの独立性: 各サブエージェントはゼロから始まる新しいコンテキストウィンドウを持つ。親エージェントの会話履歴はいっさい引き継がない
- 返却されるのは最終出力のみ: 子エージェントの途中経過（ファイル読み込み、ツール呼び出し）は親の視点からは見えない。最終メッセージだけが上に返る
- モデルの個別指定が可能:
AgentDefinitionのmodel:フィールドで各階層に異なるモデルを設定できる。'fable'、'opus'、'sonnet'、'haiku'、あるいはフルモデルIDが使える - CLAUDE.mdは各階層で読み込まれる: ただしExploreやPlanの組み込みサブエージェントは速度優先で読み込みをスキップする
- 深さの数え方: ルートエージェントがdepth=1、最深部の葉エージェントがdepth=5
availableModelsの制限がサブエージェントのモデル指定に適用されない不具合も、v2.1.172で修正された。組織レベルのモデル許可リストが正しくサブエージェントにも適用されるようになっている。
5階層の実用マップ — 各レベルの役割と推奨モデル
コミュニティの知見を統合すると、5階層ネストの実用的な割り当ては次のようになる（ofox.ai分析、claudefa.stガイド）。
| 階層 | 役割 | 推奨モデル | 典型的なタスク |
|---|---|---|---|
| L1（ルート） | 全体オーケストレーター | Opus 4.8 | 「OAuth2統合を実装せよ」を仕様に分解 |
| L2（ドメインリード） | アーキテクチャ計画 | Sonnet 4.6 | バックエンド・フロントエンド・テストの担当割り当て |
| L3（モジュールリード） | ファイルグループ調整 | Sonnet 4.6 | src/auth/を担当し、スキーマとルートを調整 |
| L4（実装） | 専門作業者 | Haiku 4.5 | token_handler.pyを書き、linterを実行して差分を返す |
| L5（検証） | バリデーター | Haiku 4.5 | テストを実行し、合否サマリーを親に返す |
ただし、これは理想的なケースだ。コミュニティの総評は「depth=3が『これは動いた』の最低ライン。5階層は上限であって目標ではない」（claudefa.st）というものだ。
設計の核心は「コンテキスト管理のためのネスト」であって「並列化のためのネスト」ではない、という点だ。Boris Cherny自身がそのモチベーションを明言している。各サブエージェントが自分のコンテキストウィンドウを埋め始める前に、下位レベルに仕事を委譲できる。冗長なログ、テスト結果、大量のファイル読み込みを親から見えない下位エージェントに隔離し、上位エージェントの「目」をきれいに保つ。
日本語コミュニティでもqiita/@nogataka氏が「計画・生成・評価の3分離パターン」として整理しており、各フェーズを独立したサブエージェントに任せることでコンテキストの汚染を防ぐアプローチを紹介している（Qiita/@nogataka）。
コストの現実 — 7倍から始まる乗数地獄
ネストを使う前に、数字を直視する必要がある。
公式ドキュメントによると、Agent Teamsを使うと通常セッションの約7倍のトークンを消費する。各エージェントが独立してCLAUDE.md、MCPツール定義、プロジェクトコンテキスト、システムプロンプトをフルレートで読み込むためだ（公式コストドキュメント）。ネストはこの乗数をさらに深くする。
GitHub Gist（@yurukusa）がコミュニティ事例をまとめた「なぜClaude Codeはこんなにトークンを使うのか」という13パターンのカタログには、サブエージェントのファンアウトが原因で$8,000〜$47,000の請求が発生したとされるケースが複数記録されている（個人による事例集約、yurukusa GitHub Gist）。
AICosts.aiは金融サービスチームがサブエージェントを放置した結果3日間で数万ドル規模のトークンコストが発生した事例を報告している（詳細はAICosts.ai参照。第三者ブログによる報告であり独立検証はしていない）。yurukusa氏のコミュニティ事例集でも「サブエージェントファンアウトで$8,000〜$47,000の請求が発生したと報告されるケース」が複数まとめられている。
日本のコミュニティでも事情は同じだ。uravation.comの試算では、1日8回のサブエージェントセッション（入力30万トークン+出力3万トークン）を日常的に回す場合、APIレートで月約$237.60になるとされている。Claude Max 5xプラン（月$100）との比較では、サブエージェントの使用が習慣化した時点でサブスクリプションの方がコスト効率が高くなる（uravation.com）。
コスト試算（参考値）
下表は2026年6月時点の公式APIレート（Opus 4.8: 入力$5/MTok・出力$25/MTok、Sonnet 4.6: 入力$3/MTok・出力$15/MTok、Haiku 4.5: 入力$1/MTok・出力$5/MTok）を基に、1セッション各階層50kトークン（入力30k・出力20k）と仮定して試算した参考値だ。実際のコストはプロンプト内容・キャッシュヒット率・モデルバージョンにより異なる。
| 構成 | 1回のコスト（参考） | 5階層合計（参考） |
|---|---|---|
| 全階層Opus 4.8 | $0.65 | $3.25 |
| 全階層Sonnet 4.6 | $0.39 | $1.95 |
| 全階層Haiku 4.5 | $0.13 | $0.65 |
| 実用構成（Opus→Sonnet→Haiku×3） | — | 約$1.11 |
コスト管理の基本は3つ。model: haikuを下位階層に指定すること、/usageコマンドでサブエージェント名別のトークン内訳を確認すること、Claude Consoleでワークスペースの上限を設定することだ。
設計の落とし穴 3選
ネストを使い始めるときに踏みやすい問題を整理する。
落とし穴1：状態が引き継がれない
最も多い失敗は「上位で決めたことが下位に伝わっていない」パターンだ。各サブエージェントは新しいコンテキストウィンドウから始まるため、L1で決定したアーキテクチャ選択（「SQLiteではなくPostgresを使う」など）はL3の実装エージェントには見えない。
CLAUDE.mdにアーキテクチャ上の決定事項を記録する習慣を持つことが根本的な対策だ。各サブエージェントは起動時にCLAUDE.mdを読み込むため、そこに書いた内容は全階層で共有される。動的なセッション内の決定は、スポーンするプロンプトに明示的に含める必要がある（公式Agent Teamsドキュメント）。
落とし穴2：コンテキスト爆発
下位エージェントが大量のツール出力、テストログ、ファイル内容を処理する場合、そのコンテキストウィンドウが急速に埋まる。公式ドキュメントはこれを「コンテキストウィンドウに生の履歴と冗長なツールペイロードを詰め込むと、エージェントが重くなり高額になる」と明確に警告している。
対策は「下位エージェントに隔離を担わせる」設計だ。ログ解析、大量ファイル読み込み、テスト実行を専用の葉エージェントに委譲し、その結果サマリーだけを親に返す。Claude CodeのライフサイクルフックPreToolUse（ツール実行直前に発火するフック）を使ってツール出力をフィルタリングする方法も有効だ。
yamato_snow氏はZennで3ヶ月間のサブエージェント運用を振り返り、「エージェントはチャットの約4倍のトークンを使う」と自身の計測から報告。さらに「SubAgentは3ヶ月でContext Rot（長時間セッションでのLLM精度低下）、トークン浪費、セッション切断の3課題すべてに対処できるようになった」と述べている（Zenn/yamato_snow, 2026年3月）。この4倍という数値は一般的なエージェント利用の個人計測値であり、公式ドキュメントが示すAgent Teamsのplan modeにおける「7倍」とは計測条件が異なる点に注意したい。
落とし穴3：ファイルの競合
複数のサブエージェントが並列で動いて同じファイルを編集しようとすると、上書きが発生する。Agent Teamsのタスクリストにはファイルロック機構があるが、直接のファイル編集は保護されない。
スポーンするプロンプトにファイルオーナーシップを明示することが現実的な対策だ（「あなたはsrc/auth/を担当する。src/api/には触れるな」）。競合が許容できないプロジェクトでは、GitHub Copilotの/fleetコマンドが使うgitワークツリーによる自動分離の方が適している。
Agent Teams・Dynamic Workflowsとの使い分け
Claude Codeにはマルチエージェントのパターンが3つある。ネストしたサブエージェントだけが選択肢ではない。
| パターン | 構造 | 向いているケース |
|---|---|---|
| ネスト型サブエージェント | 階層型（最大5階層） | 大きなタスクの再帰的分解。コンテキストの隔離が目的 |
| Agent Teams | ピアツーピア（リード+チームメート） | 独立したファイルセットを並列で担当させる。2026年6月時点では実験的 |
| Dynamic Workflows | JS/TSスクリプトで制御 | 数百エージェントのファンアウト。処理量が予測可能なバッチ作業 |
qiita/@nogataka氏は「サブエージェントは単一セッション内のタスク委譲、Agent Teamsは独立したインスタンス間の調整」という定義が最も明確だと指摘している（Qiita/@nogataka）。
注意点として、Agent Teamsは2026年6月時点で実験的機能（オプトイン環境変数が必要）であるのに対し、ネスト型サブエージェントとDynamic WorkflowsはGAステータスだ。
Zennのマルチエージェント比較記事（2026年）ではClaudeはコンテキスト管理で優位、OpenAI Codexは1,000回以上のツール呼び出しに耐える持久力で優位、Google Geminiは大規模コスト効率で優位という評価がまとまっている（Zenn/hiraoku）。
2026年6月12日時点で、公式サブエージェントドキュメントの一部には「サブエージェントはネストできない」という旧記述が残っている。機能の最新状態はGitHubリリースノートとcode.claude.com/docs/en/changelogで確認すること。SDKドキュメント（code.claude.com/docs/en/agent-sdk/subagents）も同様に旧情報が残っている。
Claude Codeのコスト管理を詳しく学ぶ
サブエージェントのトークン消費、プロンプトキャッシュ活用、Maxプランとの比較を解説しています。
関連記事
- Claude Code Dynamic Workflows完全ガイド2026｜数百エージェント並列実行の設計
- Claude Code Agent SDK：サブエージェント設計の実践ガイド2026
- Claude Code Maxプランとxhigh自動モード — コスト爆発を防ぐ設定
本記事の情報は2026年6月12日時点のものです。Claude Codeのバージョンや仕様は頻繁に更新されます。最新情報は公式changelogでご確認ください。
