dispatching-parallel-agents

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

概要

無関係な失敗が複数ある場合（異なるテストファイル、異なるサブシステム、異なるバグ）、それらを順番に調査すると時間が無駄になります。各調査は独立しているため、並列に進められます。

中心原則: 独立した問題領域ごとに 1 つのエージェントをディスパッチします。それらを同時に作業させてください。

使用するタイミング

digraph when_to_use {
    "Multiple failures?" [shape=diamond];
    "Are they independent?" [shape=diamond];
    "Single agent investigates all" [shape=box];
    "One agent per problem domain" [shape=box];
    "Can they work in parallel?" [shape=diamond];
    "Sequential agents" [shape=box];
    "Parallel dispatch" [shape=box];

    "Multiple failures?" -> "Are they independent?" [label="yes"];
    "Are they independent?" -> "Single agent investigates all" [label="no - related"];
    "Are they independent?" -> "Can they work in parallel?" [label="yes"];
    "Can they work in parallel?" -> "Parallel dispatch" [label="yes"];
    "Can they work in parallel?" -> "Sequential agents" [label="no - shared state"];
}

次の場合に使用します:

• 異なる根本原因で 3 つ以上のテストファイルが失敗している
• 複数のサブシステムが互いに独立して壊れている
• 各問題を、他の問題の文脈なしに理解できる
• 調査間で共有状態がない

次の場合には使用しないでください:

• 失敗が互いに関連している（1 つを修正すると他も直るかもしれない）
• システム全体の状態を理解する必要がある
• エージェント同士が干渉し合う

パターン

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

失敗を、何が壊れているかでグループ化します:

• ファイル A のテスト: ツール承認フロー
• ファイル B のテスト: バッチ完了時の動作
• ファイル C のテスト: 中断機能

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

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

各エージェントに与える内容:

• 明確な範囲: 1 つのテストファイルまたはサブシステム
• 明確な目標: これらのテストを通過させる
• 制約: 他のコードは変更しない
• 期待される出力: 発見と修正内容の要約

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

4. レビューして統合する

エージェントが結果を返したら:

• 各要約を読む
• 修正同士が競合していないか確認する
• テストスイート全体を実行する
• すべての変更を統合する

エージェントプロンプトの構造

良いエージェントプロンプトは次の条件を満たします:

1. 焦点が絞られている - 問題領域は 1 つだけ明確にする
2. 自己完結している - 問題を理解するために必要な文脈をすべて含む
3. 出力について具体的である - エージェントは何を返すべきか？

Fix the 3 failing tests in src/agents/agent-tool-abort.test.ts:

1. "should abort tool with partial output capture" - expects 'interrupted at' in message
2. "should handle mixed completed and aborted tools" - fast tool aborted instead of completed
3. "should properly track pendingToolCount" - expects 3 results but gets 0

These are timing/race condition issues. Your task:

1. Read the test file and understand what each test verifies
2. Identify root cause - timing issues or actual bugs?
3. Fix by:
   - Replacing arbitrary timeouts with event-based waiting
   - Fixing bugs in abort implementation if found
   - Adjusting test expectations if testing changed behavior

Do NOT just increase timeouts - find the real issue.

Return: Summary of what you found and what you fixed.

よくある間違い

❌ 範囲が広すぎる: 「すべてのテストを修正して」 - エージェントが迷子になる ✅ 具体的: 「agent-tool-abort.test.ts を修正して」 - 範囲が絞られている

❌ 文脈がない: 「競合状態を修正して」 - エージェントはどこにあるか分からない ✅ 文脈がある: エラーメッセージとテスト名を貼り付ける

❌ 制約がない: エージェントがすべてをリファクタリングしてしまうかもしれない ✅ 制約がある: 「本番コードは変更しないこと」または「テストのみ修正すること」

❌ 出力が曖昧: 「直して」 - 何が変わったか分からない ✅ 具体的: 「根本原因と変更内容の要約を返すこと」

使用しない場合

関連する失敗: 1 つを修正すると他も直るかもしれないため、まず一緒に調査する 完全な文脈が必要: 理解するにはシステム全体を見る必要がある 探索的なデバッグ: 何が壊れているか分からない段階 共有状態: エージェント同士が干渉する（同じファイルを編集する、同じリソースを使用する）

セッションからの実例

シナリオ: 大規模なリファクタリング後、3 つのファイルで 6 件のテストが失敗

失敗内容:

• agent-tool-abort.test.ts: 3 件の失敗（タイミングの問題）
• batch-completion-behavior.test.ts: 2 件の失敗（ツールが実行されない）
• tool-approval-race-conditions.test.ts: 1 件の失敗（実行回数 = 0）

判断: 独立した領域である。中断ロジック、バッチ完了、競合状態はそれぞれ別々に扱える

ディスパッチ:

Agent 1 → Fix agent-tool-abort.test.ts
Agent 2 → Fix batch-completion-behavior.test.ts
Agent 3 → Fix tool-approval-race-conditions.test.ts

結果:

• エージェント 1: タイムアウトをイベントベースの待機に置き換えた
• エージェント 2: イベント構造のバグを修正した（threadId の位置が誤っていた）
• エージェント 3: 非同期ツール実行の完了を待つ処理を追加した

統合: すべての修正は独立しており、競合はなく、スイート全体が成功した

節約できた時間: 3 つの問題を順番ではなく並列に解決できた

主な利点

1. 並列化 - 複数の調査を同時に進められる
2. 集中 - 各エージェントの範囲が狭く、追跡する文脈が少ない
3. 独立性 - エージェント同士が干渉しない
4. 速度 - 3 つの問題を 1 つ分の時間で解決できる

検証

エージェントが結果を返したら:

1. 各要約をレビューする - 何が変わったかを理解する
2. 競合を確認する - エージェントが同じコードを編集していないか？
3. スイート全体を実行する - すべての修正が一緒に動作することを確認する
4. 抜き取りで確認する - エージェントは体系的な誤りを犯すことがある

実際の効果

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

• 3 つのファイルにまたがる 6 件の失敗
• 3 つのエージェントを並列に起動
• すべての調査が同時に完了
• すべての修正を正常に統合
• エージェントの変更間の競合はゼロ