Claude Codeでネストしたサブエージェントを使って大規模なタスクを委任する方法

Claude Code v2.1.172で何が変わったのか？#

ここ数か月、Claude CodeのAIエージェントについて何か読んだことがあれば、同じ言葉を目にしたはずです。公式ドキュメントにも、私のサブエージェントに関するガイドにも、競合分析のどれにも載っています。それは「サブエージェントは別のサブエージェントを起動できない」というものです。2026年6月11日現在も、code.claude.com/docs/en/sub-agentsの3か所にその記述が残っています。Anthropicがまだ更新していないだけです。

6月10日20:44 UTC、Claude Code v2.1.172がGitHub Releasesに登場しました。主な変更履歴の項目は一行でした。

このリリースでは、ネストでしか起きないバグも修正されました。バックグラウンドのサブエージェントが起動したネスト先のサブエージェントを停止した後も、エージェントパネルでアクティブとして強調表示されたままになるというバグです。

公式ドキュメントとリリース済みビルドの内容が食い違ったままの、珍しいケースです。続いて、ネストが並列サブエージェントとどう違うのか、「深さ5」とは何を意味するのか、そして現在実際に役立つ3つのシナリオを説明します。

ネストしたサブエージェントは、並列型や逐次型とどう違うのか？#

この3つの方法を手作業で試すのに長い時間をかけました。私の捉え方はこうです。委任には幅、長さ、深さという3つの次元があります。それぞれ異なる問題を解決します。

幅—並列サブエージェント。 メインチャットが同じ階層にある独立したサブエージェントをN個起動します。それぞれが範囲の狭いタスクを受け取り、個別のウィンドウで作業し、結果だけを返します。幅は速度の問題を解決します。5つのサブエージェントが並列に作業すれば、1つが同じ作業を逐次的に行う時間で完了します。これは、私のworktreeを使った並列サブエージェントのガイドで取り上げたモデルです。

長さ—サブエージェントの連鎖。 Aが作業し、結果をBに渡します。Bが作業してCに渡します。それぞれが前のエージェントからの入力を受け取ります。長さは順序を決めます。BはAからデータを受け取るまで始められません。典型例は、まず調査用サブエージェントが情報源を集め、次に編集用サブエージェントがその情報をもとに記事を書き、最後にファクトチェック用サブエージェントが記事を確認する流れです。これは平坦な一連の処理で、メインチャットが全体の筋書きを保持します。

深さ—ネストしたサブエージェント。 AがBを起動し、BがCを起動し、CがDを起動します。それぞれの子は親の中で独立したウィンドウを使って作業し、親には結果だけを返します。メインチャットには、子、孫、ひ孫の中で起きていることが何も見えません。これがv2.1.172の新機能です。

よくある誤解は、深さ5を「サブエージェントを5つ同時に起動できる」という意味に捉えることです。そうではありません。深さとはツリーの縦方向の階層であり、同時に起動する子の数ではありません。各階層にはサブエージェントが1つでも100個でも存在できます。深さ5とは、委任の連鎖を5段階下まで進められるという意味です。メインチャット → 孫-1 → 孫-2 → 孫-3 → 孫-4 → 孫-5。各階層で枝分かれすることもあります。

Version 2.1.172 removed the rule that a subagent couldn't spawn another subagent.

速度を求めるなら幅が必要です。厳密な実行順序があるなら長さが必要です。深さが役立つのは、タスクの中にノイズの多いサブタスク（Webリクエスト15件、ログの調査、ファイル12個の読み込み）があり、そのノイズでメインウィンドウを埋めたくない場合だけです。

「深さ5階層」とは実際には何を意味するのか？#

ここでは、正直に伝えておきたいことがあります。Anthropicが明確な定義を示していないことを確かめるため、私は半日かけてドキュメントやコミュニティ分析を調べました。知っておくべきことは次のとおりです。

これは設定ではなく上限です。

