# ダイナミックワークフロー（Dynamic Workflows）

サブエージェントを使えば、すでに「分身を 1 つ送り出して」あることを並行調査できます。しかし、タスクが「チーム丸ごと」を要するほど大きくなると — たとえばリポジトリ全体を一巡してモジュールごとにレビューを書く、といった場合 — サブエージェント 1 つでは足りません。そこで登場するのが **ダイナミックワークフロー（Dynamic Workflows）** です。

ダイナミックワークフローは、Claude Code に **数十〜数百のバックグラウンドサブエージェント** を一気にオーケストレーションさせ、それぞれが作業の一部を担って並行実行する一方で、あなたは自分の作業を続けられます。これは Claude Code に現在設定されているモデル上で動作します — つまり Claude Code を QCode に向けておけば、ワークフローはそのまま使えます。

## どんな問題を解決するか

通常のサブエージェントは「少数で制御可能な」並行処理に向いています。3 つほどの分身を送り出して、API・スキーマ・テストカバレッジをそれぞれ調べる、といった具合です。しかし、本質的に並行度が高いタスクもあります。

- 200 ファイルあるリポジトリで **ファイルごとのセキュリティ／品質レビュー** を行う
- 古い API 呼び出しを **コードベース全体で新しい書き方へ一括移行** する
- 1 つのテーマについて、数十のディレクトリを **個別に調査して集約** する

直列でやればあなたは Claude が 1 つずつ片付けるのを待つことになり、サブエージェントを手動で数十個立ち上げれば、タスク分割も進捗管理も自分でやることになります。ダイナミックワークフローは「分割 → 配分 → バックグラウンド実行 → 集約」という一連の流れを丸ごと Claude Code 自身にオーケストレーションさせます。

## トリガー方法

ダイナミックワークフローに追加インストールは不要で、トリガーは軽量です。

- プロンプトにキーワード **`ultracode`** を含める。または
- 単に **「ワークフローを実行して（run a workflow）」** と頼む。

Claude Code が意図を認識すると、何個のバックグラウンドサブエージェントを送り出し、それぞれが何を担当するかを自分で計画し、並行実行を開始します。

```
> ultracode src/ 配下の各サブモジュールをコードレビューして。エラーハンドリングと
> 入力検証を重点的に。各モジュールは短いレポートを出力し、最後に 1 つの概観へ
> まとめて。
```

あるいは自然言語で:

```
> ワークフローを実行して: リポジトリ全体で旧 httpClient を呼び出している箇所を
> すべて探し、新しい fetch ラッパーへ移行する変更量を見積もり、ディレクトリ別に
> 集約して。
```

## /workflows で実行状況を確認する

ワークフローが送り出したサブエージェントは **バックグラウンドで動き続け**、メインセッションをブロックしません — 別の質問をしたり、コードを書き続けたりできます。現在どのワークフローが走っていて、どこまで進んでいるかを確認するには次を使います。

```
/workflows
```

実行中および完了したワークフローの実行（runs）が一覧表示され、全体の進捗を追ったり、各サブエージェントの成果物を確認したりしやすくなります。

> バックグラウンド実行とは、大きなタスクがもう操作をブロックしないということです。指示を投げたら別のことをして、後から `/workflows` で結果を回収しましょう。

## ワークフローを使うか、単一のサブエージェントを使うか

両者は同じ「並行委譲」の考え方を異なる規模で表したものであり、選択基準はシンプルです。**並行度と、バックグラウンド化が必要かどうかを見ます。**

| 観点 | 単一のサブエージェント | ダイナミックワークフロー |
|------|----------------------|------------------------|
| 並行規模 | 少数（数個）の独立サブタスク | 数十〜数百のサブタスク |
| トリガー | Claude に「X を調べるサブエージェントを 1 つ送って」と頼む | キーワード `ultracode` または「ワークフローを実行」 |
| 実行場所 | 完了後にメインセッションへ要約を返す | バックグラウンドで動き続け、メインセッションをブロックしない |
| 確認方法 | 結果は会話内に返る | `/workflows` で実行の一覧を見る |
| 典型的な用途 | API／スキーマ／テストの並行チェック | リポジトリ全体のレビュー／一括移行／大規模調査 |

経験則:

- サブタスクが **数個だけ** で、すぐ結果が欲しい → [サブエージェント](/docs/advanced/subagents) を使う。
- サブタスクが **数十〜数百** あり、バックグラウンドでじっくり走らせてよい → ダイナミックワークフローを使う。

