ワークフロー

動的ワークフロー（dynamic workflow）は、多数のサブエージェントを一度に動かす JavaScript のスクリプトです。Claude が依頼に合わせてスクリプトを書き、ランタイムがバックグラウンドで実行するので、セッションは応答したままです。

• 1つの会話では束ねきれない数のエージェントが要る作業に向く（全体のバグの洗い出し・500 ファイルの移行・複数の出典を突き合わせる調査・複数の角度から練る計画）
• 独立したエージェントに互いの結果を検証させるなど、繰り返せる品質のパターンを組み込める
• 中間の結果はスクリプトの変数に残るので、Claude のコンテキストには最終的な答えだけが入る
• 気に入った実行は、自分のコマンドとして保存して再利用できる

いつワークフローを使うか#

サブエージェント・スキル・エージェントチーム・ワークフローはどれも複数の手順の作業を動かせます。違いは、計画を誰が持つかです。

ワークフローは、計画をコードへ移します。ほかの方式では Claude が調整役で、ターンごとに次に何を起こすかを決め、すべての結果がコンテキストウィンドウに入ります。ワークフローのスクリプトは、ループ・分岐・中間の結果を自分で持ちます。独立したエージェントに互いの調査結果を反証させてから報告する、複数の角度から計画を書いて比べるなど、1回きりの実行より信頼できる結果を得る型を使えます。ほかの並列の方法との比べ方は並列作業の選び方を見てください。

同梱のワークフローを動かす#

まず /deep-research を実行すると、動きが分かります。多数の出典にわたって質問を調べる、Claude Code 同梱のワークフローです。エージェントが段階（フェーズ）を進める間、セッションは空いたままで、ターンごとの記録の代わりに、最後に1つのレポートが返ります。

1. 調べたい質問を付けて /deep-research を実行する。複数の角度から Web 検索を広げ、見つけた出典を取得して突き合わせ、出典つきのレポートにまとめる

   textコピー

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

2. ワークフローを許可するか聞かれるので「Yes」を選ぶ。プロンプトは権限モードで変わる（下の「実行前に計画を承認する」）

3. 実行はバックグラウンドで始まる。/workflows を実行し、矢印キーで実行を選び、Enter で進行の画面を開く。各フェーズのエージェント数・トークン合計・経過時間が出る。入力欄の下のタスクパネルにも1行の進行が出て、下矢印でフォーカスし Enter で展開できる

4. 終わるとレポートがセッションに出る。各主張の出典が示され、突き合わせで残らなかった主張は除かれる。検証役のエージェントがレートリミットや API エラーなどで主張を確かめられなかったときは、反証されたと数えず、未検証としてレポートに載る

自分の作業でワークフローを動かすには、Claude に書かせ（下の節）、狙いどおりになった実行を、自分のコマンドとして保存します。

同梱のワークフロー#

/deep-research は、自分で呼び出したときだけ動きます。自分で保存したワークフローも、同じようにコマンドになり、/ の補完に同梱のものといっしょに出ます。

実行を見る#

ワークフローはバックグラウンドで動くので、エージェントの作業中もセッションは応答します。/workflows で実行中・完了済みのワークフローを一覧し、選んで進行の画面を開きます。開かずに止めるには、一覧で選んで x を押します。進行の画面は、各フェーズのエージェント数・トークン合計・経過時間を示し、フッターに各操作のキーが出ます。

エージェントの詳細には、プロンプト・最近のツール呼び出し・結果が出ます。各呼び出しは、実行中・失敗などの状態を示します。エージェントが自分のタスクリストを持っていれば、各タスクの状態も出ます。Enter で展開すると、プロンプトと結果が全部出て、各呼び出しの入力と結果の頭が見られます。

Claude にワークフローを書かせる#

2つの方法があります。

• プロンプトで頼む：自分の言葉で、またはキーワード ultracode を入れて、Claude にその作業のワークフローを書かせる
• /effort ultracode を設定する：セッション内のすべての実質的な作業について、Claude がワークフローを計画する

すでにあるワークフローのコマンド（/deep-research のような同梱のもの、または保存したもの）も実行できます。

プロンプトで頼む#

