dispatching-parallel-agents

分派并行 Agent

概述

此技能可协调多个 Agent 并发处理互不相关的子任务，从而缩短总执行时间，同时确保正确性。它针对如何识别适合安全并行处理的任务、编写聚焦的 Agent 提示词，以及整合结果并避免冲突，提供了严格规则。关键约束是，任何两个 Agent 都不得修改同一个文件。

开始时宣布：“我正在使用 dispatching-parallel-agents 技能，并发运行 [N] 个互不相关的任务。”

Agent 工具参考

所有分派工作都使用 Agent 工具。参数：

• prompt（必填）——包含完整上下文的任务说明
• description（必填）——简短标签（3-5 个词）
• subagent_type——"Explore"（搜索代码库）、"Plan"（架构设计）、"general-purpose"（默认）
• run_in_background——异步运行时设为 true（任务完成后会收到通知）
• model——可选的模型覆盖值："sonnet"、"opus"、"haiku"

**并行：**在一条消息中调用多个 Agent，这些调用会并发运行。 **后台运行：**设为 run_in_background=true，即可非阻塞地执行任务。 **命名 Agent：**使用 subagent_type 引用已安装的 Agent 模板（例如 "superpowers:code-reviewer"）。

触发条件

• 一个任务可拆分为 2 个或更多彼此之间没有数据依赖关系的子任务
• 每个子任务都处理不同的文件或代码库中的不同部分
• 所有 Agent 完成后，可以整合结果
• 串行执行所需的总时间明显长于并行执行
• /decompose 的输出揭示了彼此独立的任务簇

---

第 1 阶段：验证独立性

**目标：**确认子任务确实相互独立，适合安全并行处理。

每个子任务都必须满足以下全部四项独立性标准：

标准	问题	如果答案为否
没有共享文件	是否有两个 Agent 会写入同一个文件？	将这些任务改为串行执行
没有共享可变状态	是否有 Agent 依赖另一个 Agent 的副作用？	将存在依赖关系的任务改为串行执行
上下文自包含	每个 Agent 是否只需自己的输入就能开展工作？	提供更多上下文或改为串行执行
可独立验证	是否可以单独验证每个 Agent 的输出？	合并为单个任务

并行处理决策表

场景	并行处理？	原因
不同文件，不同关注点	是	不可能发生冲突
同一模块，不同文件	是（谨慎处理）	确认没有共享导入项变更
同一文件，不同部分	否	必然产生合并冲突
任务 B 使用任务 A 的输出	否	存在顺序依赖
两者都读取相同文件，但写入不同文件	是	读取操作可安全并行
两者都修改共享配置文件	否	配置冲突
独立的测试文件	是	测试彼此独立
一个 Agent 添加依赖，另一个 Agent 使用该依赖	否	存在包级依赖

不要并行处理的情况

• 子任务共享可变状态或修改同一文件
• 任务 B 依赖任务 A 的输出
• 协调开销超过节省的时间
• 单个 Agent 可在 30 秒内完成工作
• 任务需要迭代优化，且每一步都会影响下一步

停止——在满足以下条件前，不要分派 Agent（通过 Agent 工具）：

• 已确认每对子任务均满足全部四项独立性标准
• 没有两个 Agent 会写入同一个文件
• 每个 Agent 的上下文都是自包含的

---

第 2 阶段：构建提示词

**目标：**编写聚焦且明确的提示词，避免范围蔓延和冲突。

每个 Agent 提示词必须且只能包含以下四个部分：

第 1 部分：范围（要做什么）

明确说明具体任务、涉及的文件和预期变更。

SCOPE: Add structured JSON logging to all API route handlers in src/api/.
Replace console.log calls with the logger from src/utils/logger.ts.
Files to modify: src/api/users.ts, src/api/orders.ts, src/api/products.ts.

第 2 部分：上下文（所需的一切信息）

提供 Agent 所需的所有信息，无需其自行探索。

CONTEXT:
- Logger API: logger.info(message, metadata), logger.error(message, error)
- Import: import { logger } from '../utils/logger'
- Current pattern in files: console.log('action', data)
- Target pattern: logger.info('action', { data, requestId: req.id })

第 3 部分：输出格式（要返回什么）

明确定义 Agent 应生成的内容。

OUTPUT: For each modified file, return:
1. The file path
2. A summary of changes made
3. Number of console.log calls replaced

第 4 节：约束（不要做什么）

明确防止范围蔓延和冲突。

CONSTRAINTS:
- Do NOT modify any files outside src/api/
- Do NOT change the logger utility itself
- Do NOT add new dependencies
- Do NOT refactor function signatures
- Do NOT modify test files
- If you encounter an issue outside your scope, report it but do not fix it

Agent 提示词模板

You are a focused agent with a single task.

## Scope
[Specific task description with exact files]

## Context
[All information needed to complete the task]
[Relevant code patterns, APIs, conventions]

## Output Format
[Exact structure of what to return]

## Constraints
- Do NOT modify files outside: [list]
- Do NOT change: [list things to leave alone]
- Do NOT add dependencies
- If you encounter an issue outside your scope, report it but do not fix it

提示词质量检查清单

检查项	问题
范围具体明确	Agent 能否无需猜测即可完成任务？
上下文完整	Agent 是否需要探索代码库？（答案应为否）
输出明确	Agent 是否会返回你需要集成的内容？
约束明确	文件范围和“不要做”的事项是否清晰？

停止 — 在执行以下操作前，不要分派（通过 Agent 工具）：

• 每条提示词都包含全部 4 个部分
• 没有提示词要求 Agent 探索所提供上下文之外的内容
• 每个约束部分都明确了文件范围

---

第 3 阶段：分派并监控

目标： 并发启动所有 Agent（通过 Agent 工具）并跟踪完成情况。

1. 在同一条消息中调用多个 Agent 工具，同时启动所有 Agent
2. 每个 Agent 独立处理分配给它的文件
3. 监控完成情况——等待所有 Agent 全部完成
4. 收集每个 Agent 的输出

分派跟踪表

| Agent | Task | Status | Files | Result |
|-------|------|--------|-------|--------|
| Agent 1 | Add logging to API | in_progress | src/api/*.ts | — |
| Agent 2 | Update unit tests | in_progress | tests/unit/*.ts | — |
| Agent 3 | Fix CSS layout | in_progress | src/styles/*.css | — |

分派期间的故障处理

情况	操作
一个 Agent 失败，其他 Agent 成功	独立重试失败的 Agent（通过 Agent 工具）
多个 Agent 分别失败	分别独立重试每个 Agent（通过 Agent 工具）
Agent 报告范围外的问题	留待集成后审查时处理
Agent 超出范围（修改了错误的文件）	拒绝其输出，并在施加更严格的约束后重新分派（通过 Agent 工具）

---

第 4 阶段：集成与验证

目标： 合并所有 Agent 的输出，并验证集成结果。

1. 收集输出 — 汇总每个 Agent 的结果
2. 检查冲突 — 确认没有文件被多个 Agent 修改
3. 应用更改 — 将所有输出集成到代码库中
4. 运行集成检查 — 执行完整测试套件
5. 解决问题 — 如果集成失败，找出导致问题的 Agent 更改
6. 原子提交 — 要么一起提交所有更改，要么全部不提交

集成验证检查清单

检查项	命令	必须通过
没有文件冲突	比较共享文件的输出差异	是
测试通过	完整测试套件	是
构建通过	构建命令	是
Lint 通过	Lint 命令	是
没有回归问题	比较更改前后的测试数量	是

集成失败决策表

失败类型	诊断	操作
Agent 1 的文件中测试失败	Agent 1 的更改有错误	将测试失败的上下文提供给 Agent 1，然后重新分派（通过 Agent 工具）
不相关文件中的测试失败	跨模块回归	找出根本原因，手动修复或重新分派（通过 Agent 工具）
构建失败	导入／类型问题	检查是哪个 Agent 的更改导致问题，并进行修复
合并冲突	Agent 修改了同一文件（本不应发生）	回滚，并将这些任务串行执行

停止 — 在提交前不要继续，直到：

• 已收集所有 Agent 的输出
• 未发现文件冲突
• 完整测试套件通过
• 构建和 Lint 通过

---

常见并行模式

模式决策表

模式	使用场景	示例
按模块	独立的模块或软件包	每个微服务调用一次 Agent
按层	各层涉及不同的文件	API Agent、服务 Agent、数据 Agent
按功能领域	独立的垂直功能切片	身份验证 Agent、个人资料 Agent、计费 Agent
按任务类型	代码、测试、文档涉及不同的文件	代码 Agent、测试 Agent、文档 Agent

示例：完整分派

TASK: "Update the API to v2, add tests, and update OpenAPI spec"

AGENT 1 - API Routes:
  Scope: Update route handlers in src/routes/v2/
  Context: [v2 API spec, breaking changes list]
  Output: Modified files list, breaking changes implemented
  Constraints: Do NOT touch tests or docs

AGENT 2 - Tests:
  Scope: Write tests in tests/v2/
  Context: [v2 API spec, test conventions, existing v1 tests as reference]
  Output: New test files, coverage summary
  Constraints: Do NOT modify source code

AGENT 3 - OpenAPI Spec:
  Scope: Update openapi/v2.yaml
  Context: [v2 API spec, OpenAPI 3.1 format]
  Output: Updated spec file
  Constraints: Do NOT modify code or tests

---

反模式 / 常见错误

反模式	失败原因	正确做法
两个 Agent 修改同一个文件	合并冲突、数据丢失	每次 Agent 调度指定一个文件负责人
Agent 之间共享可变状态	竞态条件、状态不一致	消除共享状态
提示词中的上下文不完整	Agent 会自行探索并相互干扰	提供所有所需上下文
文件边界模糊	Agent 会猜测范围并修改错误的文件	在约束中明确列出文件
完成后不进行集成检查	跨模块错误无法被发现	集成后运行完整测试套件
将有先后顺序的任务并行化	Agent B 需要 Agent A 的输出	先确认任务彼此独立
不跟踪每个 Agent 修改了哪些文件	无法诊断集成失败	维护调度跟踪表
调度过多 Agent（10 个以上）	协调开销超过节省的时间	每轮调度使用 2-5 次 Agent 调用
跳过回滚准备	无法从集成失败中恢复	保留可恢复的调度前状态

---

防止合理化的防护措施

不要调度（通过 `Agent` 工具）修改同一个文件的 Agent。不要将有数据依赖的任务并行化。不要跳过集成验证。如果不满足独立性标准，就按顺序执行任务。

如果发现自己在想：

• “这些 Agent 大概不会冲突……”——先验证，不要想当然。
• “集成应该没问题……”——运行完整测试套件，始终如此。
• “我可以手动合并它们对同一文件的修改……”——不行。一个文件只能有一个负责人。

---

集成点

技能	关系	时机
task-decomposition	上游——识别相互独立的任务集群	调度前
subagent-driven-development	互补——提供审查关卡	用于 Agent 输出的质量关卡
executing-plans	上游——可能委派相互独立的任务	执行计划期间
verification-before-completion	下游——验证集成结果	集成后
code-review	下游——审查集成后的变更	所有 Agent 完成后
resilient-execution	失败时——重试失败的 Agent	单个 Agent 失败时

---

并行安全规则摘要

规则	理由
不允许两个 Agent 修改同一个文件	防止合并冲突和竞态条件
不共享可变状态	消除数据竞争
为每个 Agent 提供完整上下文	防止 Agent 自行探索并相互干扰
明确定义文件边界	确保所有权清晰无歧义
完成后审查集成结果	发现跨模块问题
所有变更原子提交	要么全部提交，要么全部不提交
始终保留回滚途径	保留可恢复的调度前状态

---

技能类型

RIGID——严格遵循此流程。必须验证独立性。必须包含全部四个提示词部分。必须进行集成验证。并行安全方面不得走捷径。