はじめに
Claude Code の v2.1.172（2026年6月10日リリース）で、サブエージェントが自身のサブエージェントを起動できる「ネスト型サブエージェント（nested sub-agents）」 が追加されました。公式リリースノートでは「サブエージェントは最大5階層までネストできる」と説明されています。
これまでのサブエージェントは「親エージェントが子エージェントを1段だけ呼ぶ」構造でしたが、ネスト対応により「子が孫を、孫がひ孫を」と再帰的に処理を委譲できるようになりました。一方で、階層が深くなるほどトークン消費とコストが増えるため、設計の勘所を押さえておかないと「動くが高い」エージェントになりがちです。
この記事では、ネスト型サブエージェントの仕組み・定義方法・トークン設計の考え方を、公式ドキュメントと公開情報をもとに整理します。
この記事で学べること
- ネスト型サブエージェントとは何か、どのバージョンで何が変わったのか
-
.claude/agents/でサブエージェントを定義する方法（name/description/tools/model） - 5階層の上限とトークン消費の関係、コストを抑える設計パターン
- ネストすべきケース・避けるべきケースの判断基準
対象読者
- Claude Code でサブエージェントを使った自動化を組みたいエンジニア
- 複数のサブエージェントを組み合わせた際のコストが気になっている方
- エージェント設計のベストプラクティスを知りたい方
前提知識
- Claude Code（CLI）の基本操作
- サブエージェント（subagent）の基本概念（親エージェントが特定タスクを別コンテキストに委譲する仕組み）
TL;DR
- Claude Code v2.1.172（2026-06-10）で、サブエージェントが最大5階層までネスト可能に。
- 各階層は独立したコンテキストと
modelを持つため、深い階層ほどモデルを軽くするのがコスト設計の基本。 - ネストが活きるのは「木構造」「再帰的探索」のタスク。逐次処理や横の連携が必要なタスクには不向き。
ネスト型サブエージェントとは
サブエージェントのおさらい
Claude Code のサブエージェントは、特定の役割に特化した別コンテキストの作業者です。公式ドキュメント「Create custom subagents」によれば、サブエージェントは Markdown ファイルに YAML フロントマターを書いて定義し、フロントマターでエージェントの名前・用途・使えるツール・実行モデルを宣言します。
メインのエージェントが「このタスクはレビュー担当に任せよう」と判断すると、サブエージェントが起動して独立したコンテキストウィンドウで作業し、結果の要約だけを親に返します。これにより、メインの会話コンテキストを汚さずに重い調査やレビューを並走させられます。
v2.1.172 で何が変わったか
ネスト対応前は、サブエージェントは「葉（leaf）」でした。つまり、メインエージェントが子サブエージェントを呼べても、その子がさらに孫を呼ぶことはできませんでした。
v2.1.172 では、この制限が緩和され、サブエージェントが自身のサブエージェントを起動できるようになりました。リリースノートでは次のように記載されています。
Sub-agents can now spawn their own sub-agents (up to 5 levels deep)
— Claude Code release notes (v2.1.172, Jun 10, 2026)
この「最大5階層」という上限は、無限再帰による暴走とコスト爆発を防ぐための安全装置として機能します。
公式ドキュメント「Create custom subagents」によると、この深さ5の上限が固定の天井（hard ceiling）として効くのは バックグラウンドで動くサブエージェント です。深さ5のバックグラウンドサブエージェントはサブエージェント起動用ツールを受け取らず、それ以上ネストできません。一方、フォアグラウンドのサブエージェントは原理的に深さ制限がなく、親が子の完了を待つ自己制限型で動作します。正確な条件は公式ドキュメントを確認してください。
直近のアップデートとの関係
ネスト型サブエージェントは、2026年6月のClaude Code強化の一部です。同時期に以下も追加されています。
| バージョン | 日付 | 主な追加 |
|---|---|---|
| v2.1.169 | 2026-06-08 | Safe Mode（--safe-mode）、/cd コマンド |
| v2.1.170 | 2026-06-09 | Claude Fable 5 モデルへのアクセス |
| v2.1.172 | 2026-06-10 | ネスト型サブエージェント、プラグイン検索 |
特に、後述するトークン設計と相性が良いのが /usage コマンドです。/usage はプラグインやMCPサーバー単位でトークン消費の内訳を表示するため、ネストしたエージェントのどこがコストを食っているかの当たりをつけるのに役立ちます。
サブエージェントの定義方法
基本のフロントマター
サブエージェントはプロジェクトの .claude/agents/ 配下（またはユーザーレベルの ~/.claude/agents/）に Markdown ファイルとして配置します。公式ドキュメントによると、主なフロントマターフィールドは次の4つです。
---
name: log-summariser
description: コンテナの生ログを読み、構造化された要約を返す。ログ調査が必要なときに使う。
tools: Read, Grep
model: haiku
---
あなたはログ要約の専門家です。
与えられたログファイルを読み、エラー・警告・タイムスタンプを構造化して要約してください。
ファイルの書き込みは行いません。
各フィールドの役割は以下のとおりです。
| フィールド | 役割 |
|---|---|
name |
サブエージェントの一意な名前 |
description |
委譲のトリガー。Claude はユーザーの要求とこの説明を照合して、自動でサブエージェントに委譲するか判断する |
tools |
サブエージェントが使えるツールを物理的に制限する。Read, Grep, Glob だけなら書き込みは一切できない |
model |
実行モデル（haiku / sonnet / opus）。タスクの重さに応じて使い分ける |
フロントマター直下の本文がシステムプロンプト（エージェントの振る舞いを定義する指示）になります。
descriptionは「ラベル」ではなく「ルーティングのルール」として書くのが重要です。「どんな状況・どんなフレーズのときにこのエージェントを呼ぶべきか」を具体的に書くほど、自動委譲の精度が上がります。
ネストの考え方
ネストは、あるサブエージェントが別のサブエージェントを呼べるツール権限を持つことで成立します。つまり、子エージェントの tools にサブエージェント起動の権限を含めると、その子は孫を呼べるようになります。
たとえば、ログ調査を3階層に分けたバグトリアージのワークフローは次のように構成できます。
| 階層 | エージェント | 役割 | 推奨モデル |
|---|---|---|---|
| ルート（深さ0） | triage-lead |
全体の統括・最終判断 | opus |
| 中間（深さ1） | repro-runner |
再現手順の実行 | sonnet |
| 葉（深さ2） | log-summariser |
生ログの要約 | haiku |
ルートの triage-lead が repro-runner を呼び、repro-runner が log-summariser を呼ぶ——という委譲チェーンです。各階層は独立したコンテキストで動き、結果の要約だけが上位に返ります。
サブエージェント起動を許すツール権限を無制限に与えると、モデルが意図しないチェーンを延々と作り、コストが膨らむ恐れがあります。「どの子を呼べるか」を明示的に列挙する設計（後述）が安全です。なお、ネスト用の正確なツール指定の書式は更新が早いため、必ず公式ドキュメントで最新の記法を確認してください。
トークン設計の勘所
ネスト型サブエージェントで最も注意すべきはトークン消費です。各階層は独立したコンテキストウィンドウとシステムプロンプトを持つため、階層が増えるほど「システムプロンプトの書き込み」が積み重なります。
なぜ深いほど高くなるのか
1段だけのサブエージェントなら、追加コストは「子のシステムプロンプト + 子の作業トークン」だけです。しかしネストすると、中間階層のコンテキストは最終的に親へは要約しか返らないにもかかわらず、その途中過程のトークンは消費されます。多分岐（1つの親が複数の子を、その子がさらに複数の孫を呼ぶ）になると、消費は階層的に膨らみます。
設計パターン: 深い階層ほど軽いモデルに
コストを抑える基本は、役割と階層に応じてモデルを使い分けることです。
| 深さ | 典型的な役割 | モデル戦略 |
|---|---|---|
| 0（メイン） | 統括・最終的な合成 | Opus（高度な推論） |
| 1 | 中間的な推論・調整 | Sonnet（標準的な実装） |
| 2以上 | 単純な探索・読み取り | Haiku（安価な葉作業） |
葉に近い単純作業（ログ読み・grep・要約）にOpusを使うのは典型的な無駄です。葉はHaiku、推論が必要な中間はSonnet、最終合成だけOpus——というように下に行くほど軽くするのがセオリーです。
環境変数 CLAUDE_CODE_SUBAGENT_MODEL でサブエージェントのデフォルトモデルをまとめて指定できます。たとえば全体のデフォルトをHaikuにしておき、能力が必要な階層だけ各エージェントの model フィールドで個別に格上げする、という運用がコスト管理しやすくなります。
# サブエージェントのデフォルトモデルを軽量モデルに固定
export CLAUDE_CODE_SUBAGENT_MODEL=haiku
claude
/usage で内訳を可視化する
どの階層・どのコンポーネントがトークンを消費しているかは、/usage コマンドで確認できます。複数のプラグインやMCPサーバー、ネストしたエージェントを併用しているときほど、内訳の可視化は効果を発揮します。コストが想定より高いときは、まず /usage で「どこが食っているか」を特定してからモデル戦略を見直すのが効率的です。
ネストすべきケース・避けるべきケース
ネストは万能ではありません。タスクの形に応じて使い分けます。
ネストが向くケース
- 木構造のタスク: 1つの親が、役割の異なる複数の専門レビュアー（セキュリティ・パフォーマンス・スタイル）に分岐させる
- 再帰的な探索: モノレポをディレクトリ単位でスコープを切りながら深掘りする
ネストを避けるべきケース
-
逐次処理: 「Aの次にB、その次にC」と一直線に進むタスクは、ネストせず1つのエージェントで
maxTurnsを多めに取るほうがシンプルかつ安価です - 横の連携が必要な並列作業: 並列ワーカー同士が情報を共有しながら進める必要があるなら、ネスト（縦の委譲）ではなく、並列実行に適した仕組み（agent teams など）が適しています
ネストは「縦方向の委譲」、agent teams のような並列実行は「横方向の協調」と整理すると判断しやすくなります。タスクが分岐・再帰なら縦、協調・共有なら横です。
まとめ
- Claude Code v2.1.172（2026-06-10）で、サブエージェントが最大5階層までネストできるようになりました。
- サブエージェントは
.claude/agents/にname/description/tools/modelをフロントマターで定義します。descriptionはルーティングルールとして、toolsは権限の物理的制限として書くのが要点です。 - 各階層は独立コンテキストを持つため、深い階層ほど軽いモデルにするのがトークン設計の基本。
CLAUDE_CODE_SUBAGENT_MODELでデフォルトを軽くし、必要な階層だけ格上げします。 - ネストが活きるのは木構造・再帰探索のタスク。逐次処理や横の協調には不向きで、それぞれ単一エージェントやAgent Teamsが適します。
ネスト型サブエージェントは強力ですが、設計を誤ると「動くが高い」エージェントになります。まずは小さな2〜3階層から始め、/usage でコストを観測しながら階層とモデルを調整していくのがおすすめです。
参考リンク
- Create custom subagents — Claude Code Docs — サブエージェントの定義方法・フロントマター仕様
- Claude Code release notes — Releasebot — v2.1.172 のネスト型サブエージェント追加
- Claude Code Subagents: A 2026 Practical Guide — Tembo.io — サブエージェント設計の実践ガイド