Claude Code のダイナミックワークフローは、サブエージェントの動かし方そのものを JavaScript のスクリプトとして書き出し、そのスクリプトをランタイムが実行する仕組みです。会話のターンごとに Claude が次の一手を決めるのではなく、繰り返し・分岐・ファンアウトをコードが持つため、1回の実行で数十から数百のエージェントを動かせます。
この記事では、公式ドキュメントに基づいて、ワークフローが他の仕組みと何が違うのか、どう起動するのか、生成されたスクリプトはどんな形をしているのか、そして実行中の管理・再開・上限・コストをどう見るのかを順に説明します。ダイナミックワークフローの利用には Claude Code v2.1.154 以降が必要です。
ダイナミックワークフローとは何か
ダイナミックワークフローとは、サブエージェントを大規模に指揮する JavaScript のスクリプトです。あなたが依頼した内容に対して Claude がスクリプトを書き、専用のランタイムがそれをバックグラウンドで実行します。実行中もセッションは応答可能なままなので、ワークフローの完了を待つあいだに別の作業を続けられます。
向いているのは、次のどちらかに当てはまる作業です。ひとつは、1つの会話では調整しきれない数のエージェントが必要な作業。もうひとつは、その指揮の手順そのものをスクリプトとして読み、再実行したい作業です。公式ドキュメントは具体例として、コードベース全体のバグ掃討、500ファイル規模の移行、複数の情報源を互いに突き合わせる必要がある調査、そして決める前に複数の独立した角度から下書きしておきたい難しい計画、の4つを挙げています。
いちばん手早く動きを確かめる方法は、同梱されている /deep-research を実行することです。これは1つの問いについて複数の角度から Web 検索をファンアウトし、見つけた情報源を取得して相互に突き合わせ、出典つきのレポートを返す組み込みワークフローです。突き合わせに耐えなかった主張は除外されたうえで報告されます。
/deep-research What changed in the Node.js permission model between v20 and v22?実行すると、Claude Code がワークフローを許可してよいか尋ねてきます。Yes を選ぶと、実行はバックグラウンドで始まります。/deep-research は自分で呼び出したときだけ動き、勝手に起動することはありません。
なお、検証エージェントがレート制限や API エラーで主張を確認できなかった場合、そのレポートではその主張が「反証された」ではなく未検証として列挙されます。確認できなかったことと否定されたことを混ぜない設計になっています。
サブエージェント・スキル・エージェントチームとの違い
サブエージェント、スキル、エージェントチーム、ワークフローは、いずれも複数の手順からなる作業を実行できます。違いは誰が計画を持っているかです。公式ドキュメントの比較表を要約すると次のようになります。
| サブエージェント | スキル | エージェントチーム | ワークフロー | |
|---|---|---|---|---|
| 正体 | Claude が起動する作業者 | Claude が従う指示書 | 対等なセッションを監督するリードエージェント | ランタイムが実行するスクリプト |
| 次に何を動かすか決めるのは | Claude（ターンごと） | Claude（プロンプトに従う） | リードエージェント（ターンごと） | スクリプト |
| 途中結果の置き場所 | Claude のコンテキストウィンドウ | Claude のコンテキストウィンドウ | 共有のタスクリスト | スクリプトの変数 |
| 再利用できるもの | 作業者の定義 | 指示そのもの | チームの定義 | 指揮の手順そのもの |
| 規模 | 1ターンあたり数件の委譲 | サブエージェントと同じ | 長時間動く数体 | 1回の実行で数十から数百体 |
| 中断したとき | ターンをやり直す | ターンをやり直す | チームメイトは動き続ける | 同じセッション内で再開できる |
ここでいちばん実務に効く違いは、途中結果の置き場所です。サブエージェント・スキル・エージェントチームでは Claude が指揮役なので、結果はすべてコンテキストウィンドウに戻ってきます。ワークフローでは、ループも分岐も途中結果もスクリプトが自分で保持するため、Claude のコンテキストには最終的な答えだけが載ります。100ファイルを1体ずつ調べさせても、100個の調査ログが会話に流れ込むことはありません。
もうひとつ、計画をコードに移すことで再現可能な品質パターンを適用できるようになります。たとえば、独立したエージェントに互いの発見を敵対的にレビューさせてから報告する、あるいは複数の角度から計画を起草して互いに比較する、といった形です。1回きりの実行より信頼できる結果が得られる、というのが公式の説明です。
ワークフローを起動する三つの方法
ワークフローを始める方法は3つあります。
1. プロンプトに ultracode と書く
セッションの努力度（effort）を変えずに、その1件だけをワークフローとして実行したいときは、プロンプトに ultracode というキーワードを含めます。
ultracode: audit every API endpoint under src/routes/ for missing auth checks「use a workflow」「run a workflow」のように自分の言葉で頼んでも同じ扱いになります。Claude Code は入力欄でキーワードを強調表示し、Claude はターンごとに作業する代わりにワークフロー用のスクリプトを書きます。なお v2.1.160 より前は、キーワードそのものが workflow でした。自然言語での依頼はどちらのバージョンでも通ります。
意図せず起動しそうになったときは、macOS では Option+W、Windows と Linux では Alt+W で強調表示を取り消せます。強調されたキーワードの直後にカーソルがある状態でバックスペースを押しても同じです。キーワードそのものを無効にしたい場合は、設定で「Ultracode keyword trigger」をオフにします。
重要な点として、このキーワードはあなた自身が打ったプロンプトでのみオプトインとして働きます。対話プロンプト、IDE 拡張のパネル、リモートコントロールのクライアント、そして入力を人間由来として記録する Agent SDK アプリケーションが対象です。次の経路から届いたプロンプトではワークフローは起動しません。
-pで渡したプロンプト- 人間の入力として記録せずに Agent SDK アプリケーションが送ったプロンプト
- スケジュールされたタスクのプロンプト
- 会話に中継された Webhook のペイロードやプルリクエストのコメント
v2.1.210 より前は、これらの経路からもキーワードがワークフローを起動していました。外部から来た文字列で勝手に大量のエージェントが動かないよう、後から絞られた形です。
2. ultracode を効かせたセッションにする
ultracode は、xhigh の推論努力度と自動的なワークフロー編成を組み合わせた Claude Code の設定です。オンにすると、依頼を待たずに Claude が実質的な作業ごとにワークフローを計画するようになります。
/effort ultracode最初からオンの状態でセッションを始めるには claude --effort ultracode で起動します（v2.1.203 以降）。オンのあいだは、1つの依頼が連続する複数のワークフローに分かれることがあります。コードを理解するもの、変更を加えるもの、検証するもの、という具合です。セッション内のすべての作業に適用されるため、1件あたりのトークン消費と所要時間は他の努力度より増えます。日常的な作業に戻るときは /effort high で下げます。
3. 保存済み・同梱のワークフローコマンドを呼ぶ
気に入った実行結果はコマンドとして保存できます。/workflows で対象の実行を選び s を押すと保存ダイアログが開き、保存先を2つから選べます。.claude/workflows/（プロジェクト内。リポジトリを clone した全員で共有）と、~/.claude/workflows/（ホームディレクトリ。すべてのプロジェクトで使えるが自分だけに見える）です。保存後は /<名前> として実行できます。
保存したワークフローには、args という名前のグローバル変数として入力を渡せます。次のように依頼すると、Claude が構造化データとして渡すので、スクリプト側は解析せずにそのまま配列やオブジェクトのメソッドを呼べます。
Run /triage-issues on issues 1024, 1025, and 1030args を渡さなかった場合、スクリプト内のグローバルは undefined になります。
保存されたスクリプトの中身を読む
保存したワークフローのファイルは、meta ブロックと、それに続くスクリプト本体という形をしています。通常は編集する必要がありませんが、Claude が何を生成したのかを読み取れるように、公式ドキュメントが示している小さな例を引用します。
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)本体はトップレベル await が使える素の JavaScript です。agent() がサブエージェントを1体起動し、pipeline() がリストの要素ごとに1体ずつ走らせます。
末尾の .filter(Boolean) には理由があります。agent() の呼び出しは、実行中にそのエージェントを停止した場合や、回復不能な API エラーに当たった場合に null を返します。pipeline() はその null を結果の配列にそのまま残すため、使う前に落とす必要があるのです。
スクリプトを自分で書き換えたい場合は、Claude に変更点を説明させるか、Agent SDK リファレンスの Workflow ツールの項目で全オプションを確認してください。
実行時のスクリプトはどこに置かれるか
ワークフローランタイムは、会話とは切り離された環境でスクリプトを実行します。途中結果は Claude のコンテキストではなくスクリプトの変数に残ります。
実行のたびに、そのスクリプトは ~/.claude/projects/ 配下のセッションディレクトリへファイルとして書き出されます。実行開始時に Claude はそのパスを受け取るので、パスを尋ねればそのまま教えてもらえます。ファイルを開いて Claude が書いた指揮の内容を読む、前回の実行のスクリプトと差分を取る、あるいは自分で編集して「この版で再実行して」と頼む、といった使い方ができます。
どんな依頼がワークフロー向きか
公式ドキュメントが挙げているプロンプトの形をいくつか紹介します。いずれもスクリプトは自分で書かず、その作業のためのワークフローを書いて実行するよう Claude に頼む形です。
- 同じ問題について多数のファイルを監査する:
use a workflow to audit every route handler under src/routes/ for missing authentication checks, and adversarially verify each finding before reporting it - 検査が通るまで直し続ける:
use a workflow to run npx tsc --noEmit and keep fixing the reported errors until the type check passes or two rounds in a row make no progress - 多数のファイルを並列に移行する（衝突しないよう1ファイルずつ隔離したコピーで作業させる）
- 変更ファイルごとにレビューを走らせ、最後に1体が順位づけと重複排除をして1つの要約にまとめる
- 新しい発見が2周続けて出なくなるまで探索を繰り返す
実行中の管理・再開・上限とコスト
実行が始まったら、/workflows の画面か、入力欄の下のタスクパネルで進捗行を展開して管理します。
/workflows進捗ビューには各フェーズのエージェント数、トークン合計、経過時間が出ます。フッターに操作キーが並びます。主なものは次のとおりです。
| キー | 動作 |
|---|---|
↑ / ↓ | フェーズまたはエージェントを選ぶ |
Enter または → | 選んだフェーズへ、さらにエージェントへ降りて、そのプロンプト・直近のツール呼び出し・結果を読む |
Esc または ← | 1階層戻る。v2.1.203 から v2.1.205 では ← が戻らないので Esc を使う |
f | 選んだフェーズのエージェント一覧を状態で絞り込む（押すたびに切り替わる） |
p | 実行の一時停止と再開 |
x | 選んだエージェントを停止する。実行そのものにフォーカスがあるときはワークフロー全体を停止する |
r | 選んだ実行中のエージェントを再起動する |
s | その実行のスクリプトをコマンドとして保存する |
再開の落とし穴
止めた実行は再開できます。ただし、どの結果が残るかには2つの規則があり、これを知らないと再開のたびに同じ作業をやり直すことになります。
- 停止時点でまだ動いていたエージェントの結果は保存されないので、再開時に最初からやり直す。
- 再生（リプレイ）はエージェントが開始した順にたどる。キャッシュされた結果は、完了しなかった最初のエージェントで打ち切られ、それより後に開始したエージェントは、完了していてもすべて再実行される。
2番目の規則が、ファンアウトの途中で止めることを高くつかせます。公式ドキュメントの例をそのまま挙げると、スクリプトが A、B、C、D の順に4体を起動し、B が動いている最中に停止したとします。再開すると A はキャッシュから返ります。B は完了していないので再実行されます。そしてC と D も、停止前に完了していたにもかかわらず再実行されます。B より後に開始したためです。
ここから導かれる設計の指針は明快です。作業を多数の小さなエージェントへ分けたワークフローのほうが、1体の長いエージェントに任せるより、停止時に失う進捗が少なくなります。
一時停止した実行は、/workflows で選んで p を押すか、同じスクリプトで再実行するよう Claude に頼めば再開できます。ただし再開が効くのは同じ Claude Code セッション内だけです。ワークフローが動いている状態で Claude Code を終了すると、次のセッションではワークフローは最初から始まります。
ランタイムの上限
ランタイムには次の制約があります。
- 実行中のユーザー入力は受け付けない。実行を止められるのはエージェントの権限プロンプトだけ。段階ごとに承認を挟みたい場合は、各段階を別々のワークフローとして実行する
- ワークフロー自身からのファイルシステム・シェルへの直接アクセスは無い。読み書きとコマンド実行を担うのはエージェントで、スクリプトはそれらを調整する
- モジュールの読み込みは不可。
import()を含むスクリプトは実行開始前に失敗する。ライブラリが要る処理はエージェントの作業として渡す - 同時に動くエージェントは最大16体。Claude Code が使える CPU が少ない環境（CPU 制限のあるコンテナを含む）ではさらに減る
- 1回の実行あたりのエージェント総数は1,000体。暴走したループを止めるための上限
コストの見方
ワークフローは多数のエージェントを起動するため、1回の実行で、同じ作業を会話で進めた場合よりも明確に多いトークンを消費します。消費はプランの使用量とレート制限に、通常のセッションと同じように計上されます。
大きな作業に踏み切る前に支出を見積もるには、まず小さく切って実行してみるのが確実です。リポジトリ全体ではなく1ディレクトリ、広い問いではなく狭い問い、という具合です。/workflows の画面では各エージェントのトークン使用量が進行中に表示され、いつでも実行を止められます。前述のとおり、完了済みの作業は通常そのまま残ります。
Claude Code は、異常に大きく育った実行に警告も出します。スケジュールされたエージェントが25体を超えるか、予測トークン合計が150万を超えると、タスクパネルの進捗行に Large workflow の警告が出ます。これは助言であって、実行を止めたり制限したりはしません。サイズの目安（size guideline）を自分で選んでいる場合はそのエージェント数が25体のしきい値を置き換え、ultracode がオンのセッションでは警告は出ません。
ワークフロー内のエージェントは、スクリプトが別のモデルを指定しない限りセッションのモデルを使います。日常的に小さいモデルへ切り替えている人は、大きな実行の前に /model を確認してください。強いモデルが要らない段階には小さいモデルを使うよう、依頼の時点で伝えておくこともできます。
規模の目安を設定する
サイズの目安は、Claude がワークフローを書くときに狙うエージェント数を伝える設定です。上限ではなく助言として渡されるため、別の規模を要求するプロンプトはこの目安を上書きします（v2.1.202 以降）。
| 値 | Claude が狙うエージェント数 |
|---|---|
unrestricted | 目安なし。作業に合わせて Claude が決める |
small | 5体未満 |
medium | 15体未満 |
large | 50体未満 |
既定は medium です（v2.1.219 以降。それより前のバージョンの既定は unrestricted）。変更は次のプロンプトから効きます。ランタイムのエージェント上限は、この設定にかかわらず適用されます。
ワークフローを無効にする
ワークフローは CLI、デスクトップアプリ、IDE 拡張、claude -p の非対話モード、Agent SDK で使えます。無効化の設定はどの経路でも共通です。自分だけ無効にするには、設定で「Dynamic workflows」をオフにするか、~/.claude/settings.json に "disableWorkflows": true を書くか、環境変数 CLAUDE_CODE_DISABLE_WORKFLOWS=1 を設定します。組織全体で無効にする場合は、管理された設定に同じキーを書きます。
無効にすると、同梱のワークフローコマンドは使えなくなり、ultracode キーワードは実行を起動しなくなり、/effort のメニューから ultracode が消えます。
参考にした公式ドキュメント
本記事は次の Anthropic 公式ドキュメントを 2026年8月26日に参照して執筆した、非公式の日本語訳・解説です。バージョン番号や上限値は変わることがあるため、最新の仕様は公式ドキュメントで確認してください。
- Orchestrate subagents at scale with dynamic workflows（本記事の主たる出典。定義・起動方法・スクリプトの形・ランタイムの上限・再開規則・コストの節はすべてこのページに基づいています）
- Claude Code Overview（ダイナミックワークフローが Claude Code 全体のどこに位置づけられるかの確認）