🎭

Claude Code 実践検証 Day 17｜Subagentsオーケストレーションの基礎―並列・直列を使い分ける

に公開
AI
Windows
Claude Code
Subagents
tech

複数のファイルを同時に分析したい。でも、順番に処理しないといけないタスクもある。

Claude CodeのSubagentって、そういう「並列」と「直列」の使い分け、できるんでしょうか？

Day 15-16でSubagentの基本を押さえたので、今回は複数Subagentを協調させる「オーケストレーション」を試してみます。Windows環境で動かすところまでを整理しました。

オーケストレーションでできること

複数のSubagentを「まとめ役（Orchestrator）」が指揮して、タスクを分担させる仕組みです。

2つのパターン

パターン 説明 使いどころ
並列実行（Fan-out） 同時に複数タスクを処理 独立したファイル分析、バッチ処理
直列実行（Pipeline） 順番に処理、前段の結果を次段へ 依存関係のあるワークフロー 
並列実行:
    ┌── Subagent A ──┐
    │                │
開始 ├── Subagent B ──┼─→ 結果統合
    │                │
    └── Subagent C ──┘

直列実行:
開始 → Subagent A → Subagent B → Subagent C → 完了

公式ドキュメントではrun_in_backgroundパラメータやAgentOutputToolの使い方が説明されていますが、私の環境ではもっとシンプルに使えました。

設定方法

カスタムエージェントの配置

オーケストレーションには、カスタムエージェントを使うと便利です。

your-project/
├── .claude/
│   └── agents/
│       ├── analyzer-agent.md    ← 分析用
│       ├── collector-agent.md   ← 収集用
│       └── processor-agent.md   ← 処理用
├── CLAUDE.md
└── src/

カスタムエージェントの書き方

analyzer-agent.mdの例：

---
name: analyzer-agent
description: ファイルを分析し、統計情報を返すエージェント
---

## 役割

ファイルの内容を分析し、以下の情報を返してください。

## 出力形式

| 項目 | 値 |
|------|-----|
| 行数 | {行数} |
| 文字数 | {文字数} |
| 単語数 | {単語数} |
| ステータス | success または error |

ポイント:

  • descriptionに役割を明記しておく（参照される可能性がある）
  • 出力形式を指定すると、結果の統合がしやすい
  • 実際の呼び出しはエージェント名を明示的に指定するのが確実

正直、最初は「こんなシンプルな設定で動くの？」と思ってました。でも、これで十分動くんですよね。

動作確認

並列実行を試す

以下のプロンプトを投げてみてください。

analyzer-agentを使って、data/file-a.txt、data/file-b.txt、data/file-c.txt
の3ファイルを並列で分析し、結果を統合してサマリーを作成してください。

成功の判定

3つのエージェントが同時に起動し、このような表示になれば成功です。

● 3 analyzer-agent agents finished (ctrl+o to expand)
   ├─ Analyze file-a.txt · 1 tool use · 3.0k tokens
   │  ⎿  Done
   ├─ Analyze file-b.txt · 1 tool use · 3.0k tokens
   │  ⎿  Done
   └─ Analyze file-c.txt · 1 tool use · 3.0k tokens
      ⎿  Done

直列実行を試す

collector-agentでdata/ディレクトリのファイル一覧を収集し、
その結果をprocessor-agentに渡して処理してください。
最後にreporter-agentでレポートを作成してください。

成功の判定

順番に1つずつ実行されます。

● collector-agent(Collect files from data/)
  ⎿  Done (4 tool uses · 4.3k tokens · 23s)

● processor-agent(Process collected data)
  ⎿  Done (0 tool uses · 4.0k tokens · 13s)

● reporter-agent(Create final report)
  ⎿  Done (1 tool use · 4.5k tokens · 26s)

前段の結果が後段に渡されていることを確認してください。

注: processor-agentがツール0回なのは、役割が曖昧だったためです。詳しくはDay 18で解説します。

Windows環境で動かす前に知っておくべきこと

明日の検証編で詳しく解説しますが、先にポイントだけお伝えします。

