Claude Codeワークフローの同時実行数をMAX_CONCURRENT_AGENTSで調整する
ダイナミックワークフローが同時に走らせるエージェント数は既定16・上限256です。CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTSでの調整方法とCPU数連動の挙動、他の上限との違いをまとめます。
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が使われます。バージョンを上げずに調整だけ先に試すことはできない仕様なので、期待どおりに反映されないときはまずバージョンを確認します。
既定値16はCPU数で下がることがある
既定の16は固定値ではありません。Claude Codeが利用できるCPUが少ない環境では、実行時の上限が16よりさらに下がります。CPU数を制限したコンテナの中でワークフローを動かす場合も同じ扱いです。
CIのジョブランナーやリソース制限付きのDockerコンテナでワークフローを回すと、ローカルの開発機より低い同時実行数になることがあります。想定より遅いと感じたら、まずCPU割り当てを疑うのが近道です。
値を変える方法とバリデーションの挙動
設定できるのは1から256の範囲で、受け付けるのは数字だけの文字列です。範囲外の値や数字以外を含む値を指定した場合、Claude Codeはエラーを出さずに既定値へ静かにフォールバックします。桁区切りや指数表記のような書き方は想定されていません。
export CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS=64
claude上の例は上限を64に引き上げる設定です。シェルのexportはそのターミナルセッションだけに効き、claudeを起動するたびに読み直されます。恒久的に固定したいときは後述のsettings.jsonを使います。
workflowSizeGuidelineのようにClaude Code側が専用の設定キーと/configの項目を用意している値とは違い、この上限には専用の設定キーがありません。永続化する手段は環境変数そのものを設定ファイルのenvブロックに書く方法だけです。
スクリプトがparallel()で一度に100件のタスクを展開しても、上限が既定の16のままなら実際に動くのは常に16件までです。残り84件はエラーにも失敗にもならず、先に走っている16件のどれかが終わって空きスロットが出るたびに1件ずつ繰り上がって実行されます。この「並べたのに待たされる」挙動自体は正常なキューイングで、故障ではありません。
上げるとどうなるか、下げるとどうなるか
同時実行数を上げると、大量のファイルを対象にした調査や移行のようなファンアウトが速く終わります。ただし実行中の各エージェントのtranscriptはClaude Codeのメモリー上に保持され続けるため、値を上げるほどメモリー使用量も増えます。数百エージェント規模のrunで上限を256近くまで上げると、マシンのメモリーを圧迫する可能性があります。
用途別の目安は次の通りです。
| 用途 | 推奨の方向性 | 理由 |
|---|---|---|
| ノートPCでの対話的な開発 | 推奨の方向性既定の16のまま、または下げる | 理由メモリーとCPUを他の作業と共有するため |
| CPU制限付きのCIランナー | 推奨の方向性明示的に低めの値を固定 | 理由環境側の実効上限がすでに低いことが多い |
| 専用マシンでの大規模な調査・移行 | 推奨の方向性上限に近い値まで上げる | 理由メモリーに余裕があれば並列度がそのまま短縮に効く |
| メモリーに制約のある共有サーバー | 推奨の方向性既定より下げる | 理由多数のtranscriptを同時保持しない設計にする |
settings.jsonでチームに固定する
シェルのexportは個人のターミナルにしか効きません。プロジェクトの全員に同じ上限を強制したいときは、.claude/settings.jsonのenvキーに書きます。
{
"env": {
"CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS": "32"
}
}シェルと設定ファイルの両方で値を指定した場合は、設定ファイル側が優先されます。管理者が配布するmanaged settingsは、プロジェクト設定やユーザー設定より優先されるため、組織全体で上限を固定したい場合はそちらに置きます。
混同しやすい別の上限と混ぜない
同時実行数を調整する設定は他にもありますが、それぞれ効く場所が違います。
| 設定 | 効く対象 | 値の性質 |
|---|---|---|
CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS | 効く対象同時に走るエージェント数の実行時上限 | 値の性質ハードキャップ(1〜256) |
workflowSizeGuideline設定 | 効く対象Claudeがワークフローを書くときに狙うエージェント総数 | 値の性質あくまで助言(smallは5未満・mediumは10未満・largeは50未満が目安) |
parallel()・pipeline()1回あたりの項目数 | 効く対象スクリプトの1呼び出しで渡せる件数 | 値の性質4,096件を超えるとランタイムがエラーで拒否 |
| 1runあたりの総エージェント数 | 効く対象1回の実行全体で起動できるエージェントの延べ数 | 値の性質上限1,000体、暴走ループの防止用 |
workflowSizeGuidelineは「Claudeがどれくらいの規模でスクリプトを書くか」を決める指針であり、実際に何体まで同時に走らせるかは決めません。largeガイドラインでスクリプトが50体近いエージェントを起動しても、そのうち実際に並行して動けるのはCLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTSの枠内だけで、残りはキューに積まれます。
この上限を256まで引き上げても、1run全体で起動できるエージェントの延べ数(最大1,000体)は変わりません。同時実行数は「一度に何体を並行させるか」というスループットの調整弁であり、「1回のrunでどこまで大きな仕事を任せられるか」という総量の上限とは別の軸です。総量を増やしたいわけではなく、既に1,000体の枠に収まっているタスクをより短い時間で終えたいときに、この変数を上げる意味があります。
PREFIX_STAGGER_MSとの違い
ファンアウトで同時に何体も起動すると、モデル・エフォート・ツール構成などが一致するエージェント同士はプロンプトキャッシュを共有できます。このとき最初のエージェント以外を数秒だけ待たせてキャッシュを効かせる仕組みがCLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS(既定5000ミリ秒)です。MAX_CONCURRENT_AGENTSが「同時に走れる人数の枠」を決めるのに対し、こちらは「その枠の中で先発を少し待つかどうか」を決める設定で、役割が異なります。この待ち合わせの詳しい仕組みと、1時間キャッシュへ延ばす設定はClaude Codeワークフローのプロンプトキャッシュの効き方で扱っています。
上限を上げる価値があるのはどんな場面か
ワークフローが向くのは、1回の会話では抱えきれない規模のタスクです。コードベース全体を対象にした同じ不具合の一斉調査、数百ファイル規模の移行、複数のソースを突き合わせて裏取りする調査などが典型例です。こうしたタスクはparallel()で数十〜数百件を一気に展開するため、既定の16では大半が順番待ちになり、実行時間の大部分が待ち時間で埋まります。専用マシンでメモリーに余裕があるなら、上限を上げるほどこの待ち時間がそのまま短縮されます。
逆に、対象が数件程度の小さな調査やコードレビューでは、既定の16でスロット不足になる場面はほとんどありません。上げても速くならないうえメモリー使用量だけが増えるので、タスクの規模に見合わない値を常設しないのが無難です。
上げる値もマシンのCPU・メモリーに対して無制限に効くわけではありません。実行時の実効上限はCPU数が少なければ既定の16よりさらに下がる仕様なので、設定した数値どおりに並行実行されるかどうかは、最終的に動かす環境のリソースに左右されます。値を256まで上げても、CPUとメモリーがそれに見合っていなければ、キューでの待ち時間が減る代わりに個々のエージェントの処理自体が遅くなるだけということもあります。
同時実行数を上げるとコスト・利用上限への影響も増える
ワークフローは1回の実行で多数のエージェントを起動するため、同じ作業を会話の中でこなすより明確に多くのトークンを使うことがあります。Claude Codeはスケジュールされたエージェントが25体を超える、または投影トークン総量が150万を超えると、タスクパネルの進捗行に「Large workflow」の警告を表示します。この警告はあくまで助言で、runを止めたり制限したりはしません。workflowSizeGuidelineで自分でサイズ指針を選んでいる場合はその指針のエージェント数がこの25体という閾値の代わりに使われ、ultracodeを有効にしたセッションではそもそも警告が出ません(ultracodeを有効にすること自体が大きなrunへの同意とみなされるためです)。
同時実行数を上げること自体がAPIへのリクエスト頻度を上げるため、利用上限に達する速度も上がります。runがclaude.aiの利用上限に達すると、対話セッションが非対話モード(-p)やAgent SDK、バックグラウンドセッションでない限り、影響を受けたエージェントは失敗せず上限のリセットを待ってから続きを再開します。大きなタスクにかける前に、対象を1ディレクトリだけに絞るなど小さな範囲でまず試し、/workflowsビューでエージェントごとのトークン使用量を確認してから本番の規模に広げるのが実務での進め方です。
よくあるつまずき
- 値を上げたのに速くならない: CPU数が少ない環境では実効上限がそもそも16より低く、設定した値まで届いていない可能性があります。コンテナのCPU割り当てを先に確認します
- 文字列を渡したのに反映されない: 受け付けるのは数字だけです。範囲外の数値や数字以外の文字列はエラーにならず既定値の16へ静かにフォールバックするため、意図した値が効いているかは進捗を示す
/workflowsビューで確認するのが確実です - 古いバージョンで設定が効かない: v2.1.269より前のClaude Codeはこの変数自体を読みません。効かないときはまずバージョンを疑います
まとめ
CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTSは、ダイナミックワークフローが同時に走らせるエージェント数を1〜256の範囲で調整する環境変数で、既定は16です。実効上限はCPU数が少ない環境やコンテナ内ではさらに下がり、値を上げるほど各エージェントのtranscriptがメモリーを消費します。workflowSizeGuideline(スクリプトの規模の助言)やparallel()・pipeline()の件数上限(4,096件)、1runあたりの総エージェント数(1,000体)とは効く対象が違うので混同しないようにします。ファンアウト内のキャッシュ待ち合わせを調整したい場合は、この変数ではなくCLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MSを扱う別記事を参照します。