Claude Code 入れ子サブエージェント完全ガイド｜5階層・トークン7倍の落とし穴【2026年6月】

「ひとつのタスクで148,000トークン、6回の試行、合計21分。コードは一行も自分で書いていない。」これは英Owain Lewis氏が入れ子サブエージェントを実機で試した記録から拾った数字だ。質は確かに高い。だが対価としてのトークン消費と時間は無視できない量になる。

2026年6月10日、AnthropicはClaude Code v2.1.172をリリースした。目玉はひとつ。サブエージェントが自分の子サブエージェントを呼び出せるようになった。最大5階層までだ。それまでの公式ドキュメントは「サブエージェントは他のサブエージェントを呼べない」と明記していた。無限再帰の防止が理由だ。その制限が、ついに解除された。

この記事では、入れ子サブエージェントの仕組みと、実ユーザーの成功事例・失敗事例の両方を踏まえて、本当に使うべき場面と避けるべき場面を整理する。

入れ子サブエージェントとは — まず仕組みから

Claude Codeのサブエージェントは、メインのClaude（親）が tool call として別のClaudeインスタンス（子）を呼び出す機能だ。子は新しいコンテキストウィンドウで動き、終了時に「要約された結論」だけを親に返す。子の途中経過は親には届かない。

v2.1.172から、この子がさらに孫を呼べるようになった。深さは5まで。深さ0が起点のメイン会話、深さ1が最初のサブエージェント、深さ5が末端の葉だ。それより深い呼び出しはClaude Code側で拒否される。

階層	役割	コンテキスト
深さ0	メイン会話（コーディネーター）	全期間共有
深さ1	直接のサブエージェント	独立した200K
深さ2〜4	中間の子・孫	各層で独立
深さ5	末端（葉）	独立、最深

なぜ Anthropic はこの機能を解禁したのか

2026年初頭、Anthropic公式のClaude Code Subagentsガイドは「サブエージェントは他のサブエージェントを生成できない」と明記していた。Owain Lewis氏は同じ時期のCodex（OpenAI製）がmax_depth設定で入れ子を許していた点を引き合いに、「Claude Codeでは30階層でも勝手にネストできてしまう状態だった、ガードレールがほしい」と書いていた。

つまり実装の問題ではない。あくまで設計判断として「使うな」と言っていたわけだ。

その方針が転換した背景は、Anthropic公式のリリースノートとclaudefa.stのまとめを読む限り、3つに整理できる。

1. コンテキスト汚染問題が無視できなくなった。1Mトークンのコンテキストを持つOpus 4.6/4.7でも、深いリサーチや大規模リファクタリングでは200K〜400Kを使い切るケースが頻発。途中のツール呼び出しを末端に追いやって、親の会話を守る必要が出てきた。

2. Multi-agentパターンの定着。コミュニティ製プラグイン（Deep Trilogy等）や、自分の記事でも紹介したClaude Code Reviewなど、複数エージェント協調が実戦投入されている流れ。

3. 5階層という現実的な天井。Anthropicは「無限ではなく5」と上限を切った。同社のエンジニアリングブログ風に言えば「4階層先のClaudeが本当にベストな仕事をするのか、まだ誰も知らないからこそ5で切った」というスタンスだ。

実例：何ができるようになったのか

1. 大規模リサーチの “結論だけ” を持ち帰る

/research-deep "GraphQL N+1問題のうちうちのコードベースで該当する箇所" のような曖昧で広いタスクを投げた場合。

• 深さ1: 全リポジトリのGraphQLレゾルバを列挙
• 深さ2: 各レゾルバについて、DataLoaderの有無を確認
• 深さ3: 該当箇所のSQLログ取得を試行
• 深さ4: ログ分析と該当箇所の絞り込み

