Claude Code の Dynamic Workflows：実際のコードベースで 1,000 個の subagents を動かす方法

Claude Code の dynamic workflows は、マルチエージェントのオーケストレーションの仕組みです。Claude が JavaScript のスクリプトを書き、最大 1,000 個の並列 subagents へ作業をばらまきます。途中結果はモデルのコンテキストウィンドウではなくスクリプトの変数に保持され、最終的に検証済みの答えだけがセッションに返ってきます。2026 年 5 月 28 日に Claude Opus 4.8 と同時にリリースされ、利用には CLI v2.1.154 以降が必要です。

今回は、アーキテクチャ、6 つのスクリプトプリミティブ、実際のユースケース、正直なコスト計算、そしてリサーチプレビューの最初の数週間で開発者がつまずいているポイントを見ていきます。

Claude Code の dynamic workflow とは？
Claude Code workflows の仕組み：アーキテクチャ
Claude Code workflows の実用ユースケース
Claude Code workflow のコスト・制限・効率
開発者がつまずく落とし穴と注意点
Claude Code workflows と LangGraph・Temporal などの比較
Claude Code workflows のベストプラクティス
よくある質問

Claude Code の dynamic workflow とは？

dynamic workflows が登場する前は、Claude が起動する subagent はどれも結果をメインの会話のコンテキストウィンドウに返していました。つまり 50 体のエージェントを動かすと、途中のテキストが 50 個分たまり、コンテキストが埋まって、タスクが終わる前に品質が落ちていったのです。エージェント数の上限というのは、ハードな制限というより、モデルが使える作業用メモリを使い果たすソフトな壁のようなものでした。

dynamic workflows はオーケストレーションを会話から完全に切り離すことで、この問題を解決します。Claude はあなたが指定したタスク専用の JavaScript スクリプトを書きます。そのスクリプトはバックグラウンドのランタイムで動きます。どのエージェントを、何体、どんな順番で起動し、いつ検証するか、といったオーケストレーションのロジックはスクリプトの変数の中に存在します。モデルのコンテキストウィンドウが受け取るのは、最終的に統合された結果だけです。

workflow スクリプトで使える 6 つのプリミティブ：

agent(prompt, opts?) — 単一の subagent を起動し、最終テキストまたは検証済み JSON を返す
parallel(thunks) — タスクの配列を同期バリア付きで並列実行する
pipeline(items, ...stages) — アイテムをステージ間にバリアなしで流す
workflow(nameOrRef, args?) — 保存済みの workflow をサブステップとして呼び出す（ネストは最大 1 レベル）
phase(title) — /workflows モニタリングダッシュボードでの進捗グループに名前をつける
log(msg) — workflow の出力にナレーター行を出す

ここでの「dynamic」には特定の意味があります。タスクの分解、エージェント数、フェーズ分けの戦略、検証の方法を、あなたが説明した個別のタスクに合わせて Claude がリアルタイムで決めるのです。同じ workflow スクリプトは二つとありません。これは、一度定義したら静的にスケジュールされるプロンプトである Routines とも違いますし、/loop セッションで使われていた古い ScheduleWakeup プリミティブとも違います。

有効な workflow スクリプトの最小構成はこんな感じです：

export const meta = {
  name: 'security-audit',
  description: 'Parallel security scan across auth, DB, and input layers',
  whenToUse: 'When you need a full security sweep before shipping',
  phases: [
    { title: 'Scan', detail: 'Three specialized agents run in parallel' },
    { title: 'Synthesize', detail: 'One agent compiles a prioritized report' },
  ]
}

phase('Scan')
const [auth, db, input] = await parallel([
  () => agent('Audit authentication flows for bypass vulnerabilities', { label: 'auth-scanner' }),
  () => agent('Check all database queries for injection risks', { label: 'db-scanner' }),
  () => agent('Review input validation and sanitization', { label: 'input-scanner' }),
])

phase('Synthesize')
const report = await agent(
  `Compile a prioritized security report from these three findings:\n\nAuth: ${auth}\n\nDB: ${db}\n\nInput: ${input}`,
  { label: 'synthesizer' }
)

return report

Claude Code workflows の仕組み：アーキテクチャ

workflow を起動すると、次の順番で物事が進みます。

ステップ 1：プランニング。 Claude があなたのリクエストを分析し、JavaScript のオーケストレーションスクリプトを書きます。このスクリプトには、どんなフェーズがあるか、各フェーズで何体のエージェントが動くか、アイテムを並列で流すかパイプラインで流すか、結果を返す前にどんな検証ロジックを走らせるか、がエンコードされています。

ステップ 2：承認。 meta.phases 配列から計画されたフェーズが表示されます。そのまま実行する、このプロジェクトでは信頼済みにして以後確認しないようにする、Ctrl+G で生の JS スクリプトを開いて中身を確認する、キャンセルする、のいずれかを選べます。

ステップ 3：実行。 workflow ランタイムがスクリプトをバックグラウンドプロセスで実行します。実際のファイル読み込み、シェルコマンド、Web の取得、MCP ツールの呼び出しは subagents がやります。各 agent() 呼び出しは、結果を JavaScript の値として返します（文字列、または schema を渡した場合は検証済み JSON）。これらの値は Claude のコンテキストではなく、スクリプトの変数にたまっていきます。

ステップ 4：検証。 Claude が生成する workflow のほとんどには検証フェーズが含まれていて、メインフェーズの結論を別のエージェントが反証したり挑んだりします。結果が収束するまで workflow は反復します。

ステップ 5：デリバリー。 スクリプトの戻り値、つまり最終的に統合された答えがあなたのセッションに届きます。Claude のコンテキストウィンドウに触れるのはこれだけです。

レジュームとキャッシュ。 ランタイムは完了した agent() 呼び出しの結果をすべてジャーナルに記録します。/workflows ダッシュボードで p キーを押して workflow を一時停止すると、再開時に完了済みエージェントはキャッシュ結果を即座に返します。これが効くのは同じ Claude Code セッション内だけです。アプリを終了するとジャーナルは破棄され、次のセッションは最初からやり直しになります。

プロンプトキャッシュとコストへの影響。 Anthropic のプロンプトキャッシュは、デフォルトで TTL が 5 分です。前回の呼び出しから 300 秒を超えて発火した agent() 呼び出しは、キャッシュを完全にミスし、キャッシュ読み込みの 12.5 倍のコストで全部書き直しになります。フェーズ間のギャップが 5 分を超える workflow では、初期セットアップ時に cache_control: { type: 'ephemeral', ttl: '1h' } を指定して 1 時間 TTL への延長を明示的に要求してください。これはキャッシュ書き込み価格の 2 倍かかりますが、長い workflow を劇的に安くしてくれます。

/workflows モニタリングダッシュボード（/workflows と打つと開きます）は、フェーズ、稼働中のエージェント数、トークン合計、経過時間を表示します。操作方法は次のとおりです。Up/Down でフェーズやエージェントを選択、p で一時停止または再開、x でエージェント 1 体または workflow 全体を停止、r で選択したエージェントを再起動、s で実行を再利用可能なコマンドとして保存します。

Claude Code workflows の実用ユースケース

1. 大きな PR を横断する並列コードレビュー。 変更されたファイルをバッチに分割し、バッチごとに 1 体のエージェントを動かしてロジック・型・セキュリティ・テストをチェックし、その結論を優先度つきのレビューに統合します。あるパターンでは、1 回のコードレビューに 90 体のエージェントを起動して月のトークン上限に達した開発者がいました。これはパターンが機能している証拠であると同時に、予算のガードレールが必要だということでもあります。

2. 大規模なマイグレーションや書き換え。 代表例は Jarred Sumner の Bun プロジェクトです。約 75 万行の Zig を 11 日で Rust に移植し、既存テストスイートの 99.8% が初回コミットからマージまでパスしました。パターンは、600 行のマッピングドキュメント（あらゆる Zig の型とイディオムを Rust の同等物に翻訳したもの）に加え、重複しないファイル集合を処理する並列エージェントを worktree で隔離し、衝突せずに書き込めるようにするというものです。

3. 敵対的クロスチェック付きのセキュリティ監査。 オーケストレーターが 3 体の専門スキャナ（認証フロー、データベースクエリ、入力検証）を並列に起動し、その後で別の検証エージェントが各結論の偽陽性を見つけようとしてから、優先度つきレポートをまとめます。組み込みの敵対的検証フェーズがあるからこそ、このパターンはリリース前監査に使えるほど信頼できるものになっています。

4. 複数ソースのリサーチハーネス。 組み込みの /deep-research コマンド自体がファンアウトパターンを示す workflow です。9 体のエージェントが異なるソースを同時にスクレイプし、途中の結論をランクづけした候補へと集約し、1 体の統合エージェントが最終レポートをまとめます。同じパターンは、競合分析、依存関係の監査、モノレポ全体にわたる changelog の要約にも使えます。

5. 大規模なテスト生成。 コードベースのすべてのモジュールにファンアウトし、モジュールごとに 1 体のエージェントが公開 API 面に対するテストを書き、その後の収束フェーズでカバレッジの重複をチェックし、重複を取り除いてから最終的なテストファイルを書き込みます。agent() の isolation: 'worktree' オプションが、並列エージェントによるファイル衝突を防ぎます。

Claude Code workflow のコスト・制限・効率

ハードな制限（ランタイムが強制するもので、交渉の余地なし）：

制約	値	理由
同時実行エージェントの最大数	16（低 CPU マシンではそれ以下）	ローカルの CPU・メモリ使用量を抑える
1 回の実行あたりの総エージェント数の最大	1,000	暴走ループを防ぐ
workflow のネストの深さ	1 レベル	子は親のカウンタを共有する

トークン料金（従量課金）：

Claude Opus 4.8：入力 100 万トークンあたり $5、出力 $25
Claude Sonnet 4.6：入力 100 万トークンあたり $3、出力 $15
キャッシュ読み込み：入力価格の約 10%。キャッシュ書き込み：入力価格の約 25%（正しく動いている場合）。

実際の workflow でのコスト計算。 Sonnet 4.6 のエージェント 3 体を、それぞれ入力 8,000 トークン・出力 2,000 トークンで動かす並列セキュリティ監査のコストは、おおよそ次のようになります：(3 × 8,000 × $3/M) + (3 × 2,000 × $15/M) = $0.072 + $0.090 = $0.162。これを Opus 4.8 に変えると、同じ実行が $0.42 になります。大規模なコードベースのレビューでこうしたエージェントを 90 体、Opus の料金で動かすと、オーバーヘッドを含める前の出力トークンだけで $12.60 に達します。開発者が 1 セッションで月の上限を使い切ってしまう理由がここにあります。

workflow がコスト効率的なときと無駄なとき：

効率的：

並列化でウォールクロック時間が短縮されるタスク（結果を速く得たくて、コストは二の次のとき）
逐次実行だと何日もかかる大規模マイグレーション
サブタスクの境界が明確で、実行中にエージェント間の依存がないタスク

無駄：

単一ファイルのちょっとした編集（普通の会話のほうが速くて安い）
リアルタイムの操舵や実行中の指示が必要なタスク（workflow は無人で走る）
探索的・曖昧なリクエストで、分解の戦略がわからないもの

5 分のキャッシュの崖。 workflow のフェーズが 300 秒以上離れていると、後ろのフェーズのエージェントは安いキャッシュ読み込みではなく、フルのキャッシュ書き込みコストを払うことになります。Opus のオーケストレーターを使った 50 体のエージェント実行では、よくキャッシュされた実行に比べてコストが 3〜6 倍に膨らむことがあります。これを避けるには、初期コンテキストで 1 時間 TTL のフラグを渡してください。

予算を意識したループ。 workflow スクリプト内のグローバル変数 budget は、起動時に設定されたトークンの目標値を公開します。予算に敏感なループは必ずガードしてください：if (budget.total && tokensUsed > budget.total * 0.8) break。ガードがないと、ループは 1,000 エージェントのハードキャップまで走ります。

開発者がつまずく落とし穴と注意点

workflow スクリプトは TypeScript ではなく JavaScript です。 ランタイムには TypeScript のトランスパイル層がありません。workflow スクリプトに型注釈を加えるとパースエラーになります。型つきのオーケストレーションが欲しいなら、実行時に workflow を呼ぶ TypeScript のラッパーを書いてください。スクリプト本体に型を入れてはいけません。

3 つの非決定的な組み込み関数は workflow スクリプト内で例外を投げます。 Date.now()、Math.random()、引数なしの new Date() は禁止です。理由は、レジュームキャッシュがすべての agent() 呼び出しを決定的なキーでジャーナルに記録するからです。非決定的な値は再実行のたびに異なるキーを生み、レジュームを壊してしまいます。回避策はこうです。タイムスタンプは起動時に args 経由で渡し、プロンプトはランダム値ではなくループのインデックスで変化させます。

スクリプトからファイルシステムやシェルへ直接アクセスはできません。 オーケストレーション層はファイルを読んだりコマンドを実行したりできません。すべての I/O は subagents 経由です。スクリプトは純粋な協調レイヤーなのです。

parallel() と pipeline() の混同。 parallel() は同期バリアです。すべての thunk が終わるのを待ってから返します。pipeline() にはバリアがありません。アイテム A がステージ 3 にいる間に、アイテム B はまだステージ 1 にいられます。独立したアイテム処理なら pipeline() をデフォルトにしてください。parallel() を使うのは、下流のステージが先行する結果すべてを一度に必要とするとき（重複除去、クロスランキング、集合全体への敵対的レビュー）だけです。parallel() 内で失敗した thunk は reject ではなく null に解決されるので、結果配列は必ず .filter(Boolean) してください。

acceptEdits モードはファイル変更を自動で適用します。 workflow 内で動く subagents はデフォルトで acceptEdits モードで動作します。ファイル編集は個別の確認プロンプトなしに適用されます。数百のファイルに触れる 50 体のエージェント実行では、未レビューの変更が大量に入るということです。本番ブランチで実行する前に、生成された workflow スクリプトを（承認プロンプトで Ctrl+G を押して）レビューしてください。

dynamic workflows を使わないほうがいいとき：

実行中に操舵したり調整したりする必要があるタスク
次のステップが今見たものに依存する、探索的なデバッグ
10 分未満で集中した単一の応答が必要なタスク
実行ごとの予算ガードレールがない、コストに敏感な環境

.github/workflows/ のプッシュスコープのバグ。 subagent が .github/workflows/ 配下のファイルを編集すると、ローカルでは編集が成功しますが、プッシュ時に失敗します。Claude Code の OAuth 認証情報に workflow スコープがないからです。このエラーはセッションの予算をすべて使い切った後に表面化します。承認する前に、workflow スクリプトに .github/workflows/ への書き込みがないか確認してください。

Claude Code workflows と LangGraph・Temporal などの比較

これらのツールはスタックの異なる層を占めていて、互いに交換できるものではありません。問うべきは、自分がどの層を解決しようとしているのかです。

シナリオ	最適なツール
コードの記述・デバッグ・リファクタリング	Claude Code（会話モード）
分解方法が未知の大規模コードベースタスク	Claude Code Dynamic Workflows
繰り返し行う専門的なコーディングタスク	Claude Code Subagents
条件分岐を伴う複雑でステートフルなアプリの workflow	LangGraph
クラッシュに耐える必要がある本番エージェント	Temporal + 任意のエージェント SDK
人間の承認ゲートがある長時間実行の workflow	Temporal
金銭が絡む、または不可逆な複数ステップの処理	Temporal
役割分担が明確なコンテンツパイプライン	CrewAI
構造化データに対する SaaS 連携	n8n

Claude Code と LangGraph。 これらは競合ではありません。Claude Code は開発時のツールです。LangGraph は本番で動くステートフルな workflow のためのランタイムアプリケーションフレームワークです。LangGraph アプリケーションを作るのに Claude Code を使ってください。重要な制約は、Claude Code が Anthropic の Claude モデルに固定されている点です。LangGraph は LangChain 連携を通じてモデル非依存です。

Claude Code と Temporal。 Temporal は、あらゆる実行（Claude 駆動のエージェントを含む）をクラッシュに強い耐久性で包みます。Claude Code にはセッションをまたぐ状態の永続化も、厳密に 1 回だけの実行保証も、監査可能な実行履歴もありません。エージェントが金銭、法的記録、あるいは不可逆な処理に触れるなら、Temporal はスタックに入れるべきです。

本番 AI エージェントのための補完的なアーキテクチャ： Claude Agent SDK が AI の推論とツール利用のループを担い、Temporal がそれを包んで耐障害性を持たせます。OpenAI Codex も Replit Agent 3 も、どちらもこの分担を選びました。

Claude Code workflows のベストプラクティス

parallel() ではなく pipeline() をデフォルトに。 pipeline() はアイテム N が最初のステージを終えた瞬間にアイテム N+1 の処理を始めるので、アイドルのギャップがなくなります。parallel() に手を伸ばすのは、あるステージが本当に先行する結果すべてを一度に必要とするときだけにしてください。

エージェント結果をパースする必要があるときは常に schema を使う。 JSON Schema を agent() に渡すと、subagent は構造化出力のツール呼び出しに強制され、不一致時には自動でリトライされます。これにより、壊れやすいテキストパースをオーケストレーションのロジックから取り除けます。

長い workflow には 1 時間のキャッシュ TTL を設定する。 フェーズが数分以上離れている実行では、デフォルトの 5 分キャッシュ TTL は必要以上に 3〜6 倍のコストを生みます。1 時間 TTL のフラグは書き込み価格の 2 倍かかりますが、マルチフェーズの実行では読み込みでそれ以上を節約できます。

予算に敏感なループはガードする。 収束するまで回るループは、反復の前に必ず budget.total をチェックしてください：if (budget.total && estimatedTokensUsed > budget.total * 0.8) { log('approaching budget, stopping early'); break }。これがないと、ループは 1,000 エージェントのキャップまで走ります。

phase() と log() を惜しまず使う。 /workflows ダッシュボードでフェーズやナレーター行にきちんとラベルがついていれば、おかしな方向に進んでいる実行を終わる前に一時停止できます。フェーズのラベルがない workflow は、終わるまで中身の見えないブラックボックスです。

isolation: 'worktree' はエージェントが本当に同じファイルに書き込むときだけ使う。 worktree の隔離はエージェントごとに別の git worktree を生成します。これは並列でファイルに書き込むタスクには正しいのですが、読み取り専用のエージェントには不要なオーバーヘッドを加えます。

うまくいった workflow は保存する。 完了した実行で /workflows ダッシュボードの s を押し、.claude/workflows/（プロジェクト共有）または ~/.claude/workflows/（個人）に保存してください。一度保存した workflow は、同じパターンの今後の実行すべてで使える /command になります。

よくある質問

Claude Code は並列で何体のエージェントを動かせますか？

Claude Code の dynamic workflows は、同時に実行されるエージェントを 16 体に制限しています。1 回の実行全体での総エージェント数は 1,000 体が上限です。これらの制限は、サブスクリプションのプランに関係なく workflow ランタイムが強制します。CPU コアが限られたマシンでは、同時実行の上限はもっと低くなることがあります。

Claude Code の dynamic workflow はどうやって起動しますか？

方法は 3 つあります。プロンプトのどこかに「workflow」という単語を入れる（Claude Code がそのキーワードをハイライトしてオーケストレーションスクリプトを書きます）、/deep-research コマンドを実行する、または /effort ultracode を設定する（セッション内のすべての実質的なタスクについて自動で workflow を計画します）。機能をグローバルに無効化せず、単一のプロンプトだけキーワードトリガーを抑えたいときは alt+w を押してください。

dynamic workflow は無料プランや Pro プランで使えますか？

dynamic workflows は Pro（$20/月）ではデフォルトでオフで、/config から手動で有効にする必要があります。Max（$100/月と $200/月のティア）と Team プランではデフォルトでオンです。Enterprise プランではデフォルトでオフで、管理者による有効化が必要です。すべてのプランで CLI v2.1.154 以降が必要です。

エージェントの workflow において Claude Code は Cursor とどう違いますか？

Claude Code はターミナルネイティブなエージェント型ツールで、コードベース全体にわたる長時間・マルチエージェントのオーケストレーション向けに設計されています。hooks、MCP 連携、skills、dynamic workflows を備え、コマンドラインから、ファイルシステムとシェルへのフルアクセスのもとで完結します。Cursor は IDE 統合型で、VS Code 内での素早い単一ファイル編集に最適化されています。IDE での日々のコード編集なら、操作性で Cursor が勝ちます。リポジトリ全体のマイグレーション、セキュリティ監査、マルチエージェントのビルドなら、Claude Code の workflow システムに Cursor で直接相当するものはありません。

Claude Code の dynamic workflows は実際にどんなタスクに使われてきましたか？

最もよく挙げられる例は Bun の Zig から Rust への書き換えです。約 75 万行を 11 日で移植し、Linux x64 でテストスイート 99.8% パスを達成しました（PR #30412、2026 年 5 月 14 日マージ）。Rakuten は並列の Claude Code セッションを使い、機能のデリバリーを 24 営業日から 5 日に短縮しました。Uber は約 5,000 人のエンジニアにわたって Claude Code の採用率 84% に達し、2026 年 3 月時点でコミットされたコードの約 70% が AI 由来でした。

まとめ

Claude Code の dynamic workflows は、オーケストレーションをモデルのコンテキストウィンドウから JavaScript のランタイムへ移します。これこそが、品質を落とさずに 500 体・1,000 体のエージェント実行を成立させる構造的な変化です。プリミティブは小さく、組み合わせやすいものです。コストは現実的で、ガードレールが必要です。落とし穴（JS 限定のスクリプト、禁止された非決定的な組み込み関数、acceptEdits の自動適用、5 分のキャッシュの崖）は、いったん知ってしまえば回避できるくらい具体的です。

まずは範囲を絞ったユースケースから始めましょう。並列コードレビュー、モジュール境界をまたぐドキュメントの一掃、あるいは十分に範囲を限定した面でのセキュリティ監査です。その実行をコマンドとして保存します。スクリプトを改良します。確実に動く workflow は、初日にコードベース全体のタスクに撃ち込んだものではなく、何回かの実行をかけて磨き上げたものです。

Posted by @speedy_devv