dispatching-parallel-agents

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

概要

このスキルは、独立したサブタスクに同時に取り組む複数のエージェントを調整し、正確性を保ちながら全体の実行時間を短縮します。安全に並列化できる機会を特定するための厳格なルール、焦点を絞ったエージェントプロンプトの作成方法、競合を避けながら結果を統合する方法を定めています。重要な制約として、同じファイルを変更してはならないエージェントが2つ以上存在してはいけません。

開始時に次のように宣言します。「並列エージェントのディスパッチスキルを使用して、独立した[N]個のタスクを同時に実行します。」

エージェントツールのリファレンス

すべてのディスパッチでAgentツールを使用します。パラメーター：

• prompt（必須）— 十分なコンテキストを含むタスクの説明
• description（必須）— 短いラベル（3〜5語）
• subagent_type — "Explore"（コードベースの検索）、"Plan"（アーキテクチャ）、"general-purpose"（デフォルト）
• run_in_background — 非同期の場合はtrue（完了時に通知されます）
• model — オプションの上書き値："sonnet"、"opus"、"haiku"

並列： 1つのメッセージ内で複数のAgent呼び出しを行うと、同時に実行されます。 バックグラウンド： ブロックせずに作業する場合はrun_in_background=trueにします。 名前付きエージェント： subagent_typeを使用して、インストール済みのエージェントテンプレート（例："superpowers:code-reviewer"）を指定します。

トリガー条件

• タスクを、相互にデータ依存関係のない2つ以上のサブタスクに分割できる
• 各サブタスクが、異なるファイルまたはコードベースの異なるセクションを扱う
• すべてのエージェントの完了後に結果を統合できる
• 逐次実行に比べて、並列実行で合計所要時間を大幅に短縮できる
• /decomposeの出力から、独立したタスク群が明らかになる

---

フェーズ1：独立性の検証

目標： サブタスクが真に独立しており、安全に並列化できることを確認します。

すべてのサブタスクは、次の4つの独立性基準をすべて満たす必要があります。

基準	質問	いいえの場合
ファイルの共有なし	2つ以上のエージェントが同じファイルに書き込みますか？	それらのタスクを逐次実行します
可変状態の共有なし	あるエージェントが、別のエージェントの副作用に依存しますか？	依存するタスクを逐次実行します
自己完結したコンテキスト	各エージェントは、自身に与えられた入力だけで作業できますか？	コンテキストを追加するか、逐次実行します
独立した検証	各エージェントの出力を単独で検証できますか？	1つのタスクにまとめます

並列化の判断表

シナリオ	並列化する？	理由
異なるファイル、異なる関心事	はい	競合が発生しません
同じモジュール内の異なるファイル	はい（注意が必要）	共有インポートに変更がないことを確認します
同じファイル内の異なるセクション	いいえ	マージ時に競合が避けられません
タスクBがタスクAの出力を使用する	いいえ	逐次的な依存関係があります
両方が同じファイルを読み、異なるファイルに書き込む	はい	読み取りは安全に並列化できます
両方が共有設定ファイルを変更する	いいえ	設定が競合します
独立したテストファイル	はい	テストは独立しています
一方のエージェントが依存関係を追加し、もう一方がそれを使用する	いいえ	パッケージレベルの依存関係があります

並列化しない場合

• サブタスクが可変状態を共有する、または同じファイルを変更する
• タスクBがタスクAの出力に依存する
• 調整のオーバーヘッドが、短縮できる時間を上回る
• 1つのエージェントで30秒以内に完了できる
• 各ステップの結果を次のステップに反映しながら、反復的に改善する必要がある

停止 — 次の条件を満たすまで、Agentツールを使ってエージェントをディスパッチしないでください。

• すべてのサブタスクの組み合わせについて、4つの独立性基準をすべて検証している
• 同じファイルに書き込むエージェントが2つ以上存在しない
• 各エージェントのコンテキストが自己完結している

---

フェーズ2：プロンプトの作成

目標： 作業範囲の逸脱や競合を防ぐ、焦点が明確で曖昧さのないプロンプトを作成します。

各エージェントのプロンプトには、次の4つのセクションを必ず含めてください。

セクション1：作業範囲（実施内容）

具体的なタスク、ファイル、期待される変更を明確にします。

SCOPE: Add structured JSON logging to all API route handlers in src/api/.
Replace console.log calls with the logger from src/utils/logger.ts.
Files to modify: src/api/users.ts, src/api/orders.ts, src/api/products.ts.

セクション2：コンテキスト（必要な情報すべて）

エージェントが調査を行わずに作業できるよう、必要な情報をすべて提示します。

CONTEXT:
- Logger API: logger.info(message, metadata), logger.error(message, error)
- Import: import { logger } from '../utils/logger'
- Current pattern in files: console.log('action', data)
- Target pattern: logger.info('action', { data, requestId: req.id })