公式ドキュメントとの差異

項目 公式の説明 実際（Windows）
並列実行の指示 run_in_backgroundを使う プロンプトで「並列で」と言うだけ
結果の取得 AgentOutputToolで取得 自動的に統合される
Windows対応 明確な記載なし Git Bashで問題なく動作

公式ドキュメントには技術的な詳細が書いてありますが、私の環境ではこれらを意識する必要はありませんでした。

ハマりやすいポイント

  • エージェント名の明示的指定: descriptionによる自動選択は未検証。agent名（今回の場合analyzer-agent）を明示的に指定するのが確実
  • 出力形式の統一: 並列実行後に統合するなら、各エージェントの出力形式を揃える
  • タイムアウト: 長時間タスクは途中で止まる可能性あり

詳しくは明日の検証編で解説します。

検証環境

項目 値
OS Windows 11 Pro
Claude Code v2.0.70
シェル Git Bash
検証日 2025-12-16

この基礎を使うと

複数ファイルの一括分析、依存関係のあるワークフローの自動化ができるようになります。「並列で」「順番に」とプロンプトで指示するだけで、Claude Codeが適切に処理してくれます。

シリーズを追いかける

12月25日まで毎日更新。フォローしておくと通知が届きます。「うちではこう動いた」などのコメントもお待ちしてます。

→ 著者ページ（Zenn）

次回：Day 18「Subagentsオーケストレーション検証―エラー分離と公式より簡単な使い方」

検証に使用したエージェント（5ファイル）

1. analyzer-agent.md（並列実行用・分析）

---
name: analyzer-agent
description: ファイル分析専門エージェント。指定されたファイルの内容を分析し、統計情報を返す。並列実行テスト用。
tools: Read, Glob
model: inherit
---

あなたはファイル分析の専門家です。

## 責務

- 指定されたファイルを読み込む
- 行数、文字数、単語数を集計する
- 分析結果を構造化して返す

## 出力形式

| 項目 | 値 |
|------|-----|
| 行数 | {行数} |
| 文字数 | {文字数} |
| 単語数 | {単語数} |
| ステータス | success または error |

2. collector-agent.md（直列実行用・収集）

---
name: collector-agent
description: データ収集専門エージェント。Pipelineの第1段階として、指定ディレクトリからファイル一覧を収集する。
tools: Glob, Read
model: inherit
---

あなたはデータ収集の専門家です。Pipelineパターンの第1段階を担当します。

## 責務

- 指定ディレクトリのファイル一覧を収集
- 各ファイルのメタ情報を取得
- 次段階（processor-agent）に渡すデータを準備

3. processor-agent.md（直列実行用・処理）

---
name: processor-agent
description: データ処理専門エージェント。Pipelineの第2段階として、収集されたデータを加工する。
tools: Read
model: inherit
---

あなたはデータ処理の専門家です。Pipelineパターンの第2段階を担当します。

## 責務

- collector-agentから受け取ったファイル一覧を処理
- 各ファイルの内容を読み込み
- データを加工・集計

4. reporter-agent.md（直列実行用・レポート）

---
name: reporter-agent
description: レポート作成専門エージェント。Pipelineの第3段階として、処理結果をレポート形式にまとめる。
tools: Read, Write
model: inherit
---

あなたはレポート作成の専門家です。Pipelineパターンの第3段階（最終段階）を担当します。

## 責務

- processor-agentから受け取った集計結果をレポート化
- 人間が読みやすい形式に整形
- 結果ファイルを出力

5. error-prone-agent.md（エラーテスト用）

---
name: error-prone-agent
description: エラーテスト用エージェント。意図的にエラーを発生させ、エラーハンドリングの検証に使用する。
tools: Read
model: inherit
---

あなたはエラーテスト用のエージェントです。

## 動作パターン

- `trigger: file_not_found` → 存在しないファイルを読もうとする
- `trigger: slow` → 長時間処理のシミュレーション
- `trigger: success` → 正常に処理を完了

Discussion