セッションの effort を変えずに、1つの作業をワークフローとして動かすには、プロンプトにキーワード ultracode を入れます。「use a workflow」「run a workflow」のように自分の言葉で頼んでも、同じように選択したものとして扱われます。

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

Claude Code は入力中のキーワードを強調し、Claude は作業をターンごとに進める代わりに、ワークフローのスクリプトを書きます。キーワードが選ぶのは作業の組み立て方だけで、エージェントのツール呼び出しには、セッションのほかのツール呼び出しと同じ権限の確認とサンドボックスが適用されます。狙いどおりに動いたら、あとからコマンドとして保存できます。別の方法で作った調整役（サブエージェントのプロンプトのフォルダや、作業を広げるスキルなど）があれば、それを Claude に示して、同じことをするワークフローを頼めます。

キーワードを取り消す・切る#

意図せず始めたくないときは、macOS は Option+W、Windows と Linux は Alt+W で、このプロンプトの強調を消します。強調したキーワードの直後にカーソルがあるときに Backspace を押しても消せます。キーワードがまったく反応しないようにするには、/config で「Ultracode keyword trigger」をオフにします。

キーワードが効く場所#

キーワードが選択として働くのは、自分で入力したプロンプトだけです。対話のプロンプト・IDE 拡張のパネル・Remote Control のクライアント・キーボード入力の origin を { kind: "human" } と記す Agent SDK のアプリが該当します。次の経路でセッションに届いたときは、ワークフローを始めません。

• -p で渡したプロンプト
• 人の入力と記さずに Agent SDK のアプリが送るプロンプト
• スケジュールされたタスクのプロンプト
• 会話に中継された Webhook のペイロードや PR のコメント

ultracode で Claude に判断させる#

Ultracode は、セッションのeffortがどの水準でも、ワークフローの自動の組み立てをオンにする設定です。オンにすると、頼まなくても、Claude が実質的な作業ごとにワークフローを計画します。

/effort ultracode

• claude --effort ultracode で、最初からオンで始められる（effort は xhigh になる。v2.1.203 以降）
• /effort のスライダーでは、Tab で「Ultracode」のトグルを切り替え、Enter で適用する
• Claude が、作業がワークフローに値するかを決める。1つの依頼が、コードを理解するもの・変更するもの・検証するものと、連続した複数のワークフローになることがある
• セッション内のすべての作業に適用されるので、同じ依頼がワークフローなしより多くのトークンと時間を使う。サブスクリプションでは使用制限をそのぶん消費し、オフのときより早くセッションや週の制限に届く

オンにすることが大規模な実行への同意になるので、オンの間は次の確認が働きません。

• 実行時の Large workflow の警告が出ない
• Agent ツールで起こすサブエージェントについて、セッションの同時サブエージェントの上限が適用されない
• auto の権限モードで、最初のワークフローの起動の承認を求められない

/effort ultracode は現在のセッションだけで効きます。毎回のセッションで始めるには、ultracode の設定を使います。日常の作業に戻るときは /effort ultracode off でオフにします。/effort のスライダーにトグルが出るのは、ultracode が使えるときだけです。

実行前に計画を承認する#

CLI では、実行ごとのプロンプトに計画されたフェーズと次の選択肢が出ます。

Ctrl+G でスクリプトをエディタで開き、Tab で、実行前にプロンプトを調整できます。このプロンプトが出るかは、権限モードで決まります。

claude -p と Agent SDK では、このプロンプトは出ません。Workflow ツールの呼び出しは、セッションのほかと同じ権限の評価を通るので、deny ルール・ask ルール・dontAsk モードが、ほかのツールの呼び出しと同じく起動に適用されます。これらの実行でワークフローを始めさせるには、次のいずれかを使います。

• 権限ルール：allow ルールの Workflow はすべてのワークフローを、Workflow(<name>) は保存済みの1つを名前で承認する
• auto の権限モード：分類器が呼び出しを確認して承認できる
• bypass permissions モード：Claude Code が呼び出しを承認する
• フック：その呼び出しを許可する PreToolUse フックが承認する
• ホスト：--permission-prompt-tool か、Agent SDK なら canUseTool のコールバックが承認する

