一行要約
dynamic workflow の本質は「計画を Claude の context ではなくコードに移すこと」で、そのおかげで中間結果はスクリプト変数に留まり、Claude の context には最終回答だけが残る。代償はトークンで、1 run あたり最大 1,000 エージェントまで走りうる。
要点
何が他と違うのか — 「誰が計画を保持するか」
| Subagents | Skills | Agent teams | Workflows | |
|---|---|---|---|---|
| 正体 | Claude が起こすワーカー | Claude が従う指示 | peer セッションを監督するリードエージェント | ランタイムが実行するスクリプト |
| 次に何を走らせるか決めるのは | Claude、ターンごと | Claude、プロンプトに従って | リードエージェント、ターンごと | スクリプト |
| 中間結果の置き場 | Claude の context window | Claude の context window | 共有タスクリスト | スクリプト変数 |
| 再利用できるもの | ワーカー定義 | 指示 | チーム定義 | オーケストレーション自体 |
| 規模 | 1ターンに数個 | 同上 | 少数の長時間 peer | 1 run に数十〜数百 |
| 中断されたら | ターンをやり直す | ターンをやり直す | teammate は走り続ける | 同一セッション内で再開可能 |
A workflow script holds the loop, the branching, and the intermediate results itself, so Claude’s context holds only the final answer. workflow のスクリプト自体がループ・分岐・中間結果を保持するので、Claude の context には最終的な答えだけが残る。
計画をコードに移すことのもう1つの効用は、繰り返し可能な品質パターンを適用できること。独立したエージェントに互いの発見を敵対的にレビューさせてから報告させる、複数の角度から計画を起草して互いに比較させる、といったことができる。
起動の3経路
| 経路 | やり方 |
|---|---|
| プロンプトで頼む | ultracode キーワードを含める、または「use a workflow」と自然文で書く |
| Claude に任せる | /effort ultracode を設定すると、セッション中のすべての実質的なタスクで Claude が workflow を計画する |
| 既存のコマンドを走らせる | bundled の /deep-research、または自分が保存したもの |
キーワードが効くのは「自分がタイプしたプロンプト」だけ（対話プロンプト、IDE 拡張のパネル、Remote Control、origin を { kind: "human" } と刻む Agent SDK アプリ）。次の経路では workflow を起動しない。
-pで渡したプロンプト- human と刻まずに Agent SDK が送ったプロンプト
- scheduled task のプロンプト
- webhook のペイロードや pull request のコメントが会話に中継された場合
ultracode は
xhighの reasoning effort と自動 workflow オーケストレーションを組み合わせた設定。1つのリクエストが連続した複数の workflow（理解する用、変更する用、検証する用）になりうる。セッション限りで、新セッションではリセットされる。
承認と権限（重要な落とし穴）
| permission mode | プロンプトが出るタイミング |
|---|---|
| Default / accept edits | 毎回（「この workflow は今後聞かない」を選んだ場合を除く） |
| Auto | 初回のみ。Yes を選ぶと user settings に記録される。ultracode がオンならスキップされる |
Bypass permissions / claude -p / Agent SDK | 一度も出ない。即座に走る |
Your permission mode controls only the launch prompt above. The subagents the workflow spawns always run in
acceptEditsmode and inherit your tool allowlist, regardless of your session’s mode. File edits are auto-approved. あなたの permission モードが制御するのは、上記の起動プロンプトだけである。workflow が立てる subagent は、セッションのモードによらず常にacceptEditsモードで動き、あなたのツール許可リストを引き継ぐ。ファイルの編集は自動承認される。
allowlist にないシェルコマンド・web fetch・MCP ツールは実行中に確認を求めてくることがある。長い run では事前に allowlist へ追加しておく。
スクリプトの形
保存されたスクリプトは meta ブロックとスクリプト本体からなる。本体は top-level await を使えるプレーンな JavaScript。
agent()— subagent を1つ起こすpipeline()— リストの各要素に対して1つずつ走らせる
agent() は、途中で止めた場合や回復不能な API エラーの場合に null を返す。pipeline() はその null を結果配列に残すので、.filter(Boolean) で落とすのが定型。
ランタイムの制約
| 制約 | 理由 |
|---|---|
| 実行中のユーザー入力を受け付けない | 中断できるのはエージェントの権限プロンプトのみ。段階ごとの承認が要るなら各段階を別の workflow にする |
| スクリプト自身にファイルシステム・シェルへの直接アクセスがない | 読み書きとコマンド実行はエージェントの仕事。スクリプトは統率するだけ |
モジュールをロードできない（import() を含むスクリプトは開始前に失敗する） | 本体はプレーン JavaScript。ライブラリが要る作業はエージェントのタスクに入れる |
| 同時実行は最大 16 エージェント（CPU コアが少ないマシンではより少ない） | ローカル資源の消費を抑える |
| 1 run あたり合計 1,000 エージェント | 暴走ループの防止 |
実行のされ方と再開
- ランタイムは会話とは別の隔離環境でスクリプトを実行する
- 各 run はスクリプトを
~/.claude/projects/配下のセッションディレクトリに書き出す。Claude は開始時にそのパスを受け取るので、読ませたり、前回の run と diff したり、編集して再実行させたりできる
再開のルール（2つ） — ここは直感に反する。
- 停止時にまだ走っていたエージェントは保存されない。再開時に最初からやり直す
- リプレイはエージェントの開始順に従う。 キャッシュされた結果は「最初に完了しなかったエージェント」で止まり、それより後に開始したエージェントは、完了していても全部やり直しになる
Say a script starts four agents, A, B, C, and D, in that order, and you stop the run while B is still going. On resume, A returns from cache. B runs again because it never finished. C and D run again too, because they started after B, even though both completed before you stopped. あるスクリプトが A、B、C、D の4つのエージェントをこの順で起動し、B がまだ動いている最中に実行を止めたとする。再開時、A はキャッシュから返る。B は完了していなかったので再実行される。C と D も再実行される。停止前に両方とも完了していたにもかかわらず、B より後に開始されたからである。
A workflow that fans work out across many small agents therefore preserves more progress than one long agent. したがって、作業を多数の小さなエージェントに分散させる workflow のほうが、1つの長いエージェントより進捗を多く保てる。
再開は同一セッション内でのみ機能する。 workflow の実行中に Claude Code を終了すると、次のセッションでは最初から始まる。
コスト管理
- 大きなタスクに踏み込む前に、小さなスライスで試す（リポジトリ全体ではなく1ディレクトリ、広い問いではなく狭い問い）
Large workflow警告: 25 エージェントを超えて予定される、または予測トークン合計が 150万を超えると、タスクパネルの進捗行に警告が出る。これは助言であって、run を止めたり制限したりはしない。size guideline を自分で選んでいればその値が 25 の閾値を置き換える。ultracode がオンのセッションでは警告は出ない- workflow 内の全エージェントは、スクリプトが別を指定しない限りセッションのモデルを使う。
CLAUDE_CODE_SUBAGENT_MODELはその両方を上書きする
size guideline（Claude への助言であって上限ではない）:
| 値 | Claude が目指すエージェント数 |
|---|---|
unrestricted | 指定なし。タスクに応じて Claude が決める |
small | 5 未満 |
medium | 15 未満（既定） |
large | 50 未満 |
保存と配布
/workflows で run を選んで s で保存。Tab で保存先を切り替える。
| 保存先 | 共有範囲 |
|---|---|
.claude/workflows/（プロジェクト） | リポジトリを clone した全員 |
~/.claude/workflows/（ホーム） | 全プロジェクトで使えるが自分だけ |
- 同名ならプロジェクト側が走る
- monorepo では、作業ディレクトリからリポジトリルートまでの間で既に存在する最も近い
.claude/workflows/に書かれる。読み込みもその経路上すべてから行われ、同名なら作業ディレクトリに最も近いものが走る - symlink 越しの書き込みは拒否される（プロジェクト側は
.claude/.claude/workflows/ 対象ファイルのいずれかが symlink なら拒否、個人側は対象ファイル自体が symlink のときだけ拒否） - plugin で配布する場合は plugin ルートの
workflows/に置く。plugin 名で namespace される（/acme-tools:release-audit）
引数を渡す: 保存した workflow は args パラメータで入力を受け取る。スクリプトは args というグローバルとして読む。Claude が構造化データとして渡すので、パースなしに配列・オブジェクトのメソッドを呼べる。省略時は undefined。
bundled workflow
/deep-research <question> — 問いを複数の角度から web 検索でファンアウトし、見つけた情報源を取得して相互検証し、各主張に投票して、相互検証を通らなかった主張を除いた出典付きレポートを返す。WebSearch ツールが必要。自分で呼んだときだけ走る。
v2.1.196 以降、検証エージェントがレート制限や API エラーで主張を確認できなかった場合、「反証された」ではなく「未検証」として列挙される。
進捗の見方（/workflows のキー操作）
| キー | 動作 |
|---|---|
↑ / ↓ | フェーズまたはエージェントを選択 |
Enter / → | 掘り下げる（フェーズ → エージェント → プロンプト・直近のツール呼び出し・結果） |
Esc / ← | 1階層戻る |
j / k | エージェント詳細内のスクロール |
f | 状態でフィルタ（押すたびに巡回） |
p | 一時停止 / 再開 |
x | 選択中のエージェントを停止（run にフォーカスがあれば全体を停止） |
r | 選択中の実行エージェントを再起動 |
s | run のスクリプトをコマンドとして保存 |
無効化
| 範囲 | 方法 |
|---|---|
| 自分 | /config で Dynamic workflows をオフ / ~/.claude/settings.json に "disableWorkflows": true / CLAUDE_CODE_DISABLE_WORKFLOWS=1 |
| 組織全体 | managed settings に "disableWorkflows": true、または Claude Code admin settings のトグル |
無効化すると bundled workflow コマンドが使えなくなり、ultracode キーワードも発火せず、/effort メニューから ultracode が消える。
そのまま使える具体例
保存されたスクリプトの形:
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)タスクの形ごとのプロンプト例（スクリプトは自分で書かない）:
use a workflow to audit every route handler under src/routes/ for missing authentication checks, and adversarially verify each finding before reporting ituse 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 progressuse a workflow to migrate every component under src/components/ from styled-components to Tailwind, working on each file in its own isolated copyuse a workflow to review every file changed in this PR for correctness issues, then merge the per-file findings into one ranked summaryuse 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キーワードで単発起動する:
ultracode: audit every API endpoint under src/routes/ for missing auth checksセッション全体を workflow 前提にする:
/effort ultracodeclaude --effort ultracodeサイズの指針を変える:
/config workflowSizeGuideline=small保存した workflow に引数を渡す:
Run /triage-issues on issues 1024, 1025, and 1030原典で言及されている関連文書
- a-harness-for-every-task — この機能の設計意図（agentic laziness / self-preferential bias / goal drift）
- sub-agents — workflow が統率するワーカーの本体
- features-overview — subagent / agent teams / workflow の使い分け
- multi-agent-research-system — fan-out と統合の実運用例
- building-effective-agents — orchestrator-workers パターン
未取得の派生リンク
- https://code.claude.com/docs/en/agents — 並列実行手段の比較
- https://code.claude.com/docs/en/costs — multi-agent 実行と利用上限
- https://code.claude.com/docs/en/agent-sdk/typescript — Workflow tool の全オプション
- https://code.claude.com/docs/en/permission-modes — permission mode
- https://code.claude.com/docs/en/plugins-reference#component-path-fields — plugin での配布