> ダイナミックワークフローは本質的にサブエージェントの「スケールアップ版」です。まず [サブエージェント](/docs/advanced/subagents) の概念をしっかり押さえてからワークフローに進むとスムーズです。

## QCode 経由で使う

ダイナミックワークフローは **Claude Code が接続しているモデル** 上で動作し、特定のプロバイダーに依存しません。つまり Claude Code を QCode に向けておけば、ワークフローが送り出すすべてのバックグラウンドサブエージェントは QCode のエンドポイントを通り — `cr_` で始まる同じ API キーが最後まで共通で使えます。

最小構成（Anthropic プロトコル）:

```bash
export ANTHROPIC_BASE_URL="https://api.qcode.cc/api"
export ANTHROPIC_AUTH_TOKEN="cr_あなたのキー"

# 中国国内のユーザーは asia エンドポイントを優先
# export ANTHROPIC_BASE_URL="https://asia.qcode.cc/api"
```

> `BASE_URL` の末尾に **スラッシュを付けないでください**。そのアドレスへ直接アクセスして `401` が返るのは正常です — パスは正しく、認証が欠けているだけという意味です。

設定が済んだら、いつも通り Claude Code を起動し、`ultracode` でワークフローをトリガーします。エンドポイントの全リファレンス、4 つのドメイン（api / asia / us / eu）、各プロトコルのパスについては [接続先と API フォーマット](/docs/getting-started/endpoints-and-api-paths) を参照してください。

ワークフロー内の各バックグラウンドサブエージェントが消費するトークンは、QCode で選んだモデルに応じて課金されます。大規模なワークフローは多数のサブエージェントを同時に走らせるため、トークン消費もそれに応じて増えます — 大きな実行の前には、フラッグシップモデル（例: `claude-opus-5`、100 万トークンあたり $5/$25、1M コンテキスト）で小さな範囲のパイロットを回し、出力品質を確認してから全面展開するとよいでしょう。

## 実践例

### 例 1: リポジトリ全体のコードレビュー

リポジトリ内の主要モジュールごとにレビューを 1 件ずつ生成させ、観点と出力を統一し、最後に集約します。

```
> ultracode packages/ 配下の各サブパッケージを独立してコードレビューして。
> 各レビューは次を網羅: エラーハンドリング、境界条件、未処理の Promise の有無、
> 命名の一貫性。各サブパッケージは 20 行以内の要点リストを出力し、最後に
> 深刻度順に並べた 1 つのマスター表へまとめて。
```

送り出したら別のことを続けてよく、後で `/workflows` で進捗を確認し、すべてのサブエージェントが終わったら集約表をまとめて確認します。

### 例 2: 大規模な API 移行の調査

手を付ける前に、ワークフローで影響範囲を把握します。

```
> ワークフローを実行して: コードベース全体で axios を直接使っている箇所を
> すべて見つけ、ディレクトリ別にグループ化し、プロジェクト内 httpClient
> ラッパーへの切り替えの工数とリスクを見積もり、「ディレクトリ / 出現回数 /
> 移行難易度 / 注意点」の表を出力して。
```

全体像が得られれば、勘ではなく実データに基づいて移行順序を決められます。

## ヒントと注意点

- **小さく始めて拡大する**: 初回はワークフローの範囲を 1 つのディレクトリまたはパッケージに絞り、出力フォーマットと品質が期待どおりか確認してから、リポジトリ全体へ広げます。
- **出力フォーマットを統一する**: 各サブエージェントが「何を、どれくらいの長さで、どう並べて出力するか」をプロンプトで明示すると、集約時にかなり楽になります。
- **バックグラウンド ≠ 放置**: ワークフローが走っている間は別のことをしてよいですが、後で `/workflows` で締めくくる（確認する）のを忘れずに。
- **画像について**: ダイナミックワークフローはテキスト／コードのタスクを扱います。Claude Code に **画像を読ませたい**（スクリーンショット、アーキテクチャ図、エラー画面）場合、それはビジョン入力機能でワークフローとは無関係です。**画像を生成したい** 場合は [gpt-image-2 画像生成](/docs/usage/image-2) を使ってください。
- ワークフローを CI／スクリプトに組み込むには、ヘッドレスモードと構造化出力を組み合わせます — [自動化と CI/CD](/docs/advanced/headless) を参照。

> フラッグシップモデルで大規模ワークフローを回しつつコストも気になりますか？ [QCode の料金](https://qcode.cc/pricing) をご覧ください — 1 つの API キーですべてのエンドポイントを使えます。