背景

この連載では、Claude Codeの公式ドキュメントを1ページずつ読み解いていきます。公式ドキュメントは情報が網羅されている分、「結局どの機能を、どんな場面で使えばいいのか」は自分で考える必要があり、読むのに意外と時間がかかります。そこで、私が実務で使うために読み込んだ内容を「使う場面→実例コード」の順に整理して残していくことにしました。専門家の解説というより、一次情報を読んだ記録です。推測や動作を確認していない部分には、その都度そう書きます。

1. 一言でいうと何か

このページは、Claude が書いた JavaScript スクリプトが、数十から数百のサブエージェントを指揮する——動的ワークフローの解説です。

第64回で示された並列化4アプローチの、最後の1つ。これで並列化クラスタが完結します。

定義は簡潔です。動的ワークフローは、サブエージェントを大規模にオーケストレーションする JavaScript スクリプトです。Claude は説明したタスク用のスクリプトを作成し、ランタイムはバックグラウンドで実行しながら、セッションは応答性を保ちます。

この機能の本質を、原文は一文で言い切っています。

違いは、計画を保持する者です。

サブエージェント・スキル・エージェントチームではClaude がオーケストレーターで、**ターンごとに次に何を生成または割り当てるかを決定し、すべての結果は Claude のコンテキストウィンドウに入ります。**対してワークフローは——ワークフロースクリプトはループ、分岐、および中間結果自体を保持するため、Claude のコンテキストは最終的な答えのみを保持します。

**判断の主体をモデルからコードに移す。**そしてその副作用として、**中間結果がコンテキストを食わない。**この2つが動的ワークフローの正体です。

前提を先に置きます。動的ワークフローは Claude Code v2.1.154 以降が必要で、すべての有料プランで利用可能です。提供面はAnthropic API アクセス、Amazon Bedrock、Google Cloud の Agent Platform、Microsoft Foundry。そしてPro では、/config の Dynamic workflows 行からオンにしてください。——Pro は既定でオフです。

2. どういう場面で役立つか

原文が挙げる典型は4つ。コードベース全体のバグスイープ、500ファイルのマイグレーション、複数のソースに対して相互検証が必要な研究質問、1つにコミットする前に複数の独立した角度から下書きする価値のある難しい計画。

シーン1：1つの会話が調整できる量を超えている

1つの会話が調整できるより多くのエージェントが必要なタスク。500ファイルの移行を1つの会話で回そうとすると、コンテキストが先に尽きます。ワークフローなら中間結果はスクリプト変数に留まるので尽きません。

シーン2：同じオーケストレーションを繰り返したい

オーケストレーションを読み直して再実行できるスクリプトとしてコード化したい場合。比較表の「繰り返し可能なもの」の行が明快で、サブエージェントはワーカー定義、スキルは指示、エージェントチームはチーム定義が再利用対象なのに対し、ワークフローだけがオーケストレーション自体を再利用します。

原文の例——すべてのブランチで実行するレビューなどのプロセスは、毎回同じオーケストレーションを実行します。

シーン3：品質パターンを機械的に強制したい

ここが見落とされやすい価値です。計画をコードに移動することで、ワークフローは単に複数のエージェントを実行するだけでなく、繰り返し可能な品質パターンを適用することもできます。独立したエージェントが相互に対立的にレビューしてから報告されるようにすることも、複数の角度から計画を下書きして相互に比較することもできるため、単一パスより信頼性の高い結果が得られます。

「対立的にレビュー」は第66回のエージェントチームでも出ましたが、あちらはClaude が調整するので毎回同じにはなりません。ワークフローはスクリプトが強制するので毎回同じです。

不要・向かないケース

• **途中で人間が判断を挟みたい。**制約の筆頭がこれです。実行中のユーザー入力なし。原文の回避策はステージ間の署名のために、各ステージを独自のワークフローとして実行します。
• **ターンごとの柔軟な判断が要る。**それはサブエージェントやエージェントチームの領分です。
• **Claude Code を終了する予定がある。****ワークフローが実行中に Claude Code を終了した場合、次のセッションはワークフローを新規に開始します。**再開は同一セッション内だけです。
• **トークンを抑えたい。**単一の実行は会話で同じタスクを処理するより意味のあるほど多くのトークンを使用できます。
• スクリプト自身にファイルを触らせたい。****ワークフロー自体からの直接ファイルシステムまたはシェルアクセスなし。——**エージェントは読み取り、書き込み、コマンドを実行します。スクリプトはエージェントを調整します。**役割分担が固定されています。
• **組織方針で無効化されている場合。**管理設定で "disableWorkflows": true が設定されていると、バンドルされたワークフローコマンドは利用不可、ultracode キーワードは実行をトリガーしなくなり、ultracode は /effort メニューから削除されます。

