dispatching-parallel-agents

并行调度 Agent

概述

当遇到多个彼此无关的失败（不同的测试文件、不同的子系统、不同的错误）时，按顺序逐个排查会浪费时间。每项排查都是独立的，可以并行进行。

核心原则： 为每个独立的问题领域调度一个 Agent，让他们并行工作。

适用场景

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 个以上测试文件因不同根本原因而失败
• 多个子系统各自独立地出现故障
• 无需了解其他问题的上下文即可理解每个问题
• 各项排查之间没有共享状态

不适用于：

• 失败之间存在关联（修复一个可能会解决其他问题）
• 需要了解整个系统的状态
• Agent 之间可能会互相干扰

工作模式

1. 找出独立的问题领域

按故障内容对失败进行分组：

• 文件 A 测试：工具审批流程
• 文件 B 测试：批处理完成行为
• 文件 C 测试：中止功能

每个领域都是独立的——修复工具审批不会影响中止测试。

2. 创建明确的 Agent 任务

每个 Agent 的任务应包含：

• 明确范围： 一个测试文件或子系统
• 清晰目标： 让这些测试通过
• 限制条件： 不要修改其他代码
• 预期输出： 总结发现的问题及修复内容

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. 审查并集成

Agent 返回结果后：

• 阅读每份总结
• 确认修复之间没有冲突
• 运行完整测试套件
• 集成所有更改

Agent 提示词结构

好的 Agent 提示词应当：

1. 聚焦明确——只针对一个问题领域
2. 自成一体——包含理解问题所需的全部上下文
3. 明确输出要求——说明 Agent 应返回什么

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 范围过广：“修复所有测试”——Agent 会不知所措
V 目标明确：“修复 agent-tool-abort.test.ts”——范围清晰

X 缺少上下文：“修复竞态条件”——Agent 不知道问题在哪里
**V 提供上下文：**粘贴错误消息和测试名称

**X 没有限制：**Agent 可能会重构所有代码
V 明确限制：“不要更改生产代码”或“只修复测试”

X 输出要求含糊：“修复它”——你不知道改了什么
V 明确要求：“返回根本原因和更改内容的总结”

不适用场景

**相关联的失败：**修复一个可能会解决其他问题——应先一起排查
**需要完整上下文：**理解问题需要查看整个系统
**探索性调试：**还不知道具体哪里出了问题
**共享状态：**Agent 之间可能会互相干扰（编辑相同文件、使用相同资源）

会话中的实际示例

**场景：**重大重构后，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

结果：

• Agent 1：将超时等待改为基于事件的等待
• Agent 2：修复事件结构错误（threadId 放置位置不正确）
• Agent 3：等待异步工具执行完成

**集成：**所有修复彼此独立，没有冲突，完整测试套件全部通过

**节省时间：**并行解决 3 个问题，而非顺序逐个解决

主要优势

1. 并行处理——同时进行多项排查
2. 聚焦——每个 Agent 的范围都很窄，需要跟踪的上下文更少
3. 独立——Agent 之间不会互相干扰
4. 快速——用解决 1 个问题的时间解决 3 个问题

验证

Agent 返回结果后：

1. 审阅每份总结——了解更改内容
2. 检查冲突——Agent 是否编辑了相同代码？
3. 运行完整测试套件——确认所有修复能够协同工作
4. 抽查——Agent 可能会犯系统性错误

真实影响

调试记录（2025-10-03）：

• 3 个文件中出现 6 个故障
• 并行派发了 3 个 Agent
• 所有调查均同时完成
• 所有修复均成功集成
• 各 Agent 的修改之间没有冲突

铁律

1. 绝不并行处理共享可变状态或写入相同文件的任务——并发写入会导致竞态条件、合并冲突和修改丢失。
2. 始终在启动并行 Agent 前，为每个 Agent 定义禁止访问路径和负责路径——未明确划分路径所有权的 Agent 会互相干扰。
3. 始终先汇总所有 Agent 的调查结果，再实施任何修改——汇总完成前依据不完整的并行结果采取行动，会造成修复冲突。
4. 绝不启动超过真正独立调查领域数量的并行 Agent——强行并行处理相关问题，只会增加协调开销，没有益处。
5. 始终在标记并行派发完成前，确认各 Agent 的所有修改之间不存在任何冲突——未经验证的集成不算完成。

反模式

反模式	失败原因	正确做法
对相同文件启动并行 Agent	竞态条件；后写入的修改生效；某个 Agent 的修复会悄然覆盖另一个 Agent 的修复	为每个 Agent 定义 owned_paths；启动前确保路径没有重叠
未等待所有 Agent 完成就依据第一个 Agent 的结果采取行动	汇总完成前会产生不完整且相互冲突的状态	等待所有并行 Agent 完成；实施任何修改前先汇总结果
将存在顺序依赖的任务并行化	Agent B 依赖 Agent A 的输出；并行执行会导致 B 使用过时数据	先梳理依赖关系；只并行处理真正独立的领域
集成后不进行冲突验证	冲突的修改会被悄然接受；系统会处于无效状态	所有并行 Agent 完成后，始终执行冲突检查
对简单的两步任务使用并行派发	并行开销超过短任务带来的收益	仅当每个调查领域都需要 3 个或更多独立步骤时，才使用并行派发

记忆协议（必须遵守）

开始前： 阅读 .claude/context/memory/learnings.md

完成后：

• 新模式 -> .claude/context/memory/learnings.md
• 发现问题 -> .claude/context/memory/issues.md
• 作出决策 -> .claude/context/memory/decisions.md

假设会被中断：如果没有记录在记忆中，就等于没有发生。