このうち、深さ2〜4の途中経過はすべて末端で消化され、深さ1の出力は「該当ファイル7個、優先度高3個、修正案2パターン」のような結論サマリだけになる。Owain Lewis氏がニュースレターで「the separation of concerns is genuinely useful」と評価しているのはこの形だ。

2. デバッグの “汚い試行錯誤” を隔離

バグの再現コードを書く・実行する・スタックトレースを読む・該当行を絞り込む、という一連の流れ。これを子エージェントに丸投げすると、親は「原因はこのモジュールのこの行、修正案はこちら」だけ受け取れる。

Claude Code v2.1.172 Release Notesでは、この用途を「impact scope investigation」と呼んでいる。バグ修正の影響範囲を子に調べさせ、親の判断材料だけ上げる、という考え方だ。

3. PR 単位の自動レビューを一段深く

マルチエージェントによるコードレビューで書いたパターンに対し、入れ子でレビュアーがファクトチェックの孫を呼べるようになった。「このコードはOWASP Top10のA01に該当するか」を孫に検証させ、レビュアー（親）には結論だけ渡す、という設計が組める。

「影」の部分 — トークン消費が爆発する

ここが正直に書くべきところだ。

Anthropic公式 “最大7倍” の根拠

AnthropicのManage costs effectivelyドキュメントには、マルチエージェント構成のトークン消費に関する記述がある。サブエージェントを使った構成ではシングルスレッド比で約7倍のトークン消費になりうる、というのが公式の試算だ。ファンアウトとは、親が複数の子を同時に呼び出して仕事を分散させる構造を指す。

入れ子の場合、この7倍が単純に重なるわけではないが、各層がさらにファンアウトすれば指数関数的にコストが膨らむ可能性は残る。新規セッションを開くたびに約20Kトークン程度のベースラインが消費される（ofox.aiの解説）ため、深い階層を多数走らせると「起動費だけで」数十万トークンに達する計算になる。

実話：49個のエージェントが$8,000を吹き飛ばした

AICosts.aiが報告したケースが衝撃的だ。あるエンジニアが自作の /typescript-checks スラッシュコマンドで49個の専門サブエージェントを並列実行し、2.5時間で消費トークンは毎分887,000、見積もり費用は**$8,000〜$15,000**に達したという。

これは入れ子ではなく並列の話だが、教訓は重なる。「ガードレールを設定しないまま走らせると、想像の桁を超える」。Owain Lewis氏も「Claude Codeは（v2.1.172前は）30階層でも止まらなかった、これは怖い」と書いていた。5階層の上限はこの恐怖への回答でもある。

個人開発者の実感に近い数字で言えば、Claude Maxプラン（月額$200）の使用枠は、入れ子+ファンアウトを油断して走らせると1回のセッションで丸ごと吹き飛ぶ規模感だと考えていい。API従量課金で運用している場合の被害は、さらに直接的だ。

“orphan tokens” 問題

中間の子エージェントが消費したトークンは、親には結論しか返らないが請求には乗る。これをofox.aiの解説記事は「orphan tokens（孤児トークン）」と呼んでいる。

orphan tokens（孤児トークン）とは、親に結論しか届かない一方で、中間階層が消費したトークンは課金対象として残る現象を指している。要約後の結論は数百トークンに圧縮されているのに、その背後で深さ4まで降りた孫が10万トークンを使っていた、というケースが起きる。請求書を見て初めて気づく類のコストだ。

落とし穴 — 5階層を実際に動かして見えた問題

1. 品質劣化の “距離問題”

これは明確に立証された話ではないが、コミュニティで議論が続いている。4階層離れたClaudeが、もとのプロンプトの意図を正しく汲み取れるのか。

仕組み上、子エージェントは親の会話全体を見ない。「親が要約して渡したプロンプト」だけを起点に動く。深さ1での要約、深さ2での再要約、深さ3でのさらに再要約……と続くと、もとの意図から遠ざかるリスクが生まれる。

