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. 独立した問題領域を特定する

問題の内容ごとに失敗を分類します。

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

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

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

各エージェントに次の内容を与えます。

• 具体的な範囲： テストファイルまたはサブシステムを一つ
• 明確な目標： 対象のテストを通過させる
• 制約： ほかのコードは変更しない
• 期待する出力： 調査結果と修正内容の概要

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. 焦点が絞られている - 明確な問題領域が一つ
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.

よくある間違い

X 範囲が広すぎる：「テストをすべて直して」—エージェントが途方に暮れます
V 具体的：「agent-tool-abort.test.tsを直して」—範囲が絞られています

X コンテキストがない：「競合状態を直して」—エージェントは場所がわかりません
V コンテキストあり： エラーメッセージとテスト名を貼り付けます

X 制約がない： エージェントがすべてをリファクタリングする可能性があります
V 制約あり：「本番コードは変更しないでください」または「テストのみ修正してください」

X 出力が曖昧：「直して」—何が変わったのかわかりません
V 具体的：「根本原因と変更内容の概要を返してください」

使用しないタイミング

関連する失敗： 一つを修正するとほかも直る可能性があるため、まずまとめて調査します
全体のコンテキストが必要： 理解するにはシステム全体を見る必要があります
探索的なデバッグ： 何が壊れているのか、まだわかっていません
共有状態： エージェント同士が干渉する可能性があります（同じファイルの編集、同じリソースの使用）

セッションでの実例

シナリオ： 大規模なリファクタリング後、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 つのエージェントを並列で起動
• すべての調査が同時に完了
• すべての修正を問題なく統合
• エージェント間の変更による競合はゼロ

絶対遵守事項

1. 絶対に、変更可能な状態を共有するタスクや同じファイルに書き込むタスクを並列化してはいけません。並行書き込みは、競合状態、マージ競合、変更の消失を引き起こします。
2. 必ず、各並列エージェントを起動する前に、禁止するパスと担当するパスを定義してください。明示的なパスの所有権がないエージェント同士は、互いの作業に干渉します。
3. 必ず、変更を実施する前に、エージェントからの調査結果をすべて統合してください。統合前に並列作業の部分的な結果に基づいて行動すると、修正同士が競合します。
4. 絶対に、真に独立した調査領域の数を超える並列エージェントを起動してはいけません。関連する問題を無理に並列化すると、メリットがないまま調整コストが増大します。
5. 必ず、並列作業の完了とする前に、エージェントによるすべての変更の間に競合がないことを確認してください。統合の検証をしていなければ、統合は完了していません。

アンチパターン

アンチパターン	失敗する理由	正しいアプローチ
同じファイルに対して並列エージェントを起動する	競合状態が発生し、最後の書き込みが優先され、あるエージェントの修正が別のエージェントによって気づかれないまま上書きされます	エージェントごとに owned_paths を定義し、起動前に重複がないことを確認する
すべての結果を待たずに最初のエージェントの結果に基づいて行動する	統合が完了する前に、状態が部分的かつ競合したものになります	すべての並列エージェントの完了を待ち、実装の前に結果を統合する
順次処理が必要な依存関係を並列化する	エージェント B がエージェント A の出力に依存しており、並列実行すると B は古いデータを扱います	まず依存関係を整理し、真に独立した領域のみを並列化する
統合後に競合を検証する手順がない	競合する変更が気づかれないまま受け入れられ、システムが無効な状態になります	すべての並列エージェントの完了後、必ず競合チェックを実行する
簡単な 2 ステップのタスクに並列ディスパッチを使う	短いタスクでは並列化のオーバーヘッドがメリットを上回ります	各調査領域に 3 つ以上の独立したステップが必要な場合にのみ、並列ディスパッチを使用する

メモリープロトコル（必須）

開始前： .claude/context/memory/learnings.md を読みます。

完了後：

• 新しいパターン -> .claude/context/memory/learnings.md
• 発見した問題 -> .claude/context/memory/issues.md
• 決定した事項 -> .claude/context/memory/decisions.md

中断を想定してください。メモリーに記録されていなければ、実施されていないのと同じです。