セクション3：出力形式（返す内容）

エージェントが作成すべき内容を正確に定義します。

OUTPUT: For each modified file, return:
1. The file path
2. A summary of changes made
3. Number of console.log calls replaced

セクション 4：制約（してはいけないこと）

スコープの拡大や競合を明示的に防ぎます。

CONSTRAINTS:
- Do NOT modify any files outside src/api/
- Do NOT change the logger utility itself
- Do NOT add new dependencies
- Do NOT refactor function signatures
- Do NOT modify test files
- If you encounter an issue outside your scope, report it but do not fix it

エージェントプロンプトのテンプレート

You are a focused agent with a single task.

## Scope
[Specific task description with exact files]

## Context
[All information needed to complete the task]
[Relevant code patterns, APIs, conventions]

## Output Format
[Exact structure of what to return]

## Constraints
- Do NOT modify files outside: [list]
- Do NOT change: [list things to leave alone]
- Do NOT add dependencies
- If you encounter an issue outside your scope, report it but do not fix it

プロンプト品質チェックリスト

確認項目	質問
スコープが具体的	エージェントは推測せずにタスクを完了できますか？
コンテキストが完全	エージェントがコードベースを調べる必要がありますか？（必要ないはずです）
出力が定義済み	エージェントは統合に必要なものを返しますか？
制約が明示的	ファイルの境界と「してはいけないこと」が明確ですか？

停止 — 次の条件を満たすまで、（Agent ツールを使って）ディスパッチしてはいけません：

• すべてのプロンプトに 4 つのセクションがある
• 提供されたコンテキストの範囲を超えて調査する必要があるプロンプトがない
• すべての制約セクションでファイルの境界が明示されている

---

フェーズ 3：ディスパッチと監視

目標： すべてのエージェントを（Agent ツールを使って）並行して起動し、完了状況を追跡します。

1. 1 つのメッセージ内で複数の Agent ツール呼び出しを行い、すべてのエージェントを並行して起動します
2. 各エージェントは、指定されたファイルを対象に独立して作業します
3. 完了状況を監視し、すべてのエージェントが完了するまで待ちます
4. すべてのエージェントから出力を収集します

ディスパッチ追跡テーブル