この制限はサーバー側に組み込まれています。クライアントv2.1.172のリバースエンジニアリングでは、MAX_DEPTH定数は見つかりませんでした。つまり、チェックはローカルマシンではなくAnthropic APIのどこかで行われます。--max-depth 7を設定してツリーを深くすることはできません。--max-depth 2を設定して、より低く安全な上限を定めることもできません。制御できるのはfrontmatterのAgent(agent_type)許可リストだけですが、これは深さではなく子エージェントの種類を制限します。

Anthropicは「5」の意味を正確に定義していません。 これが2つ目の重要な点です。

Anthropicは「5」の正確な定義を明らかにしていません。 公式情報では、depth=5がルートから下に5階層なのか、ルートを含めて合計5エージェントなのかは明記されていません。

現在、サードパーティの統合機能はそれぞれ異なる解釈をしています。ruvnet/rufloプロジェクトのADR-147では「ルートの下に子の階層が5つ = 連鎖にエージェントが6つ」と仮定しています。私も実験では同じ慣例を使っています。メインチャットをレベル0、直接の子をレベル1とし、レベル5まで数えます。ただし、この慣例は公開ドキュメントには記録されていません。

フラグなしで、すでに有効になっています。 有効化する必要はありません。Claude Codeをv2.1.172に更新した後、子エージェントのtoolsにAgentを追加すれば、別のサブエージェントを起動できます。ポイントは親エージェントがそれを許可していることです（tools: Agent(...)）。

現在、あなたの委任は幅、長さ、深さのどれで行われているのか？#

直近のプロンプトを5つ確認してみてください。こんなことをどれくらいの頻度でしているでしょうか。タスクを始めるとClaudeがファイルをgrepし始め、Webリクエストを10件送り、ログを大量にコンテキストへ流し込みます。そして20分後、ウィンドウがいっぱいになっていることに気づきます。コンテキストの70パーセントを中間ダンプが消費したため、最終回答に使えるトークン予算はわずかです。

このような状況で必要なのは深さです。並列でも連鎖でもなく、深さです。メインチャットが「調査」を1つのサブエージェントに委任し、そのサブエージェントが内部から、特定のWeb検索、ファイルの読み込み、grepを行う子を起動します。子は要点を絞った判断だけを返します。孫は親に「見つけました、確認済みです」または「見つかりませんでした。理由はXです」と伝えます。親はそれを一つの要約にまとめてあなたに返します。メインチャットはすっきりしたままです。

6月9日以前、私はこれを手作業で再現していました。Claude Codeの2つ目のインスタンスを開き、「これを調査して」というプロンプトをコピーして実行し、結果を手動でメインウィンドウに移していました。この設定の詳細は、多くのAIエージェントにコーディングを委任する方法で説明しました。v2.1.172では、オーケストレーターのシステムプロンプトに直接記述できます。Claudeが自分でツリーを構築します。

ネストしたサブエージェントが実際に役立つ3つのシナリオとは？#

シナリオ1. ファクトチェックを伴う深い調査

記事や営業提案書の材料を集めるとします。まず公開情報源から主張を5～10件抽出し、各主張を検証します。元の情報源を見つけ、引用が正確か確認し、実際の数値を計算する必要があります。

v2.1.172以前には、選択肢が2つありました。1つのサブエージェントですべてを行い、Webリクエスト30件を処理しながらコンテキストに大量の情報を詰め込む方法。あるいは手作業で分割する方法です。主張を抽出するプロンプトを一つ作り、その後は主張ごとに別のサブエージェントを起動するループを回します。メインチャットには中間リストが大量に積み上がります。

以下の手順は、メインからresearch-orchestrator（レベル1）へ委任します。オーケストレーターが主張を抽出し、fact-verifier（レベル2）へ渡し、各検証役がweb-deep-search（レベル3）へ絞った検索を委任します。メインチャットが受け取るのは、情報源付きの検証済み主張の配列だけです。それ以外はすべて子のウィンドウに留まり、あなたのコンテキストには入りません。

