dispatching-parallel-agents

并行调度 Agent

概述

当出现多个互不相关的故障（不同的测试文件、不同的子系统、不同的 Bug）时，按顺序调查会浪费时间。每项调查都是独立的，可以并行进行。

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

何时使用此技能

遇到以下情况时启用此技能：

• 3 个以上测试文件失败，且根本原因各不相同
• 多个子系统各自出现故障
• 每个问题都是独立的——无需了解其他问题的背景即可理解
• 调查之间没有共享状态
• 领域边界清晰——修复其中一项不会影响其他问题

以下情况不要使用：

• 故障彼此相关（修复一个可能会解决其他问题）
• 需要先了解整个系统的状态
• Agent 会相互干扰（编辑同一个文件）
• 探索性调试（尚不清楚哪里出了问题）

铁律

One agent, one problem domain, one clear outcome.
Never overlap scopes. Never share state. Always integrate consciously.

核心原则

独立性至关重要

问题必须真正独立——不共享文件，根本原因互不相关，修复之间没有依赖关系。

聚焦而非求广

给每个 Agent 分配范围明确的任务：一个测试文件、一个子系统、一个清晰的目标。任务范围过广会导致混乱。

必须提供清晰的输出

每个 Agent 都必须返回摘要：发现了什么、修复了什么、有哪些变更。不得悄无声息地修复。

审慎整合

不要盲目合并 Agent 的工作。检查摘要、核对冲突、运行完整测试套件并验证兼容性。

快速开始

1. 找出独立领域

按故障内容对问题进行分组：

File A tests: Tool approval flow
File B tests: Batch completion behavior
File C tests: Abort functionality

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

2. 创建聚焦的 Agent 任务

每个 Agent 的任务应包含：

• 具体范围： 一个测试文件或一个子系统
• 清晰目标： 使这些测试通过
• 约束条件： 不要修改其他代码
• 预期输出： 对发现内容和修复内容的摘要

→ 查看 agent-prompts.md，获取提示词模板和示例

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

→ 查看 coordination-patterns.md，了解调度策略

4. 检查并整合

Agent 返回后：

• 阅读每份摘要，了解变更内容
• 确认修复不会冲突，检查是否编辑了同一个文件
• 运行完整测试套件，确保兼容性
• 抽查变更，Agent 可能会犯系统性错误

→ 查看 troubleshooting.md，了解冲突解决方法

决策树

Multiple failures?
  └→ Are they independent?
      ├→ NO (related) → Single agent investigates all
      └→ YES → Can they work in parallel?
          ├→ NO (shared state) → Sequential agents
          └→ YES → Parallel dispatch ✓

主要优势

1. 并行化——同时开展多项调查
2. 聚焦——每个 Agent 的范围都很明确，需要跟踪的上下文更少
3. 独立性——Agent 之间不会相互干扰
4. 速度——在解决一个问题所需的时间内解决 N 个问题

导航

模式参考

• 协调模式——调度策略、领域识别、整合工作流

Agent 管理

• Agent 提示词——提示词结构、模板、常见错误、约束条件

学习资源

• 示例——实际场景、案例研究、节省时间分析

问题解决

• 故障排查——冲突解决、验证策略、常见陷阱

相关技能

调度并行 Agent 时，可以考虑以下互补技能（可在技能库中找到）：

• pm-workflow：项目管理协调与任务管理——有效管理多个 Agent 工作流
• test-driven-development：适用于并行修复的 TDD 模式——在并行处理前了解测试失败的原因
• verification-before-completion：整合验证——确保并行 Agent 的工作能够正确整合

关键提醒

1. 必须保持独立 - 相关故障需要由单个 Agent 调查
2. 专注胜过面面俱到 - 缩小每个 Agent 的范围，避免混淆
3. 始终验证集成结果 - 不要盲目合并 Agent 的工作
4. 必须提供清晰的输出 - 每个 Agent 都要返回变更摘要
5. 并行处理有额外开销 - 只有面对 3 个或更多独立问题时才值得采用

危险信号 - 停止

出现以下情况时立即停止：

• Agent 正在编辑相同文件（范围重叠）
• 一个 Agent 的修复破坏了另一个 Agent 的工作（存在隐藏依赖）
• 问题领域无法明确区分（彼此不独立）
• Agent 没有返回摘要（无法验证变更）
• 集成需要大规模重构（存在冲突）

如有疑问： 先从一个 Agent 开始，了解整体情况，再在确认问题确实独立后分派任务。

与其他技能的集成

前置要求： 基本了解问题领域和测试结构 互补技能： 用于协调多个 Agent 的 PM-Workflow 技能（参见技能库） 领域专用： 用于理解测试故障的测试技能（可在技能库中找到）

实际影响

来自一次调试会话（2025-10-03）：

• 6 个故障，涉及 3 个测试文件
• 并行分派了 3 个 Agent
• 所有调查均并行完成
• Agent 的变更之间没有冲突
• 节省时间： 3 个问题并行解决，而非依次解决

→ examples.md 查看详细案例