デスクトップアプリでは、ワークフロー名・フェーズの一覧・トークン使用量の注意を示す承認カードに、「Once」「Always」「Deny」の操作が出ます。進行の画面は、バックグラウンドタスクのサイドペインに出ます。ワークフローが起こすサブエージェントは、自分の権限ルールを使い、権限モードは、サブエージェントがどの権限モードで動くかの規則で決まります。長い実行でプロンプトを避けるには、始める前に、エージェントに要るツールを allow ルールに足しておきます。

再利用のために保存する#

繰り返す作業のために Claude が書いたワークフローは、その実行のスクリプトをコマンドとして保存できます。ブランチごとに行うレビューのような手順が、毎回同じ調整で動きます。/workflows を実行し、残したい実行を選んで s を押します。保存のダイアログで、Tab で2つの保存先を切り替えます。

個人用の保存先は、解決されたパスがダイアログに出ます。Enter で保存すると、どちらの保存先でも、以降のセッションで /<name> として動きます。Claude Code は、書く前に保存先のシンボリックリンクを確認し、リンクを通って書かず、エラーを出します。

• プロジェクトの保存先：.claude・.claude/workflows・対象のファイルのどれかがシンボリックリンクなら拒否する
• 個人の保存先：対象のファイル自体がシンボリックリンクのときだけ拒否する（dotfiles のツールで管理している ~/.claude も使える）

v2.1.216 より前は、リンクをたどり、選んだ場所の外にファイルを置くことがありました。.claude/ が複数あるモノレポでは、ワークフローを、適用するパッケージの隣に置けます。プロジェクトの保存先への保存は、作業ディレクトリとリポジトリのルートの間に、すでにある最も近い .claude/workflows/ に書き、なければリポジトリのルートに書きます。プロジェクトのワークフローは、その経路上のすべての .claude/workflows/ から読み込まれ、同じ名前が複数あれば、作業ディレクトリにいちばん近いものが動きます。プロジェクトと個人のワークフローが同じ名前なら、プロジェクトのものが動きます。

プラグインで配る#

チームやリポジトリをまたいで共有するには、プラグインに含めます。スクリプトをプラグインのルートの workflows/ ディレクトリに置くか、マニフェストの workflows フィールドで別の場所を指します。プラグインのワークフローは、プラグイン名の名前空間がつきます。acme-tools というプラグインの、meta.name が release-audit のスクリプトは、/acme-tools:release-audit として動きます。

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

保存したワークフローは、args のパラメーターで入力を受け取れます。スクリプトは args というグローバルとして読みます。調査の質問・対象パスの一覧・設定のオブジェクトを、実行のたびにスクリプトを編集せず、呼び出し時に渡せます。

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

Claude は一覧を構造化データとして渡すので、スクリプトは、解析せずに args の配列やオブジェクトのメソッドを直接呼べます。args を省くと、スクリプトの中でグローバルは undefined です。

プロンプトの例#

1つのエージェントの文脈に収まらない作業や、同じ手順を多くの項目に繰り返す作業に向きます。各プロンプトは、その作業のワークフローを書いて動かすよう Claude に頼むもので、スクリプトは自分で書きません。

保存されるスクリプトの形#

ワークフローを保存すると、.claude/workflows/ のファイルには、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() の呼び出しは、実行中に止めたとき、または回復できない API エラーに当たったとき、null を返す。pipeline() は null を結果の配列に残すので、例は .filter(Boolean) で落としている
• auto モードでは、スクリプトが agent() に渡すプロンプトは、分類器がそのサブエージェントの動きを確認するとき、あなたの依頼として数えられない（Claude Code が、スクリプトが計算したテキストとして印をつけるため）
• agent() に schema を渡すと、そのサブエージェントは、文章でなく、その形の JSON を返す。Claude Code は、サブエージェントを始める前にスキーマを確認し、スキーマが自己矛盾すると証明できるときは、矛盾を示すエラーで呼び出しを失敗させ、サブエージェントは始まらない（additionalProperties: false が除外する required のキーなど）
• 出力が5回試しても検証に通らなければ、最後の検証の失敗を含むエラーで呼び出しが失敗する。試行回数は MAX_STRUCTURED_OUTPUT_RETRIES で変えられる

