メインコンテンツまでスキップ

サブエージェント・フリート制限:同時実行上限とネスト深度

上級

2026年7月21日、Claude Codeは v2.1.217 をリリースし、サブエージェント・フリートに初の厳格な上限を設けました。1セッションあたり同時20サブエージェント、そしてネスト生成は完全に無効化。3日後の v2.1.219(7月24日)で、デフォルト深度3 でネストが復活しました。きっかけは公開かつ具体的で、6月13日の事件——単一のリサーチタスクが48以上の同時バックグラウンドエージェントを生成し、冗長な作業に約150万トークンを消費した後、ユーザーが停止できないという事案でした(anthropics/claude-code#68110)。

1ターンで少数を超えるエージェントを編成する場合、これらの上限は今や単一メッセージで可能なこと——そして .mcp.json、.env、オーケストレーション・プロンプトの書き方——を形作ります。

What you'll learn
  • フリートを支配する4つの環境変数:同時実行数、ネスト深度、セッション累計、サブエージェント・モデル
  • 上限に達したときClaudeが実際に見るエラー、そしてなぜランタイムが再試行しないよう指示するのか
  • なぜネストが72時間停止されたのか、復活したデフォルト(深度3)がファンアウトにとって実際に何を意味するか
  • ultracodeが同時実行上限を免除するのはいつか、ワークフローのハード上限がすべてを上書きするのはいつか
  • どんな規模でも上限内に留まる「親がオーケストレーションする」パターン

上限を形作った事件​

Issue #68110(2026年6月13日提出)は率直な原点物語です。ユーザーが単一のリサーチタスクを general-purpose サブエージェントに委任しました。そのサブエージェントは——general-purpose サブエージェントは Agent ツールを継承するため——自身の子を生成しました。その子がさらに生成。数ターン以内に48以上のバックグラウンド・エージェントが実行され、4つの独立したエージェントが同じサードパーティAPI(Wise)を独自に調査しており、ユーザーは再生成より速く停止できませんでした。介入前の合計支出:約150万トークン。

対応は5週間後、2つの出荷イベントで到着しました:

日付バージョン変更
2026-07-21v2.1.217同時実行上限 = 20;ネスト生成無効化(深度 = 1)
2026-07-24v2.1.219ネスト復活、デフォルト深度 = 3

ネストがオフの3日間は興味深い部分です——Anthropicは明らかに「ファンアウトなし」と「オーケストレーションなし」を天秤にかけ、中間の道を選びました。

4つの環境変数​

すべてのつまみは CLAUDE_CODE_ 環境変数です——シェル、.env、あるいはプロジェクトごとの settings.json で設定します。

環境変数デフォルト役割
CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS201セッション内で同じ瞬間に実行されるサブエージェントの厳格な上限。達すると生成は "Concurrent subagent limit reached" で失敗します。
CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH3サブエージェントが自身の子を生成できる深さ。1 = ネスト完全無効(親のみがオーケストレーション)。
CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION200セッション全体の累計上限——同時実行が問題なくてもこれを超える生成は失敗します。
CLAUDE_CODE_SUBAGENT_MODEL(継承)すべてのサブエージェントを特定モデルに強制。バルク工程を Haiku/Sonnet に振り、Opus 予算を親に残します。

もう2つの数字はランタイム内部にあり、環境変数ではありません:

  • Dynamic Workflows と ultracode のためのワークフロー・ハード上限:ワークフロー実行あたり同時16および合計1,000エージェント。これらはセッション環境に関わらず、ワークフローが起動するものすべてを制限します。
  • ultracode がアクティブなセッションは CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS から免除されます。理由:ultracode のワークフロー層がすでに独自の 16/1,000 のペアを強制しているため、セッション上限が二重予約になります。

実際に見るエラー​

メインエージェントが21番目の同時サブエージェント(またはデフォルト深度で4番目のネスト)を生成しようとすると、ツール呼び出しは以下を返します:

ツール結果 — 再試行しないこと

Concurrent subagent limit reached

ランタイムはモデルに上限に対してループしないよう指示します——より少ないエージェントで進めるか、直列化すべきです。これが重要な理由は2つ:

  1. 再試行こそが #68110 を破滅的にしたまさにその振る舞いです。バックオフは設計上のものです。
  2. 同じエラーがフックやログで数回以上連続して見える場合、それは制限の問題ではなくプロンプトの問題です——親がファンアウト好きで、バッチ処理を指示する必要があります。

フリートの設定方法​

Guided walkthrough1 of 5
  1. デフォルトの20から始めます。実際に独立した作業がある場合のみ上げます——例えば60パッケージにまたがるコードベース全体のスイープ。`CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS=40` をプロジェクトごとに設定し、グローバルには設定しないこと。

上限内で生き残る「親オーケストレーション」パターン​

新しいデフォルトの下で最も安全なフリート・トポロジーは、親からの幅優先です——メインセッションがワーカーを生成し、ワーカーはワーカーを生成しません。これは深度3が利用可能でも深度1のセマンティクスを使い、同時実行数の計算を自明にします:任意の瞬間にワーカーは N 以下であり、未知サイズのツリーにはなりません。

60モジュールのコードベース・スイープの具体的な形:

バッチ・オーケストレーション・スイープ — メインセッション・プロンプト

Sweep the codebase for uses of the deprecated `legacyClient()` helper.

Batch the 60 packages into 3 waves of 20. For each wave:
1. Spawn 20 read-only `Explore` subagents in parallel, one per package.
2. Wait for all 20 to return before spawning the next wave.
3. Do NOT let a subagent spawn its own children — pass every package
   in the delegation prompt directly.

Aggregate into a single `REPORT.md` after wave 3. Report the total
count and any packages that failed with the exact error string.

これが成立する理由:

  • 20の同時ワーカーは各ウェーブでデフォルト上限にちょうど1回到達します——失敗する生成はゼロ。
  • ネストは未使用のため CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH は関係ありません——設定は v2.1.217(ネスト・オフ)と v2.1.219(ネスト・オン)の両方で動作します。
  • 累計生成数:60、セッションごとのデフォルト200を大きく下回ります。

パターンを破るとき(ネストを使うとき)​

深度3が存在するのには理由があります——本当に階層的な問題もあります。ネストが役立つ2つの形:

  • **深いリサーチツリー。**それ自体が5つのソースを比較する必要があるトップレベルの research サブエージェント——それぞれが自明ではない——は、5つの兄弟 researcher の子を生成できます。合計深度 = 2。
  • **シャード単位の finalize を伴う Map/Reduce。**親が N 個のシャード所有者を生成;各シャード所有者は自分のシャードが終わったら1つの finalizer を生成。合計深度 = 2ですが、親が各 finalize を追跡するより構造的にきれいです。

どちらかの形があなたの作業を表しているなら、デフォルトのままにしてください。トポロジーがフラットなら、明示的に CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1 を設定してください——ドキュメントと安全網です。

/agents とバックグラウンド・サブエージェントとの相互作用​

初めて上限に達したときに人がつまずく2つの微妙な点:

  • **バックグラウンド・サブエージェントもカウントされる。**第27週(2026年6月29日–7月3日)以来、サブエージェントはデフォルトでバックグラウンド実行されます。バックグラウンド・エージェントは、親がそれを待ってブロックされていなくても、実行中は同時実行上限にカウントされます。
  • **フロントマターの background: true は上限を免除しない。**サブエージェントをフロントマターでバックグラウンドに固定しても、親が再開するタイミングが変わるだけで——ランタイムがそれをカウントするかどうかは変わりません。

上限エラーが出ていてメインセッションがアイドルに感じるなら、/agents を実行(またはステータスラインを確認—— Statusline 参照)して、セッション初期から生き残っているものを探してください。

Sonnet 5、Opus 5、上限下のコスト​

CLAUDE_CODE_SUBAGENT_MODEL のデフォルト動作は継承——サブエージェントは親のモデルで走ります。20の同時ワーカーを持つ Opus 5 セッションでは、これがすぐに積み上がります。上限が着地した後の推奨される形:

  • 親は Opus 5 で、オーケストレーションと最終合成のため。
  • CLAUDE_CODE_SUBAGENT_MODEL=claude-sonnet-5 で、スコープの明確なIO重視のタスクを行うワーカー。
  • 機械的なもの(grep 形の作業、フォーマット・チェック)には Haiku 4.5。

階層のトレードオフについては モデルの選び方、ツール重視のサブエージェントがモデルに関わらず請求額を膨らませる理由については MCP トークンコスト を参照。

理解度チェック

0/3
  1. メインセッションから同時に25のサブエージェントを生成します。デフォルト設定で何が起きますか?
  2. `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1` を設定するとどんなトポロジーになりますか?
  3. 同時に200のエージェントを必要とするワークフローを実行します。どのルートが動作しますか?
フリート制限 — 各カードをめくる
Enter キーまたはスペースキーでカードを裏返します。左右の矢印キーでカードを移動できます。用語を表示しました。
1 / 6
Key takeaways
  • デフォルトの同時実行上限は 20;ネスト深度のデフォルトは 3(2026年7月末の72時間は 1 だった)。
  • 4つのつまみはすべて `CLAUDE_CODE_*` 環境変数 —— 同時実行、生成深度、セッションごと合計、サブエージェント・モデル。
  • 'Concurrent subagent limit reached' は失敗して停止するシグナルであり、再試行シグナルではない。繰り返し発生するなら親プロンプトがファンアウト好き。
  • 親がウェーブでオーケストレーションするのが新しい上限下で最も安全なトポロジーで、v2.1.217 と v2.1.219 で同一に動作する。
  • 約40同時以上が必要なら1セッションを超えている —— 動的ワークフローとその 16/1,000 ワークフロー上限に移行する。

次へ​

情報源と参考文献​