Claude Codeのサブエージェント上限｜暴走委任を防ぐ
「AIに任せて放置していたら、いつの間にかエージェントがエージェントを呼び続けて止まらなくなっていた」——無人でClaude Codeを回す人が、一度は不安になる場面です。
結論から言うと、サブエージェントの暴走は CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION という1つの上限設定で止められます。既定は200で、これを超えるとそのセッションでは新しいサブエージェントが生成されません。
株式会社Fyveは、常時起動のMac miniで複数の無人ジョブを並走させています。この記事では設定の仕様に加えて、私が実際にどこへ天井を張っているかまで、無人運用の目線で解説します。
サブエージェントの「暴走委任」とは何か
サブエージェントは、親のセッションから作業を切り出し、別の文脈で並行して走らせる仕組みです。調査・実装・レビューを分担させると、1本の長い会話に全部を詰め込むより速く、文脈も汚れにくくなります。基本的な使い方は次の記事にまとめています。
便利な一方で、無人運用には固有の危うさがあります。それがサブエージェントがさらにサブエージェントを呼ぶ「入れ子の委任」です。1つが3つを呼び、その3つがまた3つずつ呼ぶ——といった具合に、委任が再帰的にふくらんでいく状態を指します。
人が横に座っていれば「さすがに増えすぎだ」と気づいて止められます。しかし深夜のバッチや常時起動機のように、誰も画面を見ていない環境では、この増殖を止める人がいません。
具体的な壊れ方は3つです。
- トークン消費が跳ねる：本来1本で終わる作業が数十本に分裂し、そのぶん課金が膨らむ
- APIのレート上限に当たる：短時間に大量のリクエストが飛び、処理そのものが詰まる
- 成果物が収拾不能になる：どのサブエージェントが何をしたのか追えなくなり、結果の統合が破綻する
入れ子の委任は、特別な設定をしなくても起こります。たとえば「この作業を分割して並列で進めて」とオーケストレーター役に頼むと、その子が「自分の担当をさらに細かく分けよう」と判断し、孫のサブエージェントを呼ぶ——という連鎖は自然に発生します。設計が悪いというより、委任という仕組みそのものが再帰的だからです。だからこそ、意図とは関係なく増え続けたときに止める「外側の天井」が要ります。
CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION の仕様
この暴走を止める仕組みが CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION です。2026年7月17日公開の Claude Code v2.1.212 で追加されました。公式のリリースノートは次のように記しています。
「Added a per-session cap on subagent spawns (default 200, override with CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION) to stop runaway delegation loops」（サブエージェント生成にセッション単位の上限を追加。既定200、同変数で上書き可。暴走する委任ループを止めるため）。
仕様を整理すると次のとおりです。
項目 | 内容 |
|---|---|
対象 | 1セッションで生成するサブエージェントの累計数 |
既定値 | 200 |
変更 | 正の整数で上書き可（上限なし） |
無効化 | できない（0やオフには設定できない） |
リセット |
|
追加バージョン | v2.1.212（2026年7月17日） |
誤解しやすい点：「同時実行数」ではなく「累計生成数」
ここは間違えやすいので強調します。この上限は、並列で"同時に"走らせられる数の上限ではありません。1セッションで累計何回サブエージェントを生成したか、の上限です。
ですから、1つずつ順番に呼んでいたとしても、累計が200に達すればそれ以上は生成できません。逆に、同時並列数そのものを絞りたい場合は別の設計課題であり、この変数では制御しません。混同しないようにしてください。
そして /clear で会話をリセットすると、このカウンタも戻ります。長時間ジョブでは、区切りのよいところで意図的に /clear を入れると、累計が無用に積み上がるのを避けられます。
上限に達したときの挙動と気づき方
累計が上限に達すると、それ以降のサブエージェント生成の要求は通らなくなります。処理が静かに止まったように見えるため、無人運用では「なぜ進まないのか」に気づきにくいのが難点です。
対策はシンプルで、上限に張り付いたことをログに残しておくことです。ジョブの実行ログにサブエージェントの起動回数を出しておけば、上限に達したのか、それとも別の原因で止まったのかを後から切り分けられます。上限は「事故を止める」ための仕組みで、「事故に気づく」のはログの役割——このふたつを分けて設計すると運用が安定します。
読者特典・無料ダウンロードClaude Codeを「素のまま」使うな無料でダウンロード →Web検索・予算の上限との違い
v2.1.212では、同じ「暴走を止める」系として CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION（Web検索の回数上限・既定200）も同時に追加されました。ここに予算の上限を加えると、無人運用の非常ブレーキは3つそろいます。
大事なのは、3つは止める「軸」が違うことです。
- Web検索の上限＝回数の軸。外向きの検索呼び出しがループするのを止める
- 予算の上限＝金額の軸。トークン課金が想定を超えて膨らむのを止める
- サブエージェントの上限＝委任数の軸。内部で委任が入れ子に分裂するのを止める
同じ「200」という数字でも役割は別物です。3方向それぞれに天井を張っておくと、どこか1つが暴走しても、被害がその軸で頭打ちになります。
回数と金額の天井については、それぞれ次の記事で詳しく扱っています。
実運用でどこに天井を張るか
私の常時起動機では、記事執筆・発信・情報収集といった複数の無人ジョブが1日に何度も走ります。各ジョブは数本から十数本のサブエージェントを使う設計です。
この規模だと、正常な1ジョブが累計200に達することはまずありません。つまり既定の200は、日常運用で当たる数字ではなく、「明らかに何かがおかしい」ときに効く非常ブレーキとして置いておく値です。
無人で回すジョブほど、「気づくのが遅れる」というコストが乗ります。日中に手元で動かしていれば数分で気づく異常も、夜間バッチでは翌朝まで走り続けかねません。金額や時間ではなく「生成数」という早い段階の指標で止められるこの上限は、その意味で無人運用と相性がよい設定です。
ただし、ジョブがサブエージェントを再帰的に増やす設計になっていると、たった1つのバグで一気に200へ張り付くことがあります。そこで私は、次の考え方で天井を落としています。
- 正常時のピーク生成数を実測する：普段そのジョブが何本のサブエージェントを使うかを、まず数える
- その2〜3倍を上限にする：正常な変動は吸収しつつ、暴走だけを早い段階で止められる高さに設定する（普段のピークが12本なら、上限は30前後に置くイメージです）
- ジョブの区切りで
/clearする：長時間ジョブでもカウンタが積み上がらないようにする
既定の200のまま放置すると、暴走に気づくのが「200本生成し切ったあと」になります。正常値の2〜3倍まで下げておけば、被害が小さいうちに頭打ちにできます。これは無人運用ならではの守り方です。
設定方法
環境変数として渡すだけです。settings.json の env に書いておくか、シェルの環境変数として設定します。
// settings.json
{
"env": {
"CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION": "40"
}
}無人（claude -p）で回すジョブの場合は、起動スクリプト側で export CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION=40 のように書いておくと、ジョブごとに確実に適用できます。値はあくまで例で、実際は自分のジョブの正常値を測ってから決めてください。
上限を下げるべきジョブの見分け方
すべてのジョブで天井を下げる必要はありません。判断の目安は「そのジョブがサブエージェントの数を動的に増やすかどうか」です。
- 下げたほうがよい：作業量に応じて本数が変わる設計（対象ファイルの数だけ分割する、見つかった項目ごとに検証役を立てる、など）。入力次第で本数が読めず、暴走の余地が大きい
- 既定のままでよい：使うサブエージェントが固定で、コード上で本数が決まっている設計。想定を超えて増えること自体が起きにくい
動的に増える設計ほど、正常値と暴走値の差が「バグ1つ」で生まれます。そういうジョブから優先して天井を落とすと、かけた手間に対して事故防止の効果が大きくなります。
まとめ
サブエージェントの暴走委任は、CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION（既定200）で止められます。これは同時実行数ではなく、1セッションの累計生成数の天井で、/clear でリセットされます。
そして、回数（Web検索）・金額（予算）・委任数（サブエージェント）の3つの天井を役割で分けて張ると、無人運用の事故は構造的に減ります。私たちは正常値の2〜3倍を上限に、非常ブレーキとして常時設定しています。AIに任せる範囲を広げるほど、この「上限をどこに置くか」の設計が効いてきます。
Claude Codeを「素のまま」使うな
設定で差がつく——CLAUDE.md・権限・スキルの実物を公開（全24ページ）
素のClaude Codeは"優秀な新入社員"。仕事を教えるほど、自分専用になります。覚えさせる4点セット——会社の説明書（CLAUDE.md）・権限の柵・手順書（スキル）・フォルダの地図——を、1人会社の実運用からコピペで使える型つきで公開します。
- そのまま書き換えて使えるCLAUDE.mdの型
- お金と送信をAIに触らせない「3段階の柵」
- 1回教えたら何度でも動く、手順書のコピペ雛形
- AIが迷子にならないフォルダ構造の3原則
毎週金曜の無料ニュースレター「ひとりAI経営」の購読特典です。メール登録後すぐ、ダウンロードページのご案内が届きます。あわせて、AI活用に関するお知らせやお役に立てそうなご案内をお送りすることがあります。解除はいつでも1クリック。
御社の業務に合わせたClaude Code導入支援
「AIツールを導入したが、現場で使われない」を終わらせる。
業務課題のヒアリングから設計、ハンズオン実践、運用定着まで一貫して支援します。