保存したスクリプトを編集する#

保存したワークフローを変えるには、その .js ファイルを編集するか、Claude に変更を頼みます。編集や依頼の前に、/workflow-authoring の同梱スキルを実行すると、Claude が参照するスクリプトの書き方のリファレンスが読み込まれます（v2.1.248 以降）。編集した版を現在のセッションで動かすには、/reload-skills でワークフローのディレクトリを読み直し、もう一度 /<name> を実行します。Claude Code は、スクリプトを読み込んで動かすとき、ファイルの各部分に次の規則を適用します。

• meta ブロック：export const meta を最初の文のままにし、name と description を持つ素のオブジェクトリテラルにする。変数・関数呼び出し・スプレッドのようなリテラルでない値が含まれると、Claude Code は /<name> を / の補完から外す
• 本体：agent()・pipeline()・parallel() のほかに、phase()・log()、args のグローバルが使える。構文エラーがあれば、ワークフローを動かすときに報告される
• phases：meta に並べる場合は、phase() に渡す題とまったく同じにする。項目のない phase() の題は、独自の進行のグループになる
• タイムスタンプと乱数：Date.now()・Math.random()・引数なしの new Date() は、スクリプトの中で例外になる。再起動した実行が同じ agent() の呼び出しを繰り返すため。タイムスタンプは args で渡す

保存した版でなく、1回の実行のスクリプトを編集することもできます。編集したスクリプトを再起動したときに、どのエージェントがもう一度動くかは、下の「一時停止のあとの再開」の節にあります。Workflow ツールの入力は、Agent SDK のリファレンスの項目を見てください。

ワークフローが動くしくみ#

ワークフローのランタイムは、会話とは別の隔離された環境でスクリプトを実行します。中間の結果は、Claude のコンテキストではなく、スクリプトの変数に残ります。

• すべての実行は、~/.claude/projects/ の下のセッションのディレクトリに、スクリプトのファイルを書く。実行が始まるとき、Claude はそのパスを受け取るので、尋ねれば分かる。ファイルを開いて、Claude が書いた調整を読む・前の実行のスクリプトと差分を取る・編集して、編集した版からの再起動を Claude に頼める
• Claude がワークフローを始められるのは、セッションがすでに読むことを許されているスクリプトファイルからだけ。作業ディレクトリの外にあるスクリプトを動かすには、先に /add-dir でそのディレクトリを足すか、Read の allow ルールを足す
• ランタイムは、実行の進行に合わせて各エージェントの結果を記録する。これが、同じセッション内で実行を再開できる理由

ファンアウトのプロンプトキャッシュ#

同じ実行のエージェントは、互いのプロンプトキャッシュを読めます。モデル・effort・エージェントタイプ・ツール・出力スキーマ・作業ディレクトリが同じ2つのエージェントは、同じツールとシステムプロンプトの接頭辞を作るので、一致する兄弟の応答が始まってから動くエージェントは、最初のリクエストでその兄弟のキャッシュを読みます。

• ワークフローのエージェントのリクエストは、メインの会話のキャッシュ TTL の区分の外にあり、キャッシュは既定で5分保持される（Claude のサブスクリプションでも同じ）。1時間保つには subagentPromptCacheTtl を 1h にする。API は1時間のキャッシュ書き込みを、より高い料金で請求する
• ファンアウトで一致するエージェントを同時に多数始めるとき、Claude Code は最初の1つを除いて、その応答が始まるまで保留し、そのあとまとめて解放する。各エージェントが、共有の接頭辞を、キャッシュなしで処理し直さずに済む。保留の上限は CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS ミリ秒で、既定は 5000。0 にすると保留を無効にする

動作と制限#

ランタイムは次の制約を適用します。

実行を管理する#

実行が始まったら、/workflows の画面か、入力欄の下のタスクパネルの進行の行を展開して管理します。実行を止めても、そのエージェントのプロセスがまだ動いている間は、実行はタスクパネルに残ります。もう一度止めると、Claude Code はそれらのプロセスに再びシグナルを送ります。