| Agent | Task | Status | Files | Result |
|-------|------|--------|-------|--------|
| Agent 1 | Add logging to API | in_progress | src/api/*.ts | — |
| Agent 2 | Update unit tests | in_progress | tests/unit/*.ts | — |
| Agent 3 | Fix CSS layout | in_progress | src/styles/*.css | — |

ディスパッチ中の失敗への対処

状況	対応
1 つのエージェントが失敗し、ほかは成功	失敗したエージェントを単独で再試行します（Agent ツールを使います）
複数のエージェントが個別に失敗	それぞれを個別に再試行します（Agent ツールを使います）
エージェントがスコープ外の問題を報告	統合後のレビュー用に記録します
エージェントがスコープを逸脱（誤ったファイルを変更）	出力を却下し、より厳しい制約を指定して再ディスパッチします（Agent ツールを使います）

---

フェーズ 4：統合と検証

目標： すべてのエージェントの出力を組み合わせ、統合した結果を検証します。

1. 出力を収集 — すべてのエージェントの結果を集めます
2. 競合を確認 — 複数のエージェントが同じファイルを変更していないことを確認します
3. 変更を適用 — すべての出力をコードベースに統合します
4. 統合チェックを実行 — テストスイート全体を実行します
5. 問題を解決 — 統合に失敗した場合、どのエージェントの変更が原因かを特定します
6. 一括でコミット — すべての変更をまとめて反映するか、まったく反映しないかのどちらかにします

統合検証チェックリスト

確認項目	コマンド	成功必須
ファイル競合がない	共有ファイルの差分を確認	はい
テストが成功する	テストスイート全体	はい
ビルドが成功する	ビルドコマンド	はい
Lint が成功する	Lint コマンド	はい
リグレッションがない	テスト数を変更前後で比較	はい

統合失敗時の判断テーブル

失敗の種類	診断	対応
Agent 1 のファイルでテストが失敗	Agent 1 の変更にバグがあります	テスト失敗のコンテキストを添えて Agent 1 を再ディスパッチします（Agent ツールを使います）
無関係なファイルでテストが失敗	横断的なリグレッション	根本原因を特定し、手動で修正するか再ディスパッチします（Agent ツールを使います）
ビルドの失敗	インポートまたは型の問題	どのエージェントの変更が原因かを確認し、修正します
マージ競合	エージェントが同じファイルを変更（本来起きるべきではありません）	ロールバックし、該当するタスクを順番に実行します

停止 — 次の条件を満たすまで、コミットしてはいけません：

• すべてのエージェントの出力を収集済み
• ファイル競合が検出されていない
• テストスイート全体が成功
• ビルドと Lint が成功

---

よくある並行処理パターン

パターン判断テーブル

パターン	使用する場面	例
モジュール単位	独立したモジュールまたはパッケージ	マイクロサービスごとに Agent を 1 回呼び出す
レイヤー単位	各レイヤーが異なるファイルに触れる場合	API エージェント、サービスエージェント、データエージェント
機能領域単位	独立した垂直スライス	認証エージェント、プロフィールエージェント、課金エージェント
タスク種別単位	コード、テスト、ドキュメントが異なるファイルに触れる場合	コードエージェント、テストエージェント、ドキュメントエージェント

例：完全なディスパッチ

TASK: "Update the API to v2, add tests, and update OpenAPI spec"

AGENT 1 - API Routes:
  Scope: Update route handlers in src/routes/v2/
  Context: [v2 API spec, breaking changes list]
  Output: Modified files list, breaking changes implemented
  Constraints: Do NOT touch tests or docs

AGENT 2 - Tests:
  Scope: Write tests in tests/v2/
  Context: [v2 API spec, test conventions, existing v1 tests as reference]
  Output: New test files, coverage summary
  Constraints: Do NOT modify source code

AGENT 3 - OpenAPI Spec:
  Scope: Update openapi/v2.yaml
  Context: [v2 API spec, OpenAPI 3.1 format]
  Output: Updated spec file
  Constraints: Do NOT modify code or tests

---

アンチパターン／よくある間違い

アンチパターン	失敗する理由	正しいアプローチ
2つのエージェントが同じファイルを変更する	マージの競合、データ損失	Agent のディスパッチごとに、各ファイルの担当者を1人にする
エージェント間で可変状態を共有する	競合状態、一貫性の欠如	共有状態をなくす
プロンプトのコンテキストが不完全	エージェントが調査し、互いに作業を妨げる	必要なコンテキストをすべて提供する
ファイルの境界が曖昧	エージェントが範囲を推測し、誤ったファイルを変更する	制約にファイルの一覧を明記する
完了後に統合チェックを行わない	複数箇所にまたがるバグを見逃す	統合後にテストスイート全体を実行する
順次実行すべきタスクを並列化する	エージェント B がエージェント A の出力を必要とする	まず独立性を確認する
どのエージェントがどのファイルに触れたか追跡しない	統合の失敗を診断できない	ディスパッチの追跡表を維持する
エージェントをディスパッチしすぎる（10人以上）	調整のオーバーヘッドが効率化の効果を上回る	ディスパッチのラウンドごとに Agent 呼び出しを2～5回にする
ロールバックの準備を省略する	統合に失敗したときに復旧できない	ディスパッチ前の状態に復旧できるようにしておく

---

合理化を防ぐためのガード

同じファイルを変更するエージェントを（`Agent` ツール経由で）ディスパッチしないでください。データ依存関係のあるタスクを並列化しないでください。統合の検証を省略しないでください。独立性の基準を満たさない場合は、タスクを順次実行してください。

次のように考えていることに気づいたら：

• 「これらのエージェントは、おそらく競合しないでしょう……」— 検証してください。決めつけないでください。
• 「統合は問題ないでしょう……」— テストスイート全体を実行してください。必ず実行してください。
• 「同じファイルへの変更を手作業でマージできます……」— いいえ。1つのファイルにつき担当者は1人です。

---

統合ポイント

スキル	関係	タイミング
task-decomposition	上流 — 独立したタスク群を特定する	ディスパッチ前
subagent-driven-development	補完関係 — レビューゲートを提供する	エージェントの出力に対する品質ゲート
executing-plans	上流 — 独立したタスクを委任する場合がある	計画の実行中
verification-before-completion	下流 — 統合後の結果を検証する	統合後
code-review	下流 — 統合後の変更をレビューする	すべてのエージェントの完了後
resilient-execution	失敗時 — 失敗したエージェントを再試行する	個々のエージェントが失敗したとき

---

並列化の安全ルールのまとめ

ルール	理由
2人のエージェントが同じファイルを変更しない	マージの競合と競合状態を防ぐ
可変状態を共有しない	データ競合をなくす
各エージェントに完全なコンテキストを渡す	エージェントが調査し、互いに作業を妨げるのを防ぐ
ファイルの境界を明確に定義する	担当範囲を明確にする
完了後に統合をレビューする	複数箇所にまたがる問題を検出する
すべての変更をアトミックにコミットする	すべて反映するか、すべて取り消す
必ずロールバック手段を用意する	ディスパッチ前の状態に復旧できるようにしておく

---

スキルの種類

RIGID — このプロセスに厳密に従ってください。独立性の検証は必須です。プロンプトの4つのセクションはすべて必須です。統合の検証は必須です。並列化の安全性に関する手順を省略してはいけません。