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  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. 速度 - 1つの問題にかかる時間で3つの問題を解決できる

確認

エージェントから結果が返ってきたら、次のことを行います：

1. 各要約を確認する - 何が変わったかを把握します
2. 競合を確認する - エージェントが同じコードを編集していないか確認します
3. テストスイート全体を実行する - すべての修正が連携して機能することを確認します
4. 抜き取り確認を行う - エージェントが系統的な誤りを犯す可能性があります

実環境での効果

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

• 3 ファイルで 6 件の失敗
• 3 つのエージェントを並行して派遣
• すべての調査を同時に完了
• すべての修正を正常に統合
• エージェントによる変更間の競合はゼロ