dispatching-parallel-agents

並列エージェントのディスパッチ

概要

複数の無関係な障害（異なるテストファイル、異なるサブシステム、異なるバグ）が発生したとき、それらを順番に調査すると時間が無駄になります。各調査は独立しており、並行して進められます。

基本原則： 独立した問題領域ごとにエージェントを1つディスパッチします。エージェントには並行して作業してもらいます。

このスキルを使う場面

次のような状況でこのスキルを有効にします。

• 3つ以上のテストファイルが失敗し、根本原因がそれぞれ異なる
• 複数のサブシステムがそれぞれ独立して壊れている
• 各問題が自己完結している――ほかの問題のコンテキストがなくても理解できる
• 調査間に共有状態がない
• 領域の境界が明確である――1つを修正してもほかに影響しない

次の場合は使わないでください。

• 障害が関連している（1つを修正するとほかも直る可能性がある）
• 最初にシステム全体の状態を把握する必要がある
• エージェント同士が干渉する（同じファイルを編集する）
• 探索的なデバッグ（何が壊れているかまだ分からない）

絶対原則

One agent, one problem domain, one clear outcome.
Never overlap scopes. Never share state. Always integrate consciously.

基本原則

独立性が重要

問題は真に独立している必要があります。ファイルの共有、関連する根本原因、修正間の依存関係があってはいけません。

広さより焦点

各エージェントの範囲を絞ります。テストファイル1つ、サブシステム1つ、明確な目標1つにします。タスクの範囲が広いと混乱につながります。

明確な報告を必須にする

各エージェントは、判明したこと、修正したこと、変更内容の要約を必ず返す必要があります。報告のない修正は認めません。

慎重に統合する

エージェントの作業を無批判にマージしないでください。要約を確認し、競合をチェックし、テストスイート全体を実行して、互換性を検証します。

クイックスタート

1. 独立した領域を特定する

何が壊れているかを基に障害をグループ化します。

File A tests: Tool approval flow
File B tests: Batch completion behavior
File C tests: Abort functionality

各領域は独立しています。ツールの承認機能を修正しても、中断テストには影響しません。

2. 範囲を絞ったエージェントタスクを作成する

各エージェントに次を指定します。

• 具体的な範囲： テストファイルまたはサブシステムを1つ
• 明確な目標： これらのテストをパスさせる
• 制約： ほかのコードは変更しない
• 期待する出力： 判明したことと修正したことの要約

→ プロンプトのテンプレートと例については、agent-prompts.md を参照してください。

3. 並行してディスパッチする

// In Claude Code / AI environment
Task("Fix agent-tool-abort.test.ts failures")
Task("Fix batch-completion-behavior.test.ts failures")
Task("Fix tool-approval-race-conditions.test.ts failures")
// All three run concurrently

→ ディスパッチ戦略については、coordination-patterns.md を参照してください。

4. 確認して統合する

エージェントから結果が返ってきたら：

• 各要約を読み、何が変更されたかを把握します
• 修正が競合しないことを確認します。同じファイルが編集されていないかチェックします
• テストスイート全体を実行し、互換性を確保します
• 変更内容を抜き取り確認します。エージェントが体系的な誤りを犯すこともあります

→ 競合の解決については、troubleshooting.md を参照してください。

判断ツリー

Multiple failures?
  └→ Are they independent?
      ├→ NO (related) → Single agent investigates all
      └→ YES → Can they work in parallel?
          ├→ NO (shared state) → Sequential agents
          └→ YES → Parallel dispatch ✓

主なメリット

1. 並列化 - 複数の調査を同時に進められます
2. 集中 - 各エージェントの範囲が狭く、追跡すべきコンテキストが少なくなります
3. 独立性 - エージェント同士が干渉しません
4. 速度 - N個の問題を、1個の問題にかかる時間で解決できます

ナビゲーション

パターンのリファレンス

• 調整パターン - ディスパッチ戦略、領域の特定、統合ワークフロー

エージェント管理

• エージェントのプロンプト - プロンプトの構成、テンプレート、よくある間違い、制約

学習リソース

• 例 - 実際のシナリオ、ケーススタディ、時間短縮の分析

問題解決

• トラブルシューティング - 競合の解決、検証戦略、よくある落とし穴

関連スキル

並列エージェントをディスパッチする際は、次の補完的なスキルも検討してください（スキルライブラリで利用できます）。

• pm-workflow: PM の調整とタスク管理 - 複数のエージェントの作業を効果的に管理します
• test-driven-development: 並列修正に役立つ TDD パターン - 並列化する前にテストの失敗を理解します
• verification-before-completion: 統合の検証 - 並列エージェントの作業が正しく統合されることを確認します

主な注意事項

1. 独立性は必須です - 関連する失敗は、単一のエージェントで調査する必要があります
2. 広さより焦点を重視します - エージェントごとに範囲を絞ることで、混乱を防げます
3. 必ず統合を検証します - エージェントの作業を盲目的にマージしないでください
4. 明確な出力が必要です - 各エージェントは変更の概要を必ず返します
5. 並列化にはオーバーヘッドがあります - 独立した問題が3件以上ある場合にのみ有効です

要注意事項 - 中止

次の場合は直ちに中止してください：

• エージェントが同じファイルを編集している（範囲が重複している）
• あるエージェントの修正が別のエージェントの作業を壊している（隠れた依存関係がある）
• 問題の領域を明確に分離できない（独立していない）
• エージェントが概要を返さない（変更を検証できない）
• 統合に大規模なリファクタリングが必要である（競合がある）

判断に迷った場合： まず1つのエージェントから始め、全体像を把握してから、本当に独立している場合にタスクを割り当ててください。

他のスキルとの連携

前提条件： 問題領域とテスト構成に関する基本的な理解 補完関係： 複数のエージェントを調整するPM-Workflowスキル（スキルライブラリを参照） ドメイン固有： テストの失敗を理解するためのテストスキル（スキルライブラリで利用可能）

実環境での効果

デバッグセッション（2025-10-03）より：

• 6件の失敗が3つのテストファイルにわたって発生
• 3つのエージェントを並列で割り当て
• すべての調査を同時に完了
• エージェント間の競合はゼロ
• 短縮できた時間： 3つの問題を逐次ではなく並列で解決

→ 詳細なケーススタディについては、examples.mdを参照