/workflowsで数十〜数百エージェントの実行を管理する
Claude Codeの/workflowsビューでダイナミックワークフローを止める・再開する・保存する方法。キーバインド、サイズ指針、再開時に再実行される範囲、使用量上限での自動待機まで、現行の仕様でまとめます。
/workflowsを開いてpキーを押すと、走っている実行を一時停止できます。同じ画面で、動いている1体のエージェントだけをxで止めることもできます。この2つは見た目が似ていますが、再開したときの扱いが違います。後者は「失敗」として数えられ、止めたエージェントより後に起動した分まで再実行されます。
ダイナミックワークフロー自体の仕組みと起動方法は別記事で扱いました。本稿は、実行が始まったあとの操作面である/workflowsビューに絞ります。症状別に、止める・再開する・コストを抑える・保存して配る、の順で掘り下げます。
数か月で何が積み上がったか
ダイナミックワークフローは、v2.1.154(2026年5月28日)の「tens to hundreds of agents」を謳う導入から始まりました。その後のバージョンで、/workflowsまわりの制御が段階的に増えています。
/workflowsまわりの制御の追加
- v2.1.154ダイナミックワークフローと/workflowsが登場
導入時の説明は「何十から何百ものエージェントにバックグラウンドで作業を振り分ける」で、
/workflowsで実行を見られるとしていました。 - v2.1.178モノレポのネストした保存先に対応
保存先が、作業ディレクトリに最も近い既存の
.claude/workflows/になりました。 - v2.1.202サイズ指針を/configに追加
small / medium / largeから選べるようになりました。助言であって上限ではありません。
- v2.1.216保存時のシンボリックリンク検査
それ以前は、リンクを辿って選んだ場所の外へ書き込む余地がありました。
- v2.1.219既定がmediumに、設定キーも追加
それまでの既定は
unrestricted(指針なし)でした。workflowSizeGuidelineキーもこの版からです。 - v2.1.271medium が10体未満に、使用量上限で自動待機
Proプランでは既定がsmallになりました。上限に当たった実行は失敗せず、リセットまで待ちます。
/workflowsの画面で何ができるか
/workflowsは実行中と完了済みのワークフローを一覧し、選んだ1件の進捗ビューを開くコマンドです。フェーズごとのエージェント数・トークン合計・経過時間が出ます。エージェントを選ぶと、プロンプト、直近のツール呼び出し、結果まで読めます。
/workflows一覧でカーソルを実行に合わせてxを押すと、進捗ビューを開かずに実行全体を止められます。進捗ビューのフッターにはキー操作が並びます。
| キー | 動作 |
|---|---|
↑ / ↓ | 動作フェーズ・エージェントの選択 |
Enter / → | 動作フェーズ、エージェント詳細の順に掘り下げる。詳細では展開・折りたたみ |
Esc / ← | 動作1階層戻る |
j / k | 動作長いエージェント詳細のスクロール |
f | 動作フェーズ内のエージェントを状態でフィルタ(再押下で切替) |
p | 動作実行の一時停止・再開 |
x | 動作選択中のエージェントを停止。実行全体にフォーカスがあれば全体を停止 |
r | 動作選択中の実行中エージェントを再起動 |
s | 動作実行のスクリプトをコマンドとして保存 |
v2.1.203〜v2.1.205だけは←がフェーズ・エージェントから戻らないため、その範囲ではEscを使います。v2.1.281の更新で、一覧はPgUp / PgDn・Home / End・j / k・マウスでも動くようになりました。
起動前の承認は権限モードで変わる
承認ダイアログの有無は、セッションの権限モードで決まります。
| 権限モード | 承認を求められるタイミング |
|---|---|
| Auto | 承認を求められるタイミング初回のみ。どれかのYesでユーザー設定に同意が記録され、以降は聞かれない |
| Manual・acceptEdits | 承認を求められるタイミング毎回。「今後このワークフローでは聞かない」を選ぶまで続く |
| bypassPermissions | 承認を求められるタイミング求められない。即座に開始 |
claude -p・Agent SDK | 承認を求められるタイミング求められない(下記の許可ルールで起動可否が決まる) |
「今後は聞かない」の選択肢が出るのは、組み込み・保存済み・プラグインのワークフローを名前で呼んだときです。そのタスクのためにClaudeが書いたスクリプトには出ません。ダイアログではCtrl+Gでスクリプトをエディタに開け、Tabで依頼文を調整できます。
claude -pやAgent SDKでは、Workflowツールの呼び出しも通常の権限評価を通ります。Workflowを許可ルールに入れると全ワークフローを、Workflow(<name>)なら保存済みの1本だけを承認できます。autoモードの分類器、bypass、PreToolUseフック、--permission-prompt-toolでも通せます。ultracodeがオンのセッションで承認がスキップされるのは、autoモードの初回起動だけです。
規模とコストを抑える
大きな実行を始める前の下準備は、公式ドキュメントが勧める順に並べると次のとおりです。
大きなタスクの前にやること
- 1
小さな一部で試す
リポジトリ全体ではなく1ディレクトリ、広い質問ではなく狭い質問から始めます。
/workflowsにはエージェントごとのトークン使用量が出るので、増え方を見てから広げられます。 - 2
サイズ指針を決める
Claudeがスクリプトを書くときの目安を
/configか設定ファイルで選びます。 - 3
モデルを確かめる
各エージェントは、スクリプトが指名しなければセッションのモデルで動きます。普段は軽いモデルに切り替えているなら、
/modelを先に見ます。 - 4
Large workflow の表示を待つ
予定が25体を超えるか、トークンの見込みが150万を超えると、入力欄下の進捗行に警告が出ます。止めるかどうかは
/workflowsで決めます。
サイズ指針の値
workflowSizeGuidelineは、Claudeがワークフローを書くときに目指すエージェント数です。助言であり上限ではないため、依頼がそれより大きい規模を求めれば、指針を超えるスクリプトも書かれます。v2.1.202以降で使えます。
| 値 | 目指すエージェント数 |
|---|---|
unrestricted | 目指すエージェント数指針なし。タスクに応じてClaudeが判断 |
small | 目指すエージェント数5体未満 |
medium | 目指すエージェント数10体未満 |
large | 目指すエージェント数50体未満 |
既定はmediumです。v2.1.271以降でProプランにサインインしていればsmallになります。v2.1.219より前の版の既定はunrestrictedでした。/config workflowSizeGuideline=smallのように直接指定できます。
/config workflowSizeGuideline=smallv2.1.219以降は、設定ファイルにworkflowSizeGuidelineを書くとそちらが優先され、/configの行は非表示になります。自分で指針を選ぶと、Large workflow警告の25体という閾値が、その値のエージェント数に置き換わります。ultracodeがオンのセッションでは、大規模実行に同意済みとして警告自体が出ません。
ランタイム側の上限
指針とは別に、ランタイムが強制する上限があります。
1回の実行にかかるランタイムの上限
同時実行
16体
既定。CPUが少ない環境やコンテナではさらに減る
同時実行の上限変更
1〜256
CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS(v2.1.269以降)
1回の呼び出しの要素数
4,096
parallel() / pipeline() に渡せるリストの長さ
実行全体のエージェント数
1,000
暴走ループの防止
組織のavailableModels許可リストがスクリプトの指名したモデルを止めると、置き換えられたモデルで実行が続きます。進捗ビューに、要求されたモデルと実際のモデルの両方が警告として出ます。ファンアウトで同時に起動した複数のエージェントがプロンプトキャッシュを読み合う条件と、既定5分のTTLはClaude Codeワークフローのプロンプトキャッシュの効き方にまとめています。
止めた実行はどこまで戻るか
再開の挙動は、止め方で分かれます。公式ドキュメントは、実行を起動順に再生し、各エージェントが保存済みの結果を返すか、もう一度走るかを決めると説明しています。
エージェントごとの再開時の扱い
完了していた
前回と同じプロンプトで完了していれば、結果はそのまま使われます。例外は、スクリプトを編集した、または手前のエージェントが前回と違う結果を返したためにプロンプトが変わった最初のエージェントです。そこから後ろは、完了済みでも再実行されます。
実行中に止めた
実行全体を止めた場合、走っていたエージェントは失敗とは数えられず、最初から走り直すだけです。後続の再実行は連鎖しません。
失敗した
失敗したエージェントと、それより後に起動した全エージェントが、完了済みでも再実行されます。/workflowsで1体だけ選んでxを押した場合も、失敗として数えられます。
具体例です。スクリプトがA・B・C・Dの順に起動し、Bが失敗したとします。再開するとAはキャッシュから返り、B・C・Dは再実行されます。Cが先に完了していても同じです。
再開できる範囲
一時停止した実行は、/workflowsで選んでpを押すと再開します。止めた実行は、エージェントのプロセスが残っている間はタスクパネルに残ります。もう一度止めると、残ったプロセスへ再度シグナルが送られます。止めた実行を続けるには、同じスクリプトでの再起動をClaudeに頼みます。前回のエージェントがまだ終了していなければ、二重に走らないよう再起動は拒否されます。
動作中のワークフローで←を押すか/backgroundを実行すると、完了済みのサブエージェントが再起動します。v2.1.246からは、何体が再起動するかが表示され、先に確認を求められます。
再開が効くのは同一セッションの中です。セッションをバックグラウンドに回した場合は、バックグラウンドセッションが同じ要領で再生して続けます。実行中にClaude Codeを終了するときは、エージェントビューがオンならMove to background and exitで持ち越せます。Exit and stop tasksを選ぶと実行は止まりますが、結果は~/.claude/projects/のセッション配下に残ります。claude --resumeで戻ったセッションなら、再起動を頼むと再生されます。新しく始めたセッションには前回の実行が無く、新規の実行として始め直しになります。
保存済みの結果がどこにも見つからないときは、再起動はnothing to resumeのエラーで失敗します。勝手に最初から走り直すことはありません。
使用量上限に当たったとき
v2.1.271以降は、claude.aiの使用量上限に当たったエージェントは失敗せず、リセットまで待ちます。新しいエージェントは始まらず、リセット直後に待機分が走り出します。進捗行と/workflowsのヘッダーにリセット時刻が出ます。
この待機が働くのは、対話セッションでclaude.aiのサブスクリプションにサインインしている場合です。次の4つの条件をすべて満たさないと、該当のエージェントは失敗として扱われます。
claude -p・Agent SDK・バックグラウンドセッション・Remote Control・エージェントチームのチームメイトのセッションのいずれでもないautoContinueAtUsageLimitがオンである(待機中にオフにすると、待っていたエージェントが失敗する)- リセットが24時間以内である(週次の上限は、それより先になることがある)
- 同じ実行で待機した回数が2回以内である(3回目は失敗する)
保存して再利用する
気に入った実行のスクリプトは、/workflowsで選んでsを押し、保存ダイアログのTabで保存先を切り替えるとコマンド化できます。
| 保存先 | 範囲 |
|---|---|
.claude/workflows/(プロジェクト) | 範囲リポジトリをcloneした全員と共有 |
~/.claude/workflows/(ホーム) | 範囲自分の全プロジェクトで使用、他者には非公開。CLAUDE_CONFIG_DIRを設定していればその配下のworkflows/ |
同名のワークフローがプロジェクトと個人の両方にあれば、プロジェクト側が動きます。保存前にはシンボリックリンクの検査が入ります。プロジェクト保存では.claude・.claude/workflows・保存先ファイルのどれかがリンクだと拒否されます。個人保存はファイル自体がリンクのときだけ拒否されます。
モノレポでは、作業ディレクトリからリポジトリルートまでの間で、最も近い既存の.claude/workflows/に保存されます。無ければリポジトリルートです。同名が複数階層にあれば、作業ディレクトリに近い方が実行されます。
保存したワークフローには、argsで入力を渡せます。スクリプトはargsというグローバル変数として読むので、対象パスや設定値を毎回書き換える必要がありません。
Run /triage-issues on issues 1024, 1025, and 1030チームや複数リポジトリへの配布にはClaude Codeプラグインが使えます。プラグインルートのworkflows/にスクリプトを置くだけで、名前空間はプラグイン名になります。acme-toolsプラグインのmeta.name: 'release-audit'なら、/acme-tools:release-auditです。argsの読み方と配布時の落とし穴はworkflowにargsを渡しプラグインで配布する記事にあります。
保存したスクリプトを編集する
保存されたワークフローは、metaブロックと、トップレベルawaitを使うプレーンなJavaScriptの本体でできています。
export const meta = {
name: 'audit-routes',
description: 'Audit every route handler for missing auth checks',
}
const found = await agent('List every .ts file under src/routes/.', {
schema: { type: 'object', required: ['files'], properties: { files: { type: 'array', items: { type: 'string' } } } },
})
const audits = await pipeline(found.files, file =>
agent(`Audit ${file} for missing authentication checks.`, { label: file }),
)
return audits.filter(Boolean)agent()はサブエージェントを1体起動します。pipeline()はリストの要素ごとに1体ずつ、parallel()は複数の作業を同時に走らせて全部の完了を待ちます。止められたエージェントや回復不能なAPIエラーに当たったエージェントはnullを返します。pipeline()はnullもそのまま配列に残すので、.filter(Boolean)で除くのが定型です。
編集の前に、バンドルされた/workflow-authoringスキル(v2.1.248以降)を実行すると、Claudeがスクリプトを書くときの参照資料が読み込まれます。直したあとは/reload-skillsでワークフローのディレクトリを読み直してから、/<name>を呼びます。ファイルには次の決まりがあります。
export const metaは先頭の文にし、nameとdescriptionを持つ素のオブジェクトリテラルにします。変数・関数呼び出し・スプレッドを入れると、/の補完から消えますphasesをmetaに書くなら、各項目をphase()に渡すタイトルと同じ文字列にします。一致しないphase()は独立した進捗グループになりますDate.now()、Math.random()、引数なしのnew Date()は例外を投げます。再実行しても同じagent()呼び出しが再現されるようにするためで、時刻はargsで渡します- スクリプトに
import()があると、実行の開始前に失敗します。ライブラリが要る処理はエージェントに任せます
停止と失敗を分ける設計が意味するもの
進捗を見る・止める・再開する・保存する、の4つが同じ/workflowsに集まったことで、ダイナミックワークフローは「Claudeに任せて結果を待つ」機能から、規模を絞って繰り返す運用に寄っています。
その中心にあるのが、停止と失敗の区別です。同じ「止める」操作でも、再開時の再実行コストが操作の選び方で変わります。止める操作そのものが、コスト設計の一部になりました。
もう一つは、サイズ指針の既定が小さくなり続けている点です。1つのスクリプトに詰め込むより、フェーズごとに分けて走らせる運用と相性のよい流れです。
運用でつまずきやすい点
サイズ指針を上限だと思う
workflowSizeGuidelineは助言です。依頼が大規模な処理を求めれば、指針を超えるスクリプトが書かれます。上限として効くのは、ランタイム側の同時16体・1回4,096要素・全体1,000体です。
個別停止のあとで再開すると、後続がまとめて再実行される
先に走ったエージェントの結果が要らなくなったときは、xで個別に止めるより、実行全体を止めて必要な部分だけ新しい実行で頼む方が、再実行の連鎖を避けられます。個別停止は失敗として数えられるため、後続の完了済みエージェントも巻き込まれます。
プロジェクト保存がシンボリックリンクで拒否される
dotfilesツールで.claudeをシンボリックリンク管理していると、プロジェクト保存は拒否されます。個人保存(~/.claude/workflows/)は、保存先ファイル自体がリンクでなければ書き込めるので、回避策になります。
保存したワークフローが補完に出ない
metaが変数や関数呼び出しを含むと、/の補完から外れます。ほかに、disableWorkflows・CLAUDE_CODE_DISABLE_WORKFLOWS・/configのトグルのどれかでワークフロー機能が切られている場合も、バンドルのコマンドと/workflow-authoringが使えなくなります。起動オプションの--safe-modeもワークフローを無効にするので、設定の切り分けでは外して試します。
--effortの値にultracodeが出ない
公式ドキュメントはclaude --effort ultracodeでの起動を案内しています。一方、v2.1.289のclaude --helpは--effortの値をlow, medium, high, xhigh, maxの5つと表示します。ultracodeを使うセッションでは、起動後に/effort ultracodeで切り替えられます。
まとめ
大きな実行は、smallの指針と小さな対象で試し、/workflowsでトークンの増え方を見てから広げる流れになります。保存する価値のある実行は、sでコマンドにしておくと次回から引数だけで呼べます。テレメトリ側から実行を追うなら、workflow.run_idによる束ね方があります。
参照した一次ソース
この記事の記述は、次の一次ソースと照合しています。更新時に参照先が変わった場合は一覧も更新します。