一時停止のあとの再開#

一時停止した実行は、/workflows で選んで p を押して再開します。止めた実行は、同じスクリプトでワークフローを再起動するよう Claude に頼みます。止めた実行のエージェントがまだ終了していなければ、終わるまで再起動を拒否し、同じエージェントの2つ目のコピーが並んで動くのを防ぎます。

Claude Code は、エージェントが始まった順に実行を再生し、各エージェントは、保存された結果を返すか、もう一度動きます。

• 完了していた：保存された結果を返す。前の実行とプロンプトが異なる最初のエージェント（スクリプトを編集した、または前のエージェントが違う結果を返したため）はもう一度動き、それ以降のエージェントも、完了していたものを含めてもう一度動く
• 止めたときに動いていた：最初からやり直す。実行全体を止めても、エージェントは失敗と数えない
• 失敗した：もう一度動き、それ以降に始まったエージェントも、完了していたものを含めてもう一度動く。/workflows でエージェント1つを選んで x で止めると、失敗と数える

最後の場合は、ファンアウトの途中の失敗が、すでに終わった作業をやり直すということです。スクリプトが A・B・C・D の順に始め、B が失敗したら、再起動は A をキャッシュから返し、B・C・D をもう一度動かします。実行を再開できるのは、同じ Claude Code のセッションの中です。セッションを離れたとき、動いているワークフローがどうなるかは、離れ方で変わります。

• セッションをバックグラウンドへ移すと、Claude Code は同じ方法でバックグラウンドのセッションで実行を再生して続ける
• ワークフローが動いている間に Claude Code を終了し、エージェントビューがオンなら、終了のダイアログに「Move to background and exit」が出て、同じ方法で実行を引き継ぐ。「Exit and stop tasks」を選ぶか、この選択肢が出ないときは、セッションとともに実行が止まる。Claude Code は実行の保存された結果を ~/.claude/projects/ の下のセッションのディレクトリに残すので、claude --resume で再開したセッションで、ワークフローの再起動を Claude に頼めば、それを再生できる

クラウドセッションでは、Claude Code は実行の結果をセッションの会話履歴とともに保存するので、セッションの VM が回収されても残ります。そのようなセッションを開き直して、ワークフローの再起動を Claude に頼めば、完了したエージェントはやはり保存された結果を返します。ローカルでもクラウドでも、Claude が以前の実行を再起動するとき、Claude Code がその実行の保存された結果をまったく見つけられなければ、実行を自動でやり直さず、nothing to resume のエラーで再起動が失敗します。そのときは、新しい実行として、ワークフローを最初から始めるよう Claude に頼みます。

使用制限に当たったとき#

エージェントが claude.ai の使用制限に当たると、そのエージェントを失敗にせず、実行が一時停止します。制限に当たったエージェントはリセットを待ち、新しいエージェントは始まりません。制限がリセットされてまもなく、待っていたエージェントがもう一度動き、実行が自動で続きます（v2.1.271 以降。それより前のバージョンでは、影響を受けたエージェントは失敗する）。待っている間、タスクパネルの進行の行と /workflows のヘッダーに、制限がリセットされる時刻が出ます。実行が一時停止するのは、次のすべてが当てはまるときだけです。1つでも外れると、該当のエージェントは失敗します。

• セッションが対話で、claude.ai のサブスクリプションでサインインしている。claude -p や Agent SDK の非対話モード、バックグラウンドセッション、Remote Control やエージェントチームのチームメイトのセッションでは、実行は一時停止しない
• autoContinueAtUsageLimit がオン（セッション自身が使用制限のリセットを待つのと同じ設定）。待っている間にオフにすると、待ちが終わり、待っていたエージェントが失敗する
• 制限が24時間以内にリセットされる（週の制限は、もっと先になることがある）
• 実行がまだ2回待っていない。3回目に制限に当たると、エージェントは失敗する

コスト#