3. コマンド・プロンプトの実例と解説

フェンス付きブロックは13種類（/workflows の重複を除く）。**すべて原文どおり引用します。**大半は自然言語のプロンプト例で、実際の JavaScript は1本だけです。

前提の再掲：v2.1.154 以降／有料プラン限定／Pro は /config で有効化が必要。

まず組み込みのものを動かす

最速の方法でワークフローの動作を確認するには、Claude Code に含まれている組み込みワークフロー /deep-research を実行します。

/deep-research What changed in the Node.js permission model between v20 and v22?

これが何をするかは表で定義されています。

コマンド	実行内容
/deep-research <question>	複数の角度にわたって質問に対する Web 検索をファンアウトし、見つけたソースをフェッチして相互検証し、各クレームに投票し、相互検証を生き残らなかったクレームがフィルタリングされた引用されたレポートを返します。WebSearch ツールが利用可能である必要があります

「各クレームに投票する」——ここが単なる並列検索との違いです。そして未検証の扱いも明記されています。**v2.1.196 以降、検証エージェントがレート制限や API エラーの後など、クレームを確認できない場合、レポートはそのクレームを未検証として列挙し、反論されたものとしてカウントしません。**確認できなかったことと否定されたことを混同しない設計です。

実行すると許可を求められ、Yes を選ぶとバックグラウンドで走り出します。セッションが無料のままで、ターンバイターンのトランスクリプトの代わりに1つのレポートを取得しながら、エージェントがバックグラウンドで一連のフェーズを処理するのを見ることができます。

実行を見る

/workflows

**ビューは各フェーズをエージェント数、トークン合計、経過時間とともに表示します。**キー割り当ては次のとおり。

キー	アクション
↑ / ↓	フェーズまたはエージェントを選択
Enter または →	選択したフェーズにドリルダウンし、次にエージェントにドリルダウンしてプロンプト、最近のツール呼び出し、結果を読む
Esc または ←	1レベル戻る。v2.1.203 から v2.1.205 では、← はフェーズまたはエージェントから戻りませんでした。これらのバージョンでは Esc を使用してください
j / k	オーバーフローするときにエージェント詳細内でスクロール
f	選択したフェーズのエージェントリストをステータスでフィルタリングします。もう一度押すとサイクルします
p	実行を一時停止または再開
x	選択したエージェントを停止するか、フォーカスが実行にあるときにワークフロー全体を停止
r	選択した実行中のエージェントを再開始
s	実行のスクリプトを保存してコマンドとして保存

個別のエージェントを止めたり再起動できる（x と r）のは、大規模実行では実用的な機能です。

入力ボックスの下のタスクパネルからも監視できます。実行中は1行の進捗サマリーが表示されます。下矢印を押してフォーカスし、Enter キーを押して展開します。

自分のタスクをワークフローにする

方法は2つ。プロンプトでワークフローを要求するか、ultracode で Claude に決定させるか。

**(1) プロンプトで要求する。**キーワードを含めるか、自然言語で頼みます。

ultracode: audit every API endpoint under src/routes/ for missing auth checks

「ワークフローを使用する」または「ワークフローを実行する」など、自分の言葉で要求することもできます。Claude は直接的な要求を同じオプトインとして扱います。なおv2.1.160 より前は、リテラルトリガーキーワードは workflow でした。自然言語リクエストは両方のバージョンで機能します。

誤爆した場合の抜け方も用意されています。macOS で Option+W または Windows と Linux で Alt+W を押してこのプロンプトのハイライトを無視するか、ハイライトされたキーワードの直後にカーソルがある状態でバックスペースを押します。キーワードがまったくトリガーされないようにするには、/config で Ultracode キーワードトリガーをオフにします。

キーワードが本文に紛れ込んだだけで発火しうるということでもあります。無効化スイッチが用意されているのは、その事故が想定されているからだと思います（この解釈は筆者のもので、原文は理由を書いていません）。

(2) セッション全体をワークフロー前提にする。

/effort ultracode

Ultracode は、xhigh 推論努力と自動ワークフローオーケストレーションを組み合わせた Claude Code 設定です。オンにすると、Claude は各実質的なタスク用にワークフローを計画し、あなたが要求するのを待ちません。

