🔬

Claude Code 実践検証 Day 18｜Subagentsオーケストレーション検証―公式より簡単、エラーも分離される

に公開
AI
Windows
Claude Code
Subagents
tech

昨日の基礎編で並列・直列の動かし方を試しました。でも、気になることがあったんですよね。

「エラーが出たら、他のSubagentも止まるのか？」
「公式ドキュメントのrun_in_backgroundって、本当に必要なのか？」

結論から言うと、公式ドキュメントより実際の使い方はずっとシンプルでした。しかも、1つのSubagentがエラーになっても、他は影響を受けずに完了します。

正直、最初は公式ドキュメントの技術的な説明を見て「難しそう」と思ってましたが、実際に動かしてみたら拍子抜けするほど簡単だったんですよね。

検証結果まとめ

検証項目 結果 補足
並列実行 ○ 「並列で」と言うだけで自動化
直列実行（Pipeline） ○ 「順番に」で依存関係を維持
エラー分離 ○ 他Subagentに影響しない
Windows環境 ○ Git Bashで問題なし

予想外だったのはエラー分離ですね。GitHub Issueで「1つ失敗すると全体が止まる」という報告があったので心配してましたが、今回の検証では発生しませんでした。

検証環境

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

検証1：並列実行の実態

公式ドキュメントにはrun_in_backgroundパラメータやAgentOutputToolの説明がありますが、実際に必要なのか試してみました。

やったこと

analyzer-agentを使って、data/file-a.txt、data/file-b.txt、data/file-c.txt
の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

3つのSubagentが同時に起動し、それぞれ完了。結果は自動的に統合されてサマリーが作成されました。

わかったこと

run_in_backgroundもAgentOutputToolも、私の環境では意識する必要はありませんでした。「並列で」と自然言語で指示するだけで、Claude Codeが適切に並列化してくれました。

公式ドキュメントではこれらを「実験的機能」として説明していますが、プロンプト指示だけで動いたのは嬉しい誤算でしたね。

検証2：直列実行（Pipeline Pattern）

依存関係のあるタスクを順番に処理できるか確認しました。

やったこと

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

結果

● 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)

collector → processor → reporter の順で実行され、前段の結果が後段に渡されていました。

わかったこと

注目すべきはprocessor-agentがツール使用0回だった点。これはprocessor-agentの役割がプロンプトから明確でなく、具体的なツール呼び出しが不要だったためと考えられます。直列実行を試す際は、各エージェントに何をさせるか明確に指示した方がよさそうですね。

総処理時間は62秒。並列実行より時間がかかりますが、依存関係があるタスクでは仕方ないですね。

検証3：エラーハンドリング

これが一番気になっていたポイント。1つのSubagentがエラーになったとき、他のSubagentはどうなるか。

やったこと

以下の3つのタスクを並列で実行してください:
1. analyzer-agentでdata/file-a.txtを分析
2. error-prone-agentを trigger: file_not_found で実行
3. analyzer-agentでdata/file-c.txtを分析

結果

Agent 結果 詳細
analyzer-agent #1 ✅ success file-a.txt分析完了
error-prone-agent ❌ error File does not exist: nonexistent-file-12345.txt
analyzer-agent #2 ✅ success file-c.txt分析完了

わかったこと

正直に告白すると、ここは予想と違いました。GitHub Issue #9905で「単一エラーで全体停止」という報告があったので、2つのanalyzer-agentも止まるかと思ってたんですよね。

でも実際は、エラーが発生したSubagentだけが失敗し、他のSubagentは独立して完了しました。これは実務で使う上で重要なポイントですね。「部分成功」が許容されるタスクなら、積極的に並列化できます。

公式ドキュメントとの比較

項目 公式の説明 実際の動作 差異
並列実行の指示 run_in_backgroundを使う プロンプトで「並列で」と言うだけ 大きな差異
結果の取得 AgentOutputToolで取得 自動的に統合される 大きな差異
エラー伝播 明確な記載なし 他Subagentに影響しない 公式に補足がない
結果の受け渡し 明確な記載なし prompt経由で自動引き継ぎ 公式に補足がない
Windows対応 明確な記載なし Git Bashで問題なく動作 公式に補足がない

私の環境では、公式ドキュメントで説明されている技術的な詳細を意識せずに使えました。ただし、環境やバージョンによって異なる可能性はあります。

実務での推奨パターン

検証結果を踏まえて、実務で使えるパターンをまとめます。

推奨する使い方

並列実行したいとき:
「〇〇を並列で分析してください」

直列実行したいとき:
「〇〇を収集し、その結果を△△に渡して、最後に□□してください」

シンプルですね。技術的なAPIを意識する必要はありません。

避けた方がいいこと

  • 全成功が必須なタスクで結果チェックなし: エラーは伝播しないので、明示的に結果を確認する必要あり
  • 同一ファイルへの並列書き込み: 未検証だが競合リスクが高い
  • 10以上の大規模並列: 上限未検証、キューイングの可能性

まとめ

  1. 並列実行は「並列で」と言うだけ - run_in_backgroundは意識不要
  2. エラーは他Subagentに伝播しない - 部分成功が可能
  3. Windows環境でも問題なし - 公式に記載ないが動作確認済み

同じところで悩んでる人の参考になれば。特にエラーハンドリングは、公式に明記されていないので検証してよかったですね。

この検証結果を使うと

複数ファイルの一括分析や、依存関係のあるワークフローの自動化が自信を持って使えるようになります。エラーが出ても全体が止まらないので、「とりあえず並列で投げて、失敗したものだけ後で対処」というパターンも可能です。

シリーズを追いかける

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

→ 著者ページ（Zenn）

Discussion