ワークフローは多数のエージェントを起こすので、1回の実行が、同じ作業を会話で進めるより、かなり多くのトークンを使うことがあります。実行は、プランの使用量とレート制限に数えられます。大きな作業を始める前に支出を測るには、まず小さな一部（リポジトリ全体でなく1つのディレクトリ、広い質問でなく狭い質問）で動かします。/workflows の画面は、実行の進行に合わせて各エージェントのトークン使用量を示し、そこでいつでも実行を止められます（たいてい、完了した作業は失われません。止めた実行が何を保つかは「一時停止のあとの再開」の節）。ランタイムのエージェントの上限は、1回の実行が起こせるエージェントの数を制限します。

Claude Code は、異常に大きくなった実行にも印をつけます。25を超えるエージェントを予定するか、見込みのトークン合計が 150 万を超えると、入力欄の下のタスクパネルの進行の行に Large workflow の警告が出ます。警告は /workflows を案内し、そこで実行を止められます。警告は助言で、実行を一時停止も制限もしません。次の2つの設定で、出るタイミングが変わります。

• 自分でサイズの目安を選ぶと、そのエージェント数が25の閾値の代わりになる。組み込みの既定の目安は、閾値を25のままにする
• ultracode がオンのセッションは警告を出さない（オンにすること自体が大規模な実行への同意だから）

Claude Code は、各ワークフローのエージェントのモデルを、サブエージェントと同じ順序で選びます。スクリプトが段階に名指ししたモデルは、その順序の「呼び出しごとのモデル」に当たります。ほかに何も決まらなければ、エージェントはセッションのモデルで動きます。モデルのコストを抑えるには：

• 日常の作業で小さなモデルに切り替える人は、大きな実行の前に /model を確かめる
• 作業を説明するとき、最も強いモデルが要らない段階には、より小さなモデルを使うよう Claude に頼む

組織の availableModels の許可リストが、スクリプトがエージェントに求めるモデルをブロックすると、そのエージェントは、サブエージェントと同じ代替の規則で代わりのモデルで動きます。/workflows の進行の画面に、求められたモデルと代替されたモデルの両方を示す警告が出ます。

サイズの目安を決める#

サイズの目安は、動的ワークフローを書くとき、Claude がいくつのエージェントを目指すかを伝えます。上限ではなく助言として Claude に送られるので、別の規模を求めるプロンプトのほうが優先されます（v2.1.202 以降）。

既定は medium です。Pro プランでサインインしていて Claude Code が v2.1.271 以降のときは small です。値を選ぶまで、/config の行はその値に既定と印をつけ、ワークフローの Running in background の行が適用中の大きさを示します（v2.1.219 以降。それより前は、既定は unrestricted）。変えるには、/config の「Dynamic workflow size」で値を選ぶか、/config workflowSizeGuideline=small を実行します。v2.1.219 以降は、どの設定ファイルでも workflowSizeGuideline キーを設定でき、その値が /config より優先され、設定ファイルが値を与えている間、Claude Code は /config の行を隠します。変更は次のプロンプトから効きます。ランタイムのエージェントの上限は、設定にかかわらず適用されます。

ワークフローをオフにする#

ワークフローは、CLI・デスクトップアプリ・IDE 拡張・claude -p の非対話モード・Agent SDK で使えます。オフにする設定は、すべての面で同じです。自分だけオフにするには：

• /config の「Dynamic workflows」をオフにする（セッションをまたいで保たれる）
• ~/.claude/settings.json に "disableWorkflows": true を設定する（セッションをまたいで保たれる）
• 環境変数 CLAUDE_CODE_DISABLE_WORKFLOWS=1 を設定する（起動時に読まれるので、設定した場所で効く）

組織全体でオフにするには、管理設定に "disableWorkflows": true を設定するか、Claude Code の管理設定のページのトグルを使います。ワークフローが無効だと、同梱のワークフローのコマンドと /workflow-authoring スキルが使えず、ultracode キーワードが実行を始めなくなり、/effort から「Ultracode」のトグルが消えます。すでに動いている実行は続きます。ワークフローをオフにすると、ultracode も使えなくなります。ultracode だけを禁止する管理設定はなく、使える場所では、ユーザーが /effort ultracode でオンにできます。effort の上限は、ultracode がオンのセッションが動く effort の水準を下げますが、ultracode をオフにはしません。