動的ワークフローで大規模にサブエージェントをオーケストレーションする

​

ワークフローを使用するタイミング

​

バンドルされたワークフローを実行する

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

/workflows

​

バンドルされたワークフロー

​

実行を監視する

​

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

• プロンプトでワークフローをリクエストする。自分の言葉で、またはキーワード ultracode を含めることで、Claude がそのタスク用のワークフローを書きます。
• ultracode で Claude に決めさせる。/effort ultracode を設定すると、Claude がセッション内のすべての実質的なタスク用にワークフローを計画します。

​

プロンプトでワークフローをリクエストする

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

​

キーワードを無視するか、オフにする

​

キーワードが機能する場所

• -p で渡されたプロンプト
• Agent SDK ア���リケーションが人間の入力としてスタンプせずに送信するプロンプト
• スケジュールされたタスクプロンプト
• ウェブフック ペイロードまたはプルリクエストコメントが会話にリレーされた場合

​

ultracode で Claude に決めさせる

/effort ultracode

• Large workflow 警告はワークフロー実行に表示されません
• セッションの同時サブエージェント制限は、Claude が Agent ツールで生成するサブエージェントに対して強制されません
• 自動権限モード では、ワークフロー起動を承認するよう求められません

​

実行前にプランを承認する

• Yes, run it: 実行を開始する
• Yes, and don’t ask again for <name> in <path>: 開始し、このプロジェクトでこのワークフローに対してこのプロンプトをスキップします。Claude Code は、現在のタスク用に Claude が書いたスクリプトではなく、バンドルされた、保存された、またはプラグインワークフローを名前で実行する場合にこのオプションを提供します。
• View raw script: 決定する前にスクリプトを読む
• No: キャンセル

• 権限ルール: すべてのワークフローを承認するには許可ルールに Workflow を追加し、名前で 1 つの保存されたワークフローを承認するには Workflow(<name>) を追加します。
• auto 権限モード: auto モードで実行します。auto モードでは分類器が呼び出しをレビューし、それを承認できます。
• バイパス権限モード: バイパス権限モードで実行します。
• フック: PreToolUse フックから呼び出しに対して "allow" を返します。plan モードでは、フックの承認だけではワークフローは開始されないため、代わりに権限ルールまたはホストの承認を使用します。
• ホスト: --permission-prompt-tool、または Agent SDK では canUseTool コールバックがそれを承認します。

​

再利用するためにワークフローを保存する

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

• プロジェクト場所: .claude、.claude/workflows、またはターゲットファイルがシンボリックリンクの場合、Claude Code は拒否します。
• 個人用の場所: Claude Code はターゲットファイル自体がシンボリックリンクの場合のみ拒否するため、ドットファイルツールで管理される ~/.claude ディレクトリは引き続き機能します。

​

プラグインでワークフローを配布する

​

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

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

​

ワークフローの実行例プロンプト

​

同じ問題について多くのファイルを監査する

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 JavaScript to TypeScript, working on each file in its own isolated copy

​

すべての変更されたファイルをレビューして 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

​

保存されたスクリプトの外観

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)

​

保存されたスクリプトを編集する

• meta ブロック: export const meta を最初のステートメントとして保持し、name と description を持つプレーン オブジェクト リテラルとして保持します。変数、関数呼び出し、スプレッドなどのリテラル値以外のものが含まれている場合、Claude Code は / オートコンプリートから /<name> を削除します。
• 本体: agent()、pipeline()、parallel() の他に、phase() を呼び出して、進捗ビューのタイトルの下に続くエージェントをグループ化し、log() を呼び出してフェーズの上にメッセージを表示し、args グローバルを読み取ることができます。本体に構文エラーがある場合、Claude Code はワークフローを実行するときにそれを報告します。
• phases: meta にそれらをリストする場合、phase() に渡す各エントリに正確にタイトルを付けます。エントリのない phase() タイトルは独自の進捗グループを取得します。
• タイムスタンプとランダム性: Claude Code はスクリプト内で Date.now()、Math.random()、および引数なしの new Date() をスローするため、再開された実行は同じ agent() 呼び出しを繰り返します。代わりに args を通じてタイムスタンプを渡します。

​

ワークフローの実行方法

​

ファンアウトでのプロンプトキャッシング

​

動作と制限

​

実行を管理する

​

一時停止後に再開する

​

どのエージェントが再実行されるか

• 完了済み: 保存された結果を返します。スクリプトを編集した、または前のエージェントが異なる結果を返したために、前回の実行とプロンプトが異なる最初のエージェントは再実行され、それ以降のすべてのエージェントも、完了済みのものを含めて再実行されます。 v2.1.305 より前では、pipeline() の各項目や parallel() の各タスクがそれぞれ複数のエージェントを実行するスクリプトを編集せずに再起動した場合にも、完了済みのエージェントが再実行されることがありました。新しい実行でこうした再実行を防ぐには、Claude Code を更新してください。
• 停止時にまだ実行中だったもの: 最初からやり直します。実行全体を停止しても、どのエージェントも失敗とは見なされません。
• 失敗したもの: 再実行され、スクリプトがその後に開始するすべてのエージェントも、完了済みのものを含めて再実行されます。/workflows でエージェントを選択して x を押し、1 つのエージェントだけを停止した場合は、失敗として扱われます。