シナリオ2. 大規模なリポジトリの分析

ファイルが200個あるプロジェクトを渡されました。アーキテクチャを理解し、主要なモジュールを見つけ、技術的負債を評価する必要があります。手作業でGlobを実行し、Readを十数回呼び出せば、10分でウィンドウがいっぱいになります。

深さを使うと、こう解決できます。メインチャットが「architect」というサブエージェントを起動します。architectは内部で3つの子を起動します。1つ目はディレクトリ構造を調べ（Globを実行して要約）、2つ目は重要な設定ファイルを5つ読み、3つ目は主要なパターンをgrepします。それぞれが簡潔な要約をarchitectに返します。architectは全体像をまとめ、半画面ほどの最終報告をメインチャットに返します。すべてのファイルに対するcatの出力が大量にコンテキストへ流れ込むことなく、プロジェクトの概要がわかります。

シナリオ3. エンドツーエンドの依存関係分析

データベースのスキーマ、API契約、共有設定ファイルを変更するとします。その影響がどこに現れるかを理解する必要があります。依存先が多く、それぞれをソースで確認しなければならないため、このタスクはコンテキストを最も速く消費します。

深さを使う場合、メインチャットが「impact-analyzer」（レベル1）を起動します。impact-analyzerは影響を受けるファイルごとにdependency-tracerを一つ起動します（レベル2）。各tracerは内部でconsumer-finder（レベル3）を起動し、コードベースをgrepしてその依存関係を使う箇所を探します。そしてそれぞれが、「この3か所に問題が起きます」という要点だけを返します。メインチャットはgrepの結果を知らずに、「影響を受けるファイル → 影響」の表をまとめます。

10分でネストしたサブエージェントを設定する方法#

ステップ1. v2.1.172以降を使っていることを確認します。

claude --version

それより古い場合は更新してください。このリリースの主な機能は、変更履歴の次の一行です。「サブエージェントが最大5階層の深さまで、自分のサブエージェントを起動できるようになりました」（全文）。

ステップ2. 子を起動できる親エージェントを作成します。

ファイル .claude/agents/research-orchestrator.md:

---
name: research-orchestrator
description: 深いファクトチェックを伴う調査を委任する
tools: Agent(fact-verifier), Read, WebFetch
model: opus
---

あなたは調査オーケストレーターです。テーマを受け取ったら:
1. 渡された資料を読むか、渡された公開URLを取得します。
   具体的な主張を最大5つ、自分で抽出します。各主張の文章、
   元URLかファイル、根拠の正確な箇所を記録します。
   資料が渡されていなければ、委任前に提出を求めます。
2. 各主張についてfact-verifierを呼び出します。fact-verifierは
   Web検索と照合のために、自分の子サブエージェントを起動します。
3. fact-verifierからは最終的な判定だけを受け取ります。
   中間ダンプを自分のコンテキストに読み込まないでください。

最終レポートは { claim, sources[], confidence } の配列だけにします。

toolsが許可する子の種類はfact-verifierだけです。主張抽出はオーケストレーター自身が行い、未定義のclaim-extractorは不要です。型の許可は種類を絞るだけで、起動回数を制限しません。この手順は抽出を最大5主張に保ってください。

ステップ3. 孫を自分で起動できる子エージェントを作成します。

ファイル .claude/agents/fact-verifier.md:

---
name: fact-verifier
description: 子のWeb検索で主張を検証する
tools: Agent(web-deep-search), Read
model: sonnet
---

あなたはファクトチェッカーです。主張を受け取ったら:
1. 2-3個の検索クエリを作成します。
2. 各クエリでweb-deep-searchを起動します。web-deep-searchは自ら
   WebSearchとWebFetchを実行し、検証済みのスニペットを返します。
3. 次の形式のverdict一つにまとめます: { claim, sources[], confidence }。