Anthropic自身が「5階層という上限は、品質が保てるか分からないからこそ設けた」というスタンスだ。実務上は2〜3階層に留めるのが現実解だと多くの記事が結論づけている（ChatForestの実証記事）。

2. デバッグが極端に難しい

入れ子の中で何かがおかしくなったとき、どの階層で何が起きたかを追うのが地獄になる。中間のログは末端で消化されているからだ。

claudefa.stのガイドはこの問題への対策として、CLAUDE_CODE_AGENT_TRACE=1 環境変数による全階層ログ出力を推奨している。ただしログ自体が膨大になるため、本番運用では絞り込みが必要だ。

3. ホワイトリスト未設定での暴走

サブエージェントの定義ファイル（.claude/agents/<name>.md）の YAML フロントマターには tools: セクションがある。

---
name: researcher
description: 大規模リサーチを行う
tools: Read, Grep, Agent(verifier)
---

ここに Agent(verifier) のように呼び出せる子エージェントを明示的に列挙する。これを書き忘れて Agent(*) のような書き方をすると、想定外の子エージェントを呼んで暴走する。

ofox.aiの記事は「3つの落とし穴」の筆頭にこのホワイトリスト未設定を挙げている。Pitfall #1だ。

電脳狐影の判断：使う場面と避ける場面

PMとしての判断を書く。

使う場面

• 大規模リファクタリングの調査段階。「このリポジトリのどこを直すべきか」を深く調べさせて、結論だけ受け取る。実装は人間（+Claude）でやる
• 複雑なバグの原因追跡。再現・ログ取得・スタックトレース解析を子に任せ、修正案だけ親で議論
• マルチ観点のレビュー。コード品質・セキュリティ・性能を別々の子に判定させ、孫でファクトチェック

避ける場面

• 小さな修正タスク。1ファイル20行の変更に入れ子は完全にオーバースペック
• コスト管理ができていないチーム。請求書ショックは想像以上にきつい
• デバッグスキルが浅い段階。何が起きているか分からないまま深い階層を動かすのは危険

PMとして見ると、これは 「タスクの分解と委譲」がそのままアーキテクチャになっている機能だ。人間の組織でも、5階層の指揮系統は機能不全を起こす。Claudeも同じだろうと推測する。技術の深い部分はPMとしての理解では追いきれない部分もあるが、「2〜3階層に留めて、5は使わない」を当面の運用ルールにしたい。

v2.1.183 で追加された “git安全装置”

入れ子サブエージェントの話とは別だが、同じ6月のv2.1.183（6月19日リリース）では auto modeでの破壊的gitコマンドの自動拒否が追加された。

「Claudeが勝手に git reset --hard を打ってローカルの変更が消えた」というインシデントへの対応だ。サブエージェントの深い階層で git 操作を行わせる場合は特に、このバージョン以降に上げておく価値がある。詳細はClaude Code auto modeパーミッションガイドで書いた。

まとめ：今日やること

1. claude --version で現在のバージョンを確認、v2.1.172未満なら claude update
2. 既存のサブエージェント定義の tools: セクションに Agent(<child_name>) の明示列挙があるか点検
3. 入れ子を試すときは深さ2から始める。3階層以上に踏み込むのはコスト試算後に
4. v2.1.183以降にも上げ、auto modeのgit安全装置を有効化

入れ子サブエージェントは、「タスクの汚い部分を末端に追いやって、親をクリーンに保つ」ためのアーキテクチャ装置だ。並列化の高速化ツールではない。この理解を間違えると、トークン課金がそれを教えてくれる。

---

免責事項: 本記事の情報は2026年6月20日時点のものだ。Claude Codeのバージョン番号・機能仕様・料金体系は変更される可能性がある。導入前に公式ドキュメント（code.claude.com）で最新情報を確認してほしい。実コスト試算は使用モデル・トークン単価・実行内容により大きく変動する。Claude、Claude Code、Anthropicは Anthropic, PBC の商標。