代償も率直に書かれています。単一のリクエストは複数のワークフローに変わる可能性があります。コードを理解するためのワークフロー、変更を加えるためのワークフロー、検証するためのワークフロー。これはセッション内のすべてのタスクに適用されるため、各リクエストはより多くのトークンを使用し、より低い努力レベルより長くかかります。

Ultracode は現在のセッション用に続き、新しいセッションを開始するときにリセットされます。戻すときは/effort high でドロップバック。起動時から有効にするなら claude --effort ultracode（v2.1.203 以降）。使えるのは**xhigh 努力をサポートするモデル**だけで、他のモデルでは、/effort メニューはそれを提供しません。

実行前の承認

CLI では計画されたフェーズと4つの選択肢が出ます。Yes, run it / Yes, and don’t ask again for <name> in <path> / View raw script / No。加えて**Ctrl+G はエディターでスクリプトを開きます。Tab を使用すると、実行開始前にプロンプトを調整できます。**

プロンプトが出るかどうかは権限モード次第です。

権限モード	プロンプトが表示される場合
デフォルト、編集を受け入れ	すべての実行、そのワークフロー用にYes, and don’t ask again を選択していない限り
自動	最初の起動のみ。任意の Yes はユーザー設定に同意を記録し、後の起動はプロンプトなしで開始します。ultracode がオンの場合は完全にスキップされます
権限をバイパス、claude -p、Agent SDK	なし。実行は直ちに開始

ここに必ず読むべき一段落があります。

権限モードは上記の起動プロンプトのみを制御します。ワークフローが生成するサブエージェントは常に acceptEdits モードで実行され、セッションのモードに関係なく、ツール許可リストを継承します。ファイル編集は自動承認されます。

**セッションが厳しい権限モードでも、ワークフロー内のエージェントのファイル編集は自動承認される。**起動を承認した時点で、その中の編集も承認したことになります。

一方、完全な無制限ではありません。**シェルコマンド、Web フェッチ、許可リストにない MCP ツールは、実行中にプロンプトを表示できます。**長時間実行でこれに引っかからないための助言も添えられています。エージェントが必要とするコマンドを開始前に許可リストに追加します。

Desktop アプリでは承認カードはワークフロー名、フェーズリスト、トークン使用量の注意を表示し、Once、Always、Deny アクションがあります。進捗ビューは Background tasks サイドペインに表示されます。

保存してコマンドにする

**/workflows を実行し、保持したい実行を選択し、s を押します。**保存先は Tab で2択。

• .claude/workflows/ プロジェクト内。リポジトリをクローンする全員と共有
• ~/.claude/workflows/ ホームディレクトリ内。すべてのプロジェクトで利用可能、自分にのみ表示。CLAUDE_CONFIG_DIR を設定している場合はそのパスの下の workflows/ ディレクトリ

保存すると**/<name> として実行**でき、バンドルされたものと一緒に / オートコンプリートに表示されます。

モノレポでの解決順が細かく定義されています。v2.1.178 以降、プロジェクトの場所に保存すると、作業ディレクトリとリポジトリルートの間に既に存在する最も近い .claude/workflows/ ディレクトリに書き込まれるか、まだ存在しない場合はリポジトリルートに書き込まれます。プロジェクトワークフローはその経路に沿ったすべての .claude/workflows/ から読み込まれ、複数が同じ名前を定義する場合、Claude Code は作業ディレクトリに最も近いものを実行します。そしてプロジェクトワークフローと個人ワークフローが名前を共有する場合、プロジェクトワークフローが実行されます。

保存したワークフローに入力を渡す

保存されたワークフローは、args パラメーターを通じて入力を受け入れることができます。スクリプトはそれを args という名前のグローバルとして読み取ります。

> Run /triage-issues on issues 1024, 1025, and 1030

Claude はリストを構造化データとして渡すため、スクリプトは最初に解析することなく、args に対して配列とオブジェクトメソッドを直接呼び出すことができます。args が省略された場合、グローバルはスクリプト内で undefined です。

自然言語で書いた列挙が、スクリプト側では配列として届く——ここは地味に便利な設計です。

実行例プロンプト6種

原文は**「それぞれは Claude にそのタスク用のワークフローを作成して実行するよう依頼します。スクリプト自体は作成しません」**と断ったうえで、6つの典型形を挙げています。全部引用します。

同じ問題について多くのファイルを監査する——1つのエージェントをファイルごとにファンアウトし、その後、検出結果を収集して検証します。

> 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