​

セッションを離れた後に再開する

• セッションをバックグラウンドに移した、または Move to background and exit を選択した場合: バックグラウンドセッションを確認した時点で実行が続行していなければ、そのセッションでワークフローの再起動を Claude に依頼します。権限モードによっては、Claude Code はまず再起動の承認を求めます。セッションがエージェントビューの Needs input の下に表示されている場合は、セッションにアタッチして承認プロンプトに応答してください。
• バックグラウンドセッションでの再起動が nothing to resume で失敗した場合: ワークフローを新しい実行として最初から開始するよう Claude に依頼します。作業ディレクトリ内のスクリプトなど、~/.claude/projects/ の外にあるスクリプトファイルのパスから Claude が実行を開始した場合、Claude はバックグラウンドセッションでその実行を再起動できません。
• Exit and stop tasks を選択した場合、または Move to background and exit が表示されなかった場合: 実行はセッションとともに停止し、Claude Code は実行の保存済み結果を ~/.claude/projects/ 内のそのセッションのディレクトリに保持します。シェルで claude --resume を使ってセッションを再開し、ワークフローの再起動を Claude に依頼してください。新しく開始したセッションでは、Claude には再起動する以前の実行がないため、ワークフローを最初から開始します。

​

実行が使用制限に達した場合

• セッションが対話型で、claude.ai サブスクリプションでサインインしていること。claude -p による非対話モードや Agent SDK、バックグラウンドセッション、Remote Control やエージェントチームのチームメイトセッションでは、実行は一時停止しません。
• autoContinueAtUsageLimit がオンであること。これは、セッション自体が使用制限のリセットを待つようにするのと同じ設定です。待機中にオフにすると、待機が終了し、待機中のエージェントは失敗します。
• 制限が 24 時間以内にリセットされること。週単位の制限はそれより先にリセットされる場合があります。
• 実行がまだ 2 回待機していないこと。3 回目に制限に達すると、エージェントは失敗します。

​

エージェントが停滞して再起動する場合

• agent stalled on all 6 attempts: すべての試行がウィンドウ全体にわたって出力なしでした。エージェントの作業がそれほど長く出力を生まない場合は、ウィンドウを延長してください
• agent lost its reply on all 6 attempts: すべての試行で応答ストリームが途絶え、Claude Code がその待機を断念しました。ストリーミングアイドルウォッチドッグが先に応答を終了させており、そのウォッチドッグのタイムアウトは CLAUDE_STREAM_IDLE_TIMEOUT_MS で設定されるため、停滞ウィンドウを延長しても効果はありません
• agent abandoned after 6 attempts: 試行がそれぞれ異なる形で終了しました。エラーにはそれらが順に列挙されます

• 1 つのエージェント: その agent() 呼び出しでミリ秒単位の stallMs を渡します。たとえば 30 分なら agent(prompt, { stallMs: 1800000 }) とします
• すべてのエージェント: CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS を設定します。これはワークフロー外のサブエージェントにも適用されます

• parallel() または pipeline() 内: エージェントの結果の代わりに null を使って実行が続行します
• 直接 await した場合: 実行はエラーで終了します

​

コスト

• サイズガイドラインを自分で選択した場合、そのエージェント数が 25 エージェントのしきい値に置き換わります。組み込みのデフォルトガイドラインでは、しきい値は 25 のままです。
• ultracode がオンのセッションでは、警告は表示されません。ultracode をオンにした時点で、大規模な実行をすでに許可しているためです。

• 日常的な作業で普段は小さいモデルに切り替えている場合は、大規模な実行の前に /model を確認します
• タスクを説明する際に、最も強力なモデルを必要としないステージには小さいモデルを使うよう Claude に依頼します

​

サイズガイドラインを設定する

​

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

• /config で Dynamic workflows をオフに切り替えます。セッションをまたいで保持されます。
• ~/.claude/settings.json で "disableWorkflows": true を設定します。セッションをまたいで保持されます。
• CLAUDE_CODE_DISABLE_WORKFLOWS=1 を設定します。起動時に読み込まれるため、設定した場所で適用されます。

• /workflows、ワークフローコマンド、/workflow-authoring スキルは利用できません
• ultracode キーワードで実行がトリガーされなくなり、/effort から Ultracode トグルが削除されます

​

関連リソース

• エージェントを並列実行：サブエージェント、エージェントビュー、エージェントチーム、ワークフローを比較
• カスタムサブエージェントを作成：ワークフローがオーケストレーションするワーカープリミティブ
• コストを管理：マルチエージェント実行が使用制限にカウントされる方法