重要な部分がわかりますか？ここでもtoolsはAgent(web-deep-search)を指定しています。つまり、ツリーのレベル2にいるfact-verifierは、自分で別のサブエージェント（レベル3）を起動できます。以前はこの行に効果がありませんでした。ドキュメントには今も次の記述が残っています。

v2.1.172では、その記述は古くなっています。構文は同じですが、ツリーのどの深さでも機能するようになりました。

ステップ4. 孫を作成します。

ファイル .claude/agents/web-deep-search.md:

---
name: web-deep-search
description: Web検索を行い、スニペットを返す
tools: WebSearch, WebFetch
model: haiku
---

検索クエリを受け取りました。WebSearchを実行し、関連性の高いURLを上位3件選び、
WebFetchで主張を裏付ける正確な引用を取得します。
{ url, snippet, supports_claim: yes|no } の配列を返してください。

孫のtoolsにAgentがないため、ツリーをさらに下へ伸ばすことはありません。

ステップ5. オーケストレーターを実行します。

claude --agent research-orchestrator

次に原文か公開URLを渡し、「この資料から具体的な主張を最大5つ抽出・検証し、主張、出典、確信度を返して」と伝えます。--agent research-orchestratorなら、そのセッション自体が調整役で、その下に検証と検索の2階層が増えます。通常のメインから調整役へ委任する場合は、そのメインの下に3階層です。

トークンを浪費し、可観測性を損なう5つのアンチパターンとは？#

アンチパターン1. タスクが一つのウィンドウに収まる。

一つのサブエージェントで処理できるなら、階層を増やさないでください。

アンチパターン2. 隔離ではなく速度を求めている。

速度が必要なら、深さではなく並列化が必要です。連鎖を組み立てる代わりに、同じ階層で5つのサブエージェントを横並びに起動してください。深さは、ノイズの多い準備作業を子のウィンドウへ移すためのもので、処理を速くするためのものではありません。

アンチパターン3. 作業に深さが必要ない。

「このファイルを見つけて見せて」は2段階の依頼であり、3階層の構造は必要ありません。タスクにノイズの多いサブタスクが含まれるときに、ネストが役立ちます。ノイズがなければ、サブエージェントを増やさないでください。

アンチパターン4. 最初の階層のプロンプトが曖昧。

これは最も危険なシナリオです。レベル1のオーケストレーターに曖昧なプロンプトを渡すと、その曖昧さが増幅されます。レベル1の曖昧なプロンプト一つが、レベル2では4つ、レベル3では16個の曖昧なプロンプトになります。孫たちが作業を始めるころには、何を探しているのかさえわかりません。

アンチパターン5. コストが幾何級数的に増える。

主要な経済的論点は、ネストによってトークン使用量が増え、その増加が深さに応じて累積することです。

ネストによってトークン使用量が増え、その増加は深さに応じて累積します。

概算してみましょう。各階層で3つに分岐する深さ3の連鎖では、サブエージェントが27個になります。単純な依頼より、少なくとも27倍のトークンを使います。ClaudeのProプランでは、この計算だと1日の上限を数時間で使い切ります。Maxプランの場合は、1週間分の利用枠を1日で使い切ることになります。

追加のアンチパターン（私の経験）：『無意味な作業をする50のエージェント』。

ほかの人のプロジェクトを見ていると、よくこういう話があります。「50個のエージェントを動かしています」。何をしているのか尋ねると、その50個は無意味な作業をしています。不要な出力の山、膨大な生の要約、重複した内容、ログの壁を生成します。それぞれが「だいたい役に立つ」何かをしていて、結果としてコンテキストが埋まり、トークン料金は小さな会社並みになります。深さ5ではこの問題は解決しません。悪化させます。レベル1で誰が何をしているのかすでに不明確なら、深さ5では混乱が5階層にわたります。

サブエージェントを起動する前に、30秒で次の4つの質問に答えられるか確認してください。

• 具体的に何をするのか（一文で）？
• どのファイルを扱うのか？
• 親に何を返すのか？
• 誰が確認するのか？