多くのファイルを並列でマイグレーションする——編集が競合しないように各ファイルを分離されたコピーで変換し、各結果を検証します。

> use a workflow to migrate every component under src/components/ from styled-components to Tailwind, working on each file in its own isolated copy

すべての変更されたファイルをレビューして1つのサマリーを作成する——ファイルごとにレビュアーを実行し、その後、すべての検出結果を1つのエージェントに渡して、それらをランク付けして重複排除します。

> use a workflow to review every file changed in this PR for correctness issues, then merge the per-file findings into one ranked summary

多くのソースにわたってトピックを研究する

> use a workflow to research how our three competitors handle rate limiting: read their public docs and recent changelog entries in parallel, then compare the approaches

リストが成長を停止するまで問題を見つける——ラウンドで検索を続け、新しいラウンドが新しいものを見つけなくなったら停止します。

> use a workflow to find flaky tests in this repo: run the suite repeatedly, record which tests fail intermittently, and stop once two rounds in a row find nothing new

6つを並べると共通の型が見えます。ファンアウト → 各結果を検証 → 統合、あるいは繰り返して収束したら止める。この2つが動的ワークフローの基本形です。

生成されるスクリプトの形

通常は編集する必要はありませんが、ここは小さいものの形なので、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つのアイテムごとに1つを実行します。

手で直したい場合はClaude に変更を説明するよう依頼するか、Agent SDK リファレンスのワークフロー ツール エントリを参照します。

実行の仕組みと上限

ワークフローランタイムは、会話から分離された隔離環境でスクリプトを実行します。中間結果は Claude のコンテキストに入る代わりにスクリプト変数に留まります。

スクリプトの実体はディスクに残ります。**すべての実行は、セッションディレクトリの ~/.claude/projects/ 配下のファイルにスクリプトを書き込みます。実行が開始されると Claude はパスを受け取るため、それを尋ねることができます。**用途は3つ挙げられています。そのファイルを開いて、Claude が作成したオーケストレーションを読んだり、前回の実行のスクリプトと比較したり、編集して Claude に編集版から再起動するよう依頼したりできます。

制約は4つ。

制約	理由
実行中のユーザー入力なし	エージェントパーミッションプロンプトのみが実行を一時停止できます。ステージ間の署名のために、各ステージを独自のワークフローとして実行します
ワークフロー自体からの直接ファイルシステムまたはシェルアクセスなし	エージェントは読み取り、書き込み、コマンドを実行します。スクリプトはエージェントを調整します
最大16個の同時エージェント、CPU コアが限定されたマシンではより少ない	ローカルリソース使用を制限
実行ごとに合計1,000エージェント	暴走ループを防止

16並列・累計1,000。この2つが物理的な天井です。

一時停止と再開

ランタイムは実行が進むにつれて各エージェントの結果を追跡します。これが実行を一時停止後に再開可能にする理由です。

再開の粒度に実務上重要な性質があります。既に完了したエージェントはキャッシュされた結果を返し、残りはライブで実行されます。停止時にまだ実行中だったエージェントは保存されず、再開時に最初からやり直すため、多くの小さなエージェント全体で作業をファンアウトするワークフローは、1つの長いエージェントよりも多くの進捗を保持します。

**エージェントを細かく割ったほうが再開に強い。**設計指針として使える事実です。

操作は**/workflows から選択して p、またはClaude に同じスクリプトでワークフローを再起動するよう依頼**。ただし再開は同じ Claude Code セッション内で機能します。

コスト管理

ワークフローは多くのエージェントを生成するため、単一の実行は会話で同じタスクを処理するより意味のあるほど多くのトークンを使用できます。実行は他のセッションと同様にプランの使用量とレート制限にカウントされます。

見積もりの作法が具体的です。大規模なタスクにコミットする前に支出を見積もるには、まず小さなスライスでワークフローを実行します。リポジトリ全体ではなく1つのディレクトリ、または広い質問ではなく狭い質問です。そして完了した作業を失うことなくいつでも実行を停止できます。

自動の警告もあります。ワークフローが25個を超えるエージェントをスケジュールするか、その予想トークン合計が150万を超える場合、入力ボックスの下のタスクパネルの進捗行に Large workflow 警告が表示されます。（v2.1.203 以降）ただし警告は参考情報です。実行を一時停止または制限しません。

閾値が変わる条件が2つ。**サイズガイドラインを設定した場合、ガイドラインのエージェント数が25エージェントのしきい値に置き換わります。**ultracode がオンのセッションは警告を表示しません。ultracode をオンにすることで既に大規模な実行にオプトインしているためです。

