Overview
When you encounter multiple unrelated failures (different test files, different subsystems, different errors), investigating them sequentially wastes time. Each investigation is independent and can be done in parallel.
Core principle: Dispatch one agent per independent problem domain. Have them work simultaneously.
When to Use
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. 並行調度
```typescript
// 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. Review and Integrate
When the agents return:
- Read each summary
- Verify the fixes do not conflict
- Run the full test suite
- Integrate all changes
Agent Prompt Structure
A good agent prompt is:
- Focused - one clear problem domain
- Independent - all the context needed to understand the problem
- Specific output - what should the agent return?
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.
Common Mistakes
❌ Too broad:"Fix all tests" - the agent gets lost ✅ Specific:"Repairagent-tool-abort.test.ts" - focused scope
❌ No context:"Fix the race condition" - the agent does not know where ✅ Context: Paste the error message and test name
**❌ No constraints:** The agent may refactor everything ✅ Constraints: "Do not change production code" or "Only fix the tests"
❌ Vague output: "Fix it" - you do not know what changed ✅ Specific:"Root cause and a summary of changes returned"
When Not to Use
Related failures: Fixing one may fix the others - investigate them together first **Needs full context:** understanding requires seeing the whole system Exploratory debugging: You do not yet know what went wrong **Shared state:** agents will interfere (editing the same files, using the same resources)
Real Example from a Session
**Scenario:** After a major refactor, 6 test failures in 3 files
Failures:
- agent-tool-abort.test.ts: 3 failures (timing issues)
- batch-completion-behavior.test.ts: 2 failures (tool not executed)
- tool-approval-race-conditions.test.ts: 1 failure (execution count = 0)
Decision: Independent domains - abort logic is separate from batch completion, and separate from the race condition
Dispatch:
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
Results:
- Agent 1: Replaced the timeout with event-based waiting
- Agent 2: Fixed the event structure error (threadId was in the wrong place)
- Agent 3: Added waiting for the async tool execution to complete
Integration: All fixes were independent, no conflicts, full suite green
Time saved: Solving 3 problems in parallel versus sequentially
Key Benefits
- Parallelization - multiple investigations happen at the same time
- Focus - each agent's scope is narrow, with less context to track
- Independent - Agents do not interfere with each other
- Speed - Solve 3 problems within 1 unit of time
Confirm
After the agents return:
- Review each summary - Understand what changed
- Check for conflicts - Did the agents edit the same code?
- Run the full suite - Verify that all fixes work together
- Spot-check - Agents may make systematic errors
Real-world impact
From a debugging session (2025-10-03):
- 6 failures in 3 files
- 3 agents dispatched in parallel
- All investigations completed simultaneously
- All fixes were successfully integrated
- Zero conflicts between agent changes