dispatching-parallel-agents

调度并行代理（Dispatching Parallel Agents）

技能概述

调度并行代理是一种将多个独立任务分配给不同代理同时处理的工作模式，每个代理拥有隔离的上下文，专注于解决特定问题域，从而大幅提升调试和开发效率。

适用场景

1. 多个测试文件同时失败

当代码重构或重大变更后，多个测试文件出现不同原因的失败时，可以为每个测试文件分配独立的代理并行调查和修复。例如：agent-tool-abort.test.ts 的时序问题、batch-completion-behavior.test.ts 的工具执行问题、tool-approval-race-conditions.test.ts 的竞态条件，这三个问题相互独立，适合并行处理。

2. 多个子系统独立故障

当系统的不同模块出现独立故障时（如工具审批流程、批量完成行为、中止功能），每个问题域可以单独理解而不需要其他上下文。此时可以调度多个代理分别专注于各自的子系统，避免单个代理在多个问题间切换导致的上下文混乱。

3. 无共享状态的独立调试

当多个调试任务之间没有共享状态、不会互相干扰时（例如操作不同的文件、使用不同的资源），可以安全地并行调度代理。关键判断标准是：修复一个问题不会影响其他问题，代理之间也不会因为编辑相同文件或资源而产生冲突。

核心功能

1. 独立问题域识别

帮助开发者快速识别哪些任务可以并行处理。通过判断失败是否相关、是否需要完整系统上下文、是否存在共享状态，将复杂的多任务场景分解为可并行处理的独立问题域，确保每个代理有明确的职责范围。

2. 精确的任务描述模板

提供编写高质量代理任务提示的结构化方法。每个代理任务应该包含：明确的范围（一个测试文件或子系统）、清晰的目标（让这些测试通过）、约束条件（不要更改其他代码）、预期的输出格式（发现和修复的总结），避免任务过于宽泛或缺乏上下文。

3. 并行调度与结果集成

支持在 Claude Code / AI 环境中并行启动多个代理任务，并在所有代理返回结果后进行统一的审核和集成。包括：阅读每个代理的修复总结、验证修复之间没有冲突、运行完整测试套件、集成所有变更，确保多个独立修复能够协同工作。

常见问题

什么时候应该使用并行代理调度？

当面临 3 个或更多独立任务、不同测试文件失败原因不同、多个子系统独立故障、每个问题可以在没有其他上下文的情况下理解、任务之间没有共享状态时，适合使用并行代理调度。核心判断标准是：修复一个问题不会影响其他问题。

如何为并行代理编写好的任务描述？

好的代理任务描述应该是：专注的（一个清晰的问题域）、自包含的（提供理解问题所需的所有上下文）、输出明确的（指定代理应该返回什么）。避免过于宽泛如"修复所有测试"，而是具体到"修复 agent-tool-abort.test.ts 中的 3 个失败测试"，并附上错误消息和测试名称。

并行代理会互相干扰吗？

在正确使用的情况下不会。关键是确保任务域是真正独立的：代理操作不同的文件、没有共享状态、修复一个问题不会影响其他问题。在调度前应该审核任务列表，确保没有代理会编辑相同的代码或使用相同的资源。审核集成阶段也需要检查代理的修复是否有冲突。