モデルの決まり方も明記されています。ワークフロー内のすべてのエージェントは、スクリプトがステージを別のモデルにルーティングしない限り、セッションのモデルを使用します。または CLAUDE_CODE_SUBAGENT_MODEL 環境変数が設定されている場合、これは両方をオーバーライドします。対策は大規模な実行前に /model を確認することと、最強のモデルが必要ないステージ用に小さいモデルを使用するよう Claude に依頼すること。

サイズガイドライン

/config の Dynamic workflow size 設定は、Claude が作成するワークフローをデフォルトでより小さなスケールに保ちます。（v2.1.202 以降）

値	Claude に送信されるガイダンス
unrestricted	ガイドラインなし。これがデフォルトです。
small	5 未満のエージェントを目指します。
medium	15 未満のエージェントを目指します。
large	50 未満のエージェントを目指します。

性質を誤解しないよう明記されています。Claude Code は設定を Claude へのアドバイスとして送信するため、異なるスケールを要求するプロンプトはそれをオーバーライドします。そしてランタイムエージェント上限は設定に関係なく引き続き適用されます。

**ガイドラインは助言、ランタイム上限は強制。**この2層構造を混同しないことです。

無効化する

ワークフローは CLI、Desktop アプリ、IDE 拡張機能、非対話モード（claude -p）、Agent SDK で利用可能です。同じ無効化設定がすべてのサーフェスに適用されます。

自分用は3通り——/config で Dynamic workflows をオフに切り替え（セッション間で保持）／~/.claude/settings.json で "disableWorkflows": true（セッション間で保持）／CLAUDE_CODE_DISABLE_WORKFLOWS=1（起動時に読み取られるため、設定した場所に適用）。

組織全体なら管理設定で "disableWorkflows": true を設定するか、Claude Code 管理設定ページのトグルを使います（第48回のサーバー管理設定）。

4. まとめ ＋ 次回予告

• 動的ワークフローはサブエージェントを大規模に指揮する JavaScript スクリプト。v2.1.154 以降・有料プラン限定・Pro は /config で要有効化。
• 他手法との違いは計画を保持する者。ワークフローだけがスクリプトが次を決め、中間結果がスクリプト変数に留まる。だからClaude のコンテキストには最終的な答えしか入らない。
• 再利用対象も違う。サブエージェント＝ワーカー定義、スキル＝指示、エージェントチーム＝チーム定義、ワークフロー＝オーケストレーション自体。
• まず**/deep-research** を動かすのが最短。各クレームに投票し、生き残らなかったものはフィルタされる。確認できなかったクレームは未検証として列挙され、反論扱いにはならない。
• 起動方法は3つ——**ultracode キーワード／自然言語で「ワークフローを使って」／/effort ultracode でセッション全体をオプトイン。**誤爆は Option+W（Windows/Linux は Alt+W）で解除でき、/config で完全に無効化できる。
• **権限モードが制御するのは起動プロンプトだけ。****ワークフロー内のサブエージェントは常に acceptEdits で走り、ファイル編集は自動承認される。**シェル・Web フェッチ・許可リスト外の MCP だけが実行中にプロンプトを出す。
• 監視は /workflows。フェーズ／エージェント単位でドリルダウンでき、x で個別停止、r で個別再起動、p で一時停止、s で保存。
• 保存先は**.claude/workflows/（共有）か ~/.claude/workflows/（個人）。同名ならプロジェクト側が勝つ。モノレポでは作業ディレクトリに最も近いもの**が実行される。
• 入力は args で渡る。自然言語の列挙が構造化データとして届く。
• ランタイム上限は同時16エージェント・累計1,000エージェント。
• 再開は同一セッション内のみ。完了済みエージェントはキャッシュから返るが、実行中だったものはやり直し——だから細かく割ったワークフローほど再開に強い。
• コストは小さいスライスで試してから。25エージェント超／推定150万トークン超で Large workflow 警告（ただし止めはしない）。/config のサイズガイドラインは助言、ランタイム上限は強制。

これで第64回が示した並列化4アプローチ——サブエージェント／エージェントビュー／エージェントチーム／動的ワークフロー——がすべて出揃いました。

次回予告（暫定）：ワークフローの再開が「同一セッション内のみ」だったこと、第63回・第65回でも claude --resume <name> が繰り返し登場したことを踏まえ、**セッション（sessions）**を取り上げ、セッションの命名・再開・管理を扱う予定です。

---