古法编程

当且仅当多个任务之间没有共享状态且没有顺序依赖时，才适合并行发射子代理。并行的核心是为每个独立问题域构建一个聚焦、自包含的指令，让代理同时工作，最后由你审查和集成结果。

dispatching-parallel-agents：多个独立故障如何并行分派 AI 子代理

在 AI 辅助编程中，逐个处理相互独立的问题会浪费时间。dispatching-parallel-agents 是 Superpowers 技能库中的一项关键模式，它指导你识别独立问题域，并同时发射多个子代理进行处理，从而将串行工作变为并行，显著提升调试和修复效率。

核心判断：两个独立性条件

在决定并行之前，必须根据 dispatching-parallel-agents/SKILL.md 中的 When to Use 流程图回答两个问题：

  1. 任务之间有没有共享状态？ 如果多个代理需要修改同一个文件或资源，它们的改动可能相互覆盖或冲突。
  2. 任务之间有没有顺序依赖？ 如果任务 B 的输入依赖任务 A 的输出，那么 B 必须等 A 完成。

只有当这两个条件都不满足时，并行分派才是正确的选择。

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”];
}

适合并行的场景（来自技能文档的“Real Example”）

例如，在一次重构后，CI 报告了 6 个测试失败，分布在三个文件中：

  • agent-tool-abort.test.ts：计时/竞态条件问题
  • batch-completion-behavior.test.ts：事件结构错误
  • tool-approval-race-conditions.test.ts：异步等待问题

这三组失败根因完全不同，修复一个不会影响另一个。它们没有共享状态（修改不同文件），也没有顺序依赖。这是一个典型的并行场景。以下是一个来自 tests/skill-triggering/prompts/dispatching-parallel-agents.txt 的真实 skill-triggering 测试 prompt，它触发了并行处理模式：

I have 4 independent test failures happening in different modules:

  1. tests/auth/login.test.ts - “should redirect after login” is failing
  2. tests/api/users.test.ts - “should return user list” returns 500
  3. tests/components/Button.test.tsx - snapshot mismatch
  4. tests/utils/date.test.ts - timezone handling broken

These are unrelated issues in different parts of the codebase. Can you investigate all of them?

不适合并行的场景（来自技能文档的“When NOT to Use”）

如果问题根因未知（例如，一个模糊的类型不匹配构建失败），你无法在并行分派前将问题拆分为独立的子任务。当故障相互关联、修复一个可能解决另一个、或需要理解系统完整状态时，应选择单个代理进行调查。

并行分派的操作步骤（基于技能文档的“The Pattern”）

1. 识别独立的任务域 (Identify Independent Domains)

根据失败的模块、子系统或错误类型进行分组。核心原则是：修复一个域的问题不会影响另一个域。例如，将失败的测试按其所属的源文件或功能子系统归类。

2. 创建聚焦的代理任务 (Create Focused Agent Tasks)

每个子代理的指令必须是聚焦、自包含且目标明确的。它不应该继承你当前会话的历史，而是由你精确构建它所需的所有上下文。好的指令包含四个要素：

  • 明确的范围：例如，“只修复 src/agents/agent-tool-abort.test.ts 这个文件”。
  • 足够的背景：直接粘贴相关的错误信息、测试名称和期望行为。
  • 清晰的目标：明确说明是返回修复后的代码、根因分析还是改动说明。
  • 明确的约束：例如，“不要修改生产代码”或“不要只加大超时值”。

这是一个来自技能文档 Agent Prompt Structure 部分的好指令示例：

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.

3. 并行分派 (Dispatch in Parallel)

根据你使用的平台，调用相应的工具同时启动多个代理。平台差异至关重要：

  • Claude Code: 使用原生 Task 工具。
  • Copilot CLI: 使用 task 工具，并指定 agent_type（如 general-purpose）。
  • Codex: 使用 spawn_agent 工具，并必须确保在 ~/.codex/config.toml 中启用了 multi_agent = true。
  • Gemini CLI: 使用 @generalist 语法，并将完整的任务指令作为消息传递。

4. 审查与整合 (Review and Integrate)

代理完成不等于任务结束。你需要：

  1. 阅读每个代理的摘要，理解它做了什么。
  2. 检查冲突：确认多个代理没有修改同一段代码。
  3. 运行完整的测试套件，验证所有改动合并后的效果。
  4. 抽查修改：代理有时会做出系统性错误（如简单地弱化断言），需要你来把关。

平台差异与子代理支持（基于平台工具映射文档）

不同 AI 编码平台对子代理的支持差异很大，这是并行分派的关键前提。

  • Codex (codex-tools.md)：需要手动在配置中开启 multi_agent 功能，并使用 spawn_agent/wait_agent/close_agent 工具链。
  • Copilot CLI (copilot-tools.md)：提供原生的 task 工具，支持并行调用。
  • Claude Code：原生支持 Task 工具。
  • Gemini CLI (gemini-tools.md)：支持通过 @generalist 语法分派子代理，并且支持在同一个 prompt 中请求多个独立的子代理任务以实现并行。

常见错误 (Common Mistakes)（来自技能文档）

  • ❌ 范围太宽：“帮我修所有失败的测试”——代理会迷失，倾向于做大量不必要的改动。
  • ✅ 范围具体：“修复 agent-tool-abort.test.ts”——代理目标明确。
  • ❌ 没有提供错误信息：“修复 race condition 问题”——代理不知道具体上下文。
  • ✅ 包含上下文：直接粘贴错误消息和测试名称。
  • ❌ 没有约束：代理可能重构整个模块来让测试通过。
  • ✅ 设定约束：“不要修改生产代码”或“只调整测试”。
  • ❌ 输出模糊：“修一下”——你不知道具体改了什么。
  • ✅ 要求具体输出：“返回根因摘要和改动说明”。

验证 (Verification)（来自技能文档）

代理返回后，最终验证责任在你。每个代理只能验证自己的局部改动，你必须运行完整的测试套件来验证所有改动合并后的系统稳定性。这体现了 verification-before-completion 的原则：代理声明完成前，必须由你拿出系统运行通过的“新鲜证据”。

FAQ

Q: 并行发射多少个代理合适？ A: 没有硬性限制，但受你能有效整合结果的能力约束。代理越多，整合成本越高。通常 3 到 5 个是比较容易管理的范围。

Q: 子代理如果发现自己的任务和别的代理有重叠，该怎么办？ A: 子代理应该暂停并报告冲突，而不是继续前进。这就是为什么在发射前必须明确定义任务范围和约束——让代理在存疑时上报。

Q: 并行代理的执行结果最终由谁验证？ A: 由你，而不是由任何一个子代理。每个代理只能验证自己的局部改动，最终必须由你运行完整的测试套件来验证所有改动合并后的系统稳定性。这体现了 verification-before-completion 的原则。