30秒以内に答えられないなら、そのサブエージェントは必要ありません。このルールについては、並列サブエージェントに関するガイドで別途説明しました。

コンテキストエンジニアリングなしのネストが、なぜ5階層の幻覚につながるのか？#

ここでよく聞かれます。「Claude Codeを更新してtoolsにAgentを追加したら、ツリーはできるようになりました。でも最終回答はまだ的外れです。なぜですか？」

答えは簡単です。Claude Codeのサブエージェントはすべてゼロから始まります。公式ドキュメントによると、次のとおりです。

レベル1なら、オーケストレーターが短いタスク説明を子に渡すので、対処できます。しかしレベル3では、孫は親から委任メッセージを受け取り、その親も委任メッセージしか受け取っていません。各階層で伝えられる情報は少しずつです。レベル5になると、ウィンドウには「主張Xを確認」という文言しかないサブエージェントができます。どのプロジェクトで作業しているのか、何を解決しようとしているのか、何に注目すべきなのかもわかりません。

CLAUDE.mdがない場合、レベル5の孫は、生まれて初めて職場に来たのに説明を何も受けていない社員のようなものです。タスクを与えられたので何かはします。しかし、プロジェクトが必要とする作業にはならないでしょう。

だからこそ、適切な設定が不可欠です。 適切に設定されたCLAUDE.md、business/、スキルのパイプラインなしに深さ5を使うのはカジノのようなものです。それらがあればツールになります。

ネスト以外に、v2.1.172で変わったことは？#

v2.1.172の変更履歴全文を開くと、リリース全体がサブエージェントについてのものだとわかります。

修正1. ネストしたサブエージェントが停止された後、バックグラウンドのサブエージェントがエージェントパネルでアクティブなまま「固まる」ことがなくなりました。このバグはネストでしか起きません。

修正2. availableModelsの制限がサブエージェントにも適用されるようになりました。以前は、チームが使えるモデルを制限しても（たとえば節約のためにopusを禁止しても）、サブエージェントは独自の設定で上書きしてルールを回避できました。v2.1.172では、どの場所でもルールが適用されます。

修正3. プロンプト履歴の上矢印では、メインエージェントではなく、サブエージェントの現在のタブにあるプロンプトが表示されるようになりました。可観測性の改善です。

修正4. アイドル時のCPU使用量が減りました。アイドル中に/goalインジケーターが端末を毎秒5回再描画することがなくなり、並列サブエージェントの作業中もUIの再描画頻度が下がりました。

4つすべての修正がサブエージェントに関係しています。つまりAnthropicは、変更履歴の一行だけではなく、ネストのインフラスタック全体をリリースしたということです。ネストは公開前から、Anthropic社内でしばらく使われていました。

チェックリスト：ネストが役立つとき、逆効果になるとき#

次の場合はネストを使います。

• タスクに、大量のWebリクエスト、grep、またはファイル読み込みを含むサブタスクがある。
• そのサブタスクを失っても問題ない（孫が「見つかりませんでした」と返しても、オーケストレーターが続行できる）。
• メインウィンドウに中間結果を表示する必要がない。
• サブエージェントが参照できるCLAUDE.mdと、整理されたプロジェクトコンテキストがある。
• 各階層が返す内容（入力、出力、形式）を明確に説明できる。
• Maxプランを使っているか、×27のトークンを使う余裕がある。

次の場合はネストを使いません。

• サブエージェント一つでノイズなくタスクを解決できる。
• メインウィンドウに中間結果が必要（それなら並列化が必要です）。
• プロジェクトにCLAUDE.mdがない、または業務コンテキストが乏しい。
• レベル1のプロンプトが曖昧（その曖昧さがツリーを下るにつれて指数関数的に増えます）。
• 速度が必要。比較できる同等の結果なら、深さより並列化のほうが速い。
• Proプランで一日中作業する。数時間で利用上限を使い切ります。

さらに詳しい資料はAilootでご覧いただけます。