Claude コード 動的ワークフロー：Opus 4.8で数百の並列サブエージェントを実行

Claude Opus 4.8には、Claude Codeの目玉機能としてDynamic Workflowsが搭載されました。1つのセッションで、オーケストレーションエージェントが何百もの並列サブエージェントを起動し、数十のファイルにわたるリファクタリング、広範なテストマトリックスの実行、複数のソリューションパスの同時探索といった大規模で分岐の多いタスクに対処できます。ターミナル上では魔法のように見えますが、実体は2つの機能を組み合わせたオーケストレーションパターンです。

今すぐApidogを試す

このガイドでは、Dynamic Workflowsがどのように動くのか、どの場面で使うべきか、そして生のAPIで同じパターンをどう実装するかを解説します。モデル自体については「Claude Opus 4.8とは」を参照してください。エージェントアーキテクチャの背景は「Claude Codeエージェントハーネスの詳細」で説明しています。

Dynamic Workflowsの正体

Claude Codeでは、Dynamic Workflowsは努力レベルメニューの「ultracode」として表示されます。

ただし、ultracodeは新しいAPI上の努力レベルではありません。実際には、Opus 4.8にある次の2つを組み合わせたものです。

1. xhigh努力レベル
2. 会話中のシステムメッセージ

この組み合わせにより、オーケストレーターエージェントは次の2つを得ます。

• 大規模なジョブを分解するための十分な推論深度
• 実行中にワーカーエージェントを起動するための許可

つまり、Dynamic Workflowsのコアは「深く計画するオーケストレーター」と「途中でワーカーを増やせる会話制御」です。

要素1：xhigh努力レベル

effortパラメータは、Opus 4.8が応答全体にどれだけのトークンを使うかを制御します。これにはツール呼び出しも含まれます。

xhighは、Anthropicが長時間のコーディング作業やエージェント的なタスクに推奨する努力レベルです。数百万単位のトークン予算で、30分を超える実行にも対応するよう調整されています。

Dynamic Workflowsでは、オーケストレーターが次の処理を行うため、深い推論が重要です。

• タスクを独立した作業単位に分割する
• 起動するワーカー数を決める
• ワーカーごとのスコープを定義する
• 結果を集約してマージする

努力レベルが低いと、作業範囲が狭くなり、ツール呼び出しも少なくなります。これは、広範な分岐タスクを扱うオーケストレーターには不向きです。

実装時は、xhighと合わせて大きめのmax_tokensを設定します。64Kは妥当な開始点です。

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=64000,
    output_config={"effort": "xhigh"},
    thinking={"type": "adaptive"},
    messages=[
        {
            "role": "user",
            "content": "Plan a refactor of the auth module across all 14 services."
        }
    ],
)

要素2：会話中のシステムメッセージ

もう1つの重要な要素が、Messages APIの会話中システムメッセージです。

Opus 4.8より前は、システムプロンプトは会話の開始時に置かれ、固定されていました。現在は、messages配列の途中にシステムエントリを配置し、タスク実行中に新しい指示や許可を挿入できます。

この仕組みにより、オーケストレーターは会話開始後に次のような権限を得られます。

• サブタスクを作成する
• ワーカーを起動する
• ワーカーごとにスコープを渡す
• 途中で発見した情報に基づいて実行方針を更新する

Anthropicはこの機能を「会話中のシステムメッセージ」として文書化しています。API変更としては小さいですが、実行中のエージェントに新しい能力や許可を追加できるため、オーケストレーション設計では大きな意味を持ちます。

Claude CodeでDynamic Workflowsを有効にする

Claude Codeでは、努力レベルメニューから「ultracode」を選択します。

これにより、内部的には次の状態になります。

• xhigh努力レベルが使用される
• 会話中のシステムメッセージを通じて並列サブエージェント生成が許可される
• オーケストレーターが大きなタスクを分割して実行できる

使い方はシンプルです。

1. Claude Codeで努力レベルを「ultracode」に設定する
2. 大規模で分割可能なタスクを渡す
3. オーケストレーターに計画、分割、実行、統合を任せる
4. 生成された差分や結果をレビューする

実行中は、次の処理が自動で行われます。

• Claudeがタスクを計画する
• 作業単位ごとにワーカーを起動する
• ワーカー結果がメインセッションに戻る
• オーケストレーターが結果を統合する

Claude Codeをプラン付きでセットアップしている場合は、「Claudeプランセットアップガイド付きClaudeエージェントSDK」も参考になります。

Dynamic Workflowsを使うべきケース

Dynamic Workflowsは、広範で並列化しやすいタスクに向いています。

代表例は次のとおりです。

• 複数ファイルにまたがるパターン置換やリファクタリング
• 大規模なテストマトリックスの生成と実行
• 複数の実装案を並行して探索し、比較する作業
• 各ワーカーが1モジュールを担当するコードベース分析
• サービスごとの変更影響調査
• APIエンドポイント群の仕様確認やテストケース生成

たとえば、14個のサービスにまたがる認証処理のリファクタリングなら、次のように分割できます。

オーケストレーター:
  - 全体の変更方針を決める
  - サービスごとにワーカーを割り当てる
  - 返ってきた変更案を比較する
  - 最終的な統合方針を作る

ワーカー:
  - service-a の認証処理を調査
  - service-b の認証処理を調査
  - service-c の認証処理を調査
  ...

このように、作業単位が独立しているほどDynamic Workflowsの効果が出ます。

Dynamic Workflowsを避けるべきケース

一方で、次のようなタスクには向いていません。

• 1ファイルだけの小さな修正
• 前のステップの結果が次のステップに強く依存する作業
• 並列化できない逐次的なデバッグ
• 仕様が曖昧で、まず人間の判断が必要な作業

1ファイルの軽微な変更に何百ものサブエージェントを使うと、メリットよりトークン消費のほうが大きくなります。

判断基準は次のとおりです。

使うべき:
  - 作業を独立した単位に分けられる
  - 複数の探索パスを同時に試したい
  - 対象ファイルやモジュールが多い

避けるべき:
  - 作業が小さい
  - 実行順序が厳密に決まっている
  - ワーカーを増やしても情報量が増えない

APIで同じオーケストレーションを構築する

Dynamic Workflowsのようなオーケストレーションは、Claude Codeなしでも実装できます。

必要なのは、同じ2つの要素です。

1. xhigh努力レベル
2. 会話中のシステムメッセージ

Anthropicは「オーケストレーションモードを構築する」で実例を公開しています。

基本的な流れは次のとおりです。

1. オーケストレーター呼び出しをxhighで実行する
2. タスク分解結果を受け取る
3. 会話中のシステムメッセージでワーカー起動を許可する
4. 各ワーカー呼び出しを並列に実行する
5. ワーカー結果を収集する
6. オーケストレーターに戻してマージさせる

1. オーケストレーターで計画する

import anthropic

client = anthropic.Anthropic()

orchestrator = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=64000,
    output_config={"effort": "xhigh"},
    thinking={"type": "adaptive"},
    messages=[
        {
            "role": "user",
            "content": "Plan a refactor of the auth module across all 14 services."
        },
    ],
)

2. ワーカー単位に分割する

実装では、オーケストレーターに構造化された分割結果を返させると扱いやすくなります。

{
  "tasks": [
    {
      "id": "service-auth-a",
      "scope": "Analyze auth module in service-a",
      "files": ["services/a/auth/*"]
    },
    {
      "id": "service-auth-b",
      "scope": "Analyze auth module in service-b",
      "files": ["services/b/auth/*"]
    }
  ]
}

3. ワーカーを並列実行する

各ワーカーは、1つの作業単位だけを担当する独立したMessages呼び出しにします。ワーカー側は必ずしもxhighである必要はありません。狭いタスクならmediumやlowを検討します。

from concurrent.futures import ThreadPoolExecutor

def run_worker(task):
    return client.messages.create(
        model="claude-opus-4-8",
        max_tokens=8000,
        output_config={"effort": "medium"},
        messages=[
            {
                "role": "user",
                "content": f"""
You are a worker agent.

Task ID: {task["id"]}
Scope: {task["scope"]}
Files: {task["files"]}

Return:
- findings
- proposed changes
- risks
"""
            }
        ],
    )

tasks = [
    {
        "id": "service-auth-a",
        "scope": "Analyze auth module in service-a",
        "files": ["services/a/auth/*"],
    },
    {
        "id": "service-auth-b",
        "scope": "Analyze auth module in service-b",
        "files": ["services/b/auth/*"],
    },
]

with ThreadPoolExecutor(max_workers=8) as executor:
    worker_results = list(executor.map(run_worker, tasks))

4. 結果をオーケストレーターに戻す

最後に、ワーカー結果をまとめてオーケストレーターに渡し、統合方針を作らせます。

merge = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=32000,
    output_config={"effort": "xhigh"},
    messages=[
        {
            "role": "user",
            "content": f"""
Merge these worker results into a single refactor plan.

Worker results:
{worker_results}

Return:
- final plan
- ordered implementation steps
- risks
- validation checklist
"""
        }
    ],
)

Anthropicのホスト型エージェントインフラと比較したい場合は、「マネージドエージェント vs エージェントSDK」でトレードオフを確認できます。

コストと制御

並列サブエージェントは、トークン消費を急速に増やします。

たとえば、200のワーカーを起動し、それぞれがxhighで数万トークンを使うと、合計は簡単に数百万トークンになります。Dynamic Workflowsを運用する場合は、コスト制御を設計に含めるべきです。

実践的には、次の3つを徹底します。

• ワーカーのスコープを狭くする

  • 1ワーカーに複数の責務を持たせない
  • 「1サービス」「1モジュール」「1テスト領域」などで区切る

• ワーカーごとのmax_tokensを制限する

  • 暴走したワーカーが予算を使い切らないようにする
  • 広い分析には大きめ、単純な確認には小さめに設定する

• 可能な限り低いeffortを使う

  • オーケストレーターはxhigh
  • 狭いワーカーはmediumまたはlow
  • 最終マージだけ再度xhighにする、など役割で分ける

また、繰り返し使うシステムプロンプトや共有コンテキストはキャッシュを検討してください。すべてのワーカーで同じ長文コンテキストを送ると、コストが膨らみます。

料金の考え方は「Opus 4.8の料金内訳」で詳しく説明されています。

Apidogでオーケストレーションをテストする

APIでオーケストレーションを構築する場合、難しいのはファンアウト部分のデバッグです。

確認すべき点は次のとおりです。

• ワーカーに正しいスコープが渡っているか
• ワーカーの応答形式がマージ処理と合っているか
• 会話中のシステムメッセージが意図どおり届いているか
• 失敗したワーカーを再実行できるか
• 一部のワーカー結果が欠けてもマージできるか

200回のライブワーカー呼び出しを実行した後に、ペイロード形式のミスを見つけるのは避けたいところです。

Apidogを使うと、各要素を個別に検証できます。

• オーケストレーターのリクエストを保存し、タスク分解結果を確認する
• ワーカーエンドポイントをモックし、実際のトークン消費なしでファンアウトをテストする
• ワーカー応答にアサーションを追加し、形式のズレを検出する
• 単一ワーカー呼び出しを異なるeffortレベルでリプレイする
• ライブエンドポイントへ切り替える前に、マージロジックを検証する

基本的な検証フローは次のようになります。

1. Apidogで /v1/messages へのオーケストレーターリクエストを作る
2. タスク分解レスポンスの形を確認する
3. ワーカー用モックを作る
4. ファンアウト処理からモックを呼び出す
5. ワーカー応答形式にアサーションを設定する
6. マージ処理を検証する
7. 問題がなければライブAPIへ切り替える

まずはhttps://api.anthropic.com/v1/messagesに対して、オーケストレーターとワーカーのリクエストを個別に作成します。基本リクエストは「Opus 4.8 APIガイド」を参照してください。

モック上でファンアウトとマージが安定してから、ライブエンドポイントに切り替えるのが安全です。

よくある質問

Claude CodeにおけるDynamic Workflowsとは何ですか？

1つのセッションで何百もの並列サブエージェントを起動し、大規模で分岐の多いタスクを処理できる機能です。Opus 4.8のxhigh努力レベルと会話中のシステムメッセージによって実現されます。

ultracodeは独立した努力レベルですか？

いいえ。ultracodeは、xhigh努力レベルとマルチエージェントワークフローを起動するための常時許可を組み合わせたClaude Code上の名称です。APIの努力レベルは引き続きlow、medium、high、xhigh、maxです。

会話中のシステムメッセージとは何ですか？

Messages APIで、会話の途中にシステムエントリを配置できる機能です。タスク実行中に新しい指示や許可を挿入できるため、オーケストレーターは実行開始後にワーカーを生成できます。

Claude CodeなしでDynamic Workflowsを構築できますか？

はい。生のMessages APIでxhigh努力レベルと会話中のシステムメッセージを使えば、同じオーケストレーションパターンを実装できます。

Dynamic Workflowsは高価ですか？

高価になる可能性があります。何百ものxhighサブエージェントは、数百万トークンを消費し得ます。ワーカーのスコープを狭くし、可能な限り努力レベルを下げ、共有コンテキストをキャッシュして支出を管理してください。

Dynamic Workflowsを避けるべき時はいつですか？

狭い範囲のタスクや、厳密に逐次的なタスクでは避けるべきです。各ステップが前のステップに依存している場合、並列ワーカーは価値を追加せず、小さなジョブではトークンを無駄にします。