Claude Codeワークフローの同時実行数をMAX_CONCURRENT_AGENTSで調整する

CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTSが制御するもの

Claude Codeのダイナミックワークフローは、1回の実行(run)の中で複数のサブエージェントを同時に走らせます。CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTSは、その同時実行数の上限を指定する環境変数です。設定できる範囲は1から256で、既定値は16です。上限を超えた分のagent()呼び出しはエラーにならず、空きスロットが出るまでキューで待ちます。

この変数はClaude Code v2.1.269以降で使えます。それより前のバージョンでは、変数を設定しても調整は効きません。

既定値16はCPU数で下がることがある

既定の16は固定値ではありません。Claude Codeが使えるCPUが少ない環境では、実行時の上限が16よりさらに下がります。CPU数を制限したコンテナの中でワークフローを動かす場合も同じ扱いです。

CIのジョブランナーやリソース制限付きのDockerコンテナでは、ローカルの開発機より低い同時実行数になることがあります。想定より遅いと感じたら、CPU割り当てを先に疑うのが近道です。

値を変える方法とバリデーションの挙動

受け付けるのは、1から256の範囲の数字だけの文字列です。範囲外の値や数字以外を含む値は、エラーにならず既定値のまま動きます。桁区切りや指数表記のような書き方も同じ扱いで、無視されて既定値に戻ります。

export CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS=64
claude

上の例は上限を64に引き上げる設定です。シェルのexportはそのターミナルセッションだけに効き、claudeを起動するたびに読み直されます。恒久的に固定したいときは、次の節のsettings.jsonを使います。

workflowSizeGuidelineには専用の設定キーと/configの項目がありますが、この上限にはありません。永続化する手段は、環境変数そのものを設定ファイルのenvブロックに書く方法だけです。

スクリプトがparallel()で一度に100件のタスクを展開しても、上限が既定の16のままなら同時に動くのは16件までです。残りの84件は失敗にならず、先行する16件のどれかが終わるたびに1件ずつ繰り上がります。「並べたのに待たされる」のは正常なキューイングで、故障ではありません。

settings.jsonでチームに固定する

シェルのexportは個人のターミナルにしか効きません。プロジェクトの全員に同じ上限を適用したいときは、.claude/settings.jsonのenvキーに書きます。

{
  "env": {
    "CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS": "32"
  }
}

なお、プロジェクト設定のenvの値は、多くの場合そのフォルダを信頼(trust)したあとに適用されます。ただしモデル選択・タイムアウト・上限のように安全と分類された変数は、すべての設定ファイルから起動時に適用されます。

シェルと設定ファイルのenvの両方で同じ変数を指定した場合、ほとんどのセッションでは設定ファイル側の値が使われます。Claude Codeがenvの各項目をプロセス環境へ書き込み、シェルから引き継いだ値を置き換えるためです。例外は、Claude Desktopアプリやセルフホスト環境のランナーがセッションを起動した場合です。起動環境がすでに持っている変数については、設定ファイルのenvの値が無視されます。

設定ファイルどうしの比較に限れば、設定の優先順位に従い、管理者配布のmanaged settingsが最優先です。プロジェクト設定やユーザー設定より上なので、組織全体で上限を固定するときはそちらに置きます。

同時実行数を上げるとどうなるか

同時実行数を上げると、大量のファイルを対象にした調査や移行のようなファンアウトが速く終わります。代わりに、実行中の各エージェントのtranscriptはClaude Codeのメモリー上に残り続けるため、値を上げるほどメモリー使用量が増えます。

この上限は、ローカルのリソース使用量を抑えるための枠です。

混同しやすい別の上限

ワークフローには、同時実行数のほかにも上限が2つあります。それぞれ効く場所が違います。

workflowSizeGuidelineはこれらと性質が違い、Claudeがスクリプトを書くときに狙う規模の目安です。値はsmallが5体未満、mediumが10体未満、largeが50体未満で、unrestrictedなら目安なしでタスクに合わせて決めます。既定はmediumで、Claude Code v2.1.271以降のProプランではsmallです。変更は/configの項目か、設定ファイルのworkflowSizeGuidelineキーで行います。/configなら次のコマンドです。

/config workflowSizeGuideline=small

largeでスクリプトが50体近いエージェントを起動しても、並行して動けるのは同時実行数の枠内だけで、残りはキューに積まれます。

同時実行数を256に上げても、1run全体の1,000体は変わりません。同時実行数は「一度に何体を並行させるか」を決めるスループットの調整弁で、「1回のrunにどこまで任せられるか」という総量の上限とは別の軸です。既に1,000体の枠に収まっているタスクをより短時間で終えたいときに、この変数を上げる意味があります。

Agent toolのサブエージェントとは別の上限

「同時実行数」を絞りたいとき、もう一つ紛らわしいのがCLAUDE_CODE_MAX_CONCURRENT_SUBAGENTSです。こちらはClaudeがAgent toolで起動するサブエージェント向けで、ワークフローのエージェントは数えません。公式のサブエージェントの項でも、ワークフローのエージェントやエージェントチームのチームメイトは「それぞれ独自の上限に従う」と書かれています。

ワークフローの並列度を上げてもAgent toolの20体は増えず、その逆も成り立ちます。

PREFIX_STAGGER_MSとの違い

ファンアウトで同時に何体も起動すると、モデル・エフォート・ツール構成などが一致するエージェント同士はプロンプトキャッシュを共有できます。このとき最初のエージェント以外を数秒だけ待たせてキャッシュを効かせる仕組みがCLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS(既定5000ミリ秒)です。MAX_CONCURRENT_AGENTSが「同時に走れる人数の枠」を決めるのに対し、こちらは「その枠の中で先発を少し待つかどうか」を決める設定で、役割が異なります。この待ち合わせの仕組みと、1時間キャッシュへ延ばす設定はClaude Codeワークフローのプロンプトキャッシュの効き方で扱っています。

上限を上げる価値があるのはどんな場面か

ワークフローが向くのは、1回の会話では抱えきれない規模のタスクです。公式の例には、コードベース全体のバグ調査、500ファイル規模の移行、複数のソースを突き合わせる調査が挙がっています。こうしたタスクはparallel()で数十〜数百件を展開するため、既定の16では大半が順番待ちになり、実行時間の多くが待ち時間で埋まります。

対象が数件程度の小さな調査やレビューなら、既定の16でスロットが足りなくなる場面はまずありません。上げても、実際に同時に走る数は対象の件数のままで変わりません。

同時実行数を上げるとコストと利用上限も動く

ワークフローは1回の実行で多数のエージェントを起動するため、同じ作業を会話の中でこなすより多くのトークンを使うことがあります。スケジュールされたエージェントが25体を超えるか、投影トークン総量が150万を超えると、タスクパネルの進捗行にLarge workflowの警告が出ます。警告は助言で、runを止めも制限もしません。

警告の出方は2つの設定で変わります。workflowSizeGuidelineを自分で選ぶと、その指針のエージェント数が25体の閾値の代わりに使われます。ultracodeを有効にしたセッションでは警告自体が出ません。ultracodeを有効にすることが、大きなrunへの同意として扱われるためです。

同時実行数を上げると、短時間に使うトークンが増え、利用上限に届くまでの時間も縮みます。runがclaude.aiの利用上限に当たったときの挙動には、次の4つの条件があります。

• 対話セッションで、claude.aiのサブスクリプションでサインインしている(非対話のclaude -p、Agent SDK、バックグラウンドセッション、Remote Controlやエージェントチームのチームメイトのセッションでは一時停止しない)
• autoContinueAtUsageLimitがオンになっている
• 上限が24時間以内にリセットされる(週次の上限はそれより先になることがある)
• そのrunが待機した回数が2回未満である(3回目に当たると該当のエージェントは失敗する)

4つがそろうと、該当のエージェントは失敗せずリセットを待ち、リセット後に自動で再開します。新しいエージェントは待機中は起動しません。この一時停止はClaude Code v2.1.271以降で、それより前のバージョンでは該当のエージェントが失敗します。

大きなタスクにかける前に、対象を1ディレクトリだけに絞るなど小さな範囲で試し、/workflowsビューでエージェントごとのトークン使用量を見てから規模を広げる進め方があります。

設定が効かないときの切り分け

まとめ

同時実行数を調整する変数は、ワークフローのエージェント向けのCLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTSと、Agent toolのサブエージェント向けのCLAUDE_CODE_MAX_CONCURRENT_SUBAGENTSの2つがあり、互いに影響しません。ワークフローの上限は、速さの要望よりも、動かす環境のメモリー・CPUと利用上限の消費ペースを見て決める値です。