dispatching-parallel-agents
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseDispatching Parallel Agents
并行Agent调度
Overview
概述
This skill coordinates multiple agents working concurrently on independent subtasks to reduce total execution time while maintaining correctness. It provides strict rules for identifying safe parallelization opportunities, writing focused agent prompts, and integrating results without conflicts. The key constraint is that no two agents may modify the same file.
Announce at start: "I'm using the dispatching-parallel-agents skill to run [N] independent tasks concurrently."
本技能用于协调多个Agent在独立子任务上并发工作，在保证正确性的同时减少总执行时间。它提供了严格的规则，用于识别安全的并行化机会、编写聚焦的Agent提示词，以及无冲突地整合结果。核心约束是：任意两个Agent不得修改同一文件。
启动时声明: "我正在使用dispatching-parallel-agents技能并发运行[N]个独立任务。"
Agent Tool Reference
Agent工具参考
All dispatch uses the tool. Parameters:
Agent- (required) — task description with full context
prompt - (required) — short label (3-5 words)
description - —
subagent_type(codebase search),"Explore"(architecture),"Plan"(default)"general-purpose" - —
run_in_backgroundfor async (you'll be notified on completion)true - — optional override:
model,"sonnet","opus""haiku"
Parallel: Multiple calls in one message run concurrently.
Background: for non-blocking work.
Named agents: Use to reference installed agent templates (e.g., ).
Agentrun_in_background=truesubagent_type"superpowers:code-reviewer"所有调度都使用工具，参数如下：
Agent- （必填）—— 包含完整上下文的任务描述
prompt - （必填）—— 简短标签（3-5个词）
description - ——
subagent_type（代码库搜索）,"Explore"（架构设计）,"Plan"（默认值）"general-purpose" - —— 异步执行时设为
run_in_background（完成后会收到通知）true - —— 可选覆盖模型：
model,"sonnet","opus""haiku"
并行执行： 同一条消息中多次调用即可并发运行。
后台执行： 设置实现非阻塞工作。
命名Agent： 使用引用已安装的Agent模板（例如）。
Agentrun_in_background=truesubagent_type"superpowers:code-reviewer"Trigger Conditions
触发条件
- A task decomposes into 2+ subtasks with no data dependencies between them
- Each subtask operates on different files or different sections of the codebase
- The combined result can be assembled after all agents complete
- Total serial time would be significantly longer than parallel time
- output reveals independent task clusters
/decompose
- 一个任务可拆解为2个及以上互相无数据依赖的子任务
- 每个子任务操作不同文件或代码库的不同区块
- 所有Agent执行完成后可合并输出结果
- 串行执行总时间显著长于并行执行时间
- 输出显示存在独立的任务集群
/decompose
Phase 1: Independence Verification
阶段1：独立性验证
Goal: Confirm subtasks are truly independent and safe to parallelize.
Every subtask must satisfy ALL four independence criteria:
| Criterion | Question | If NO |
|---|---|---|
| No shared files | Do any two agents write to the same file? | Serialize those tasks |
| No shared mutable state | Does any agent depend on a side effect of another? | Serialize dependent tasks |
| Self-contained context | Can each agent work with only its own inputs? | Provide more context or serialize |
| Independent verification | Can each agent's output be validated alone? | Combine into single task |
目标： 确认子任务完全独立，可安全并行执行。
每个子任务必须满足全部四项独立性标准：
| 标准 | 验证问题 | 不满足时处理 |
|---|---|---|
| 无共享文件 | 是否有两个Agent会写入同一个文件？ | 串行执行这些任务 |
| 无共享可变状态 | 某个Agent是否依赖另一个Agent的副作用输出？ | 串行执行存在依赖的任务 |
| 上下文自包含 | 每个Agent是否仅靠自身输入即可完成工作？ | 提供更多上下文或串行执行 |
| 可独立验证 | 每个Agent的输出是否可以单独校验？ | 合并为单个任务 |
Parallelization Decision Table
并行化决策表
| Scenario | Parallelize? | Reason |
|---|---|---|
| Different files, different concerns | Yes | No conflict possible |
| Same module, different files | Yes (careful) | Verify no shared imports change |
| Same file, different sections | No | Merge conflicts inevitable |
| Task B uses Task A's output | No | Sequential dependency |
| Both read same files, write different | Yes | Reads are safe to parallelize |
| Both modify shared config file | No | Config conflicts |
| Independent test files | Yes | Tests are independent |
| One agent adds dep, another uses it | No | Package-level dependency |
| 场景 | 是否可以并行？ | 原因 |
|---|---|---|
| 不同文件、不同业务域 | 是 | 不可能产生冲突 |
| 同一模块、不同文件 | 是（需谨慎） | 确认无共享的导入内容会被修改 |
| 同一文件、不同区块 | 否 | 合并冲突不可避免 |
| 任务B依赖任务A的输出 | 否 | 存在顺序依赖 |
| 均读取相同文件、写入不同文件 | 是 | 读取操作可安全并行 |
| 均修改共享配置文件 | 否 | 会产生配置冲突 |
| 独立的测试文件 | 是 | 测试用例互相独立 |
| 一个Agent添加依赖，另一个Agent使用该依赖 | 否 | 存在包级别依赖 |
When NOT to Parallelize
不可并行的场景
- Subtasks share mutable state or modify the same files
- Task B depends on the output of Task A
- The overhead of coordination exceeds the time saved
- A single agent can complete the work in under 30 seconds
- The task requires iterative refinement where each step informs the next
STOP — Do NOT dispatch agents (via the tool) until:
Agent- All four independence criteria verified for every subtask pair
- No two agents write to the same file
- Each agent's context is self-contained
- 子任务共享可变状态或修改同一文件
- 任务B依赖任务A的输出
- 协调开销超过并行节省的时间
- 单个Agent可在30秒内完成全部工作
- 任务需要迭代优化，每一步的输出会影响下一步执行
暂停 — 满足以下条件前请勿（通过工具）调度任务：
Agent- 所有子任务对均通过四项独立性标准验证
- 没有两个Agent会写入同一文件
- 每个Agent的上下文都是自包含的
Phase 2: Prompt Construction
阶段2：提示词构建
Goal: Write focused, unambiguous prompts that prevent scope creep and conflicts.
Each agent prompt MUST contain exactly four sections:
目标： 编写聚焦、无歧义的提示词，避免范围蔓延和冲突。
每个Agent的提示词必须严格包含四个部分：
Section 1: Scope (What to Do)
部分1：范围（要做什么）
Be specific about the exact task, files, and expected changes.
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.明确说明具体任务、涉及文件和预期变更。
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.Section 2: Context (Everything Needed)
部分2：上下文（所需全部信息）
Provide all information the agent needs without requiring it to explore.
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 })提供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 })Section 3: Output Format (What to Return)
部分3：输出格式（要返回什么）
Define exactly what the agent should produce.
OUTPUT: For each modified file, return:
1. The file path
2. A summary of changes made
3. Number of console.log calls replaced明确定义Agent需要产出的内容。
OUTPUT: For each modified file, return:
1. The file path
2. A summary of changes made
3. Number of console.log calls replacedSection 4: Constraints (What NOT to Do)
部分4：约束（不能做什么）
Prevent scope creep and conflicts explicitly.
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明确禁止范围蔓延和冲突操作。
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 itAgent Prompt Template
Agent提示词模板
You are a focused agent with a single task.You are a focused agent with a single task.Scope
Scope
[Specific task description with exact files]
[Specific task description with exact files]
Context
Context
[All information needed to complete the task]
[Relevant code patterns, APIs, conventions]
[All information needed to complete the task]
[Relevant code patterns, APIs, conventions]
Output Format
Output Format
[Exact structure of what to return]
[Exact structure of what to return]
Constraints
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
undefined- 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
undefinedPrompt Quality Checklist
提示词质量检查清单
| Check | Question |
|---|---|
| Scope is specific | Can the agent complete the task without guessing? |
| Context is complete | Does the agent need to explore the codebase? (should be no) |
| Output is defined | Will the agent return what you need to integrate? |
| Constraints are explicit | Are file boundaries and "do NOT" items clear? |
STOP — Do NOT dispatch (via the tool) until:
Agent- Every prompt has all 4 sections
- No prompt requires the agent to explore beyond provided context
- File boundaries are explicit in every constraint section
| 检查项 | 验证问题 |
|---|---|
| 范围明确 | Agent无需猜测即可完成任务吗？ |
| 上下文完整 | Agent不需要额外探索代码库吗？（应为否） |
| 输出定义清晰 | Agent返回的内容可直接用于整合吗？ |
| 约束明确 | 文件边界和“禁止”项是否清晰？ |
暂停 — 满足以下条件前请勿（通过工具）调度任务：
Agent- 每个提示词都包含全部四个部分
- 没有提示词要求Agent探索提供的上下文之外的内容
- 每个约束部分都明确标注了文件边界
Phase 3: Dispatch and Monitor
阶段3：调度与监控
Goal: Launch all agents (via the tool) concurrently and track completion.
Agent- Launch all agents concurrently by invoking multiple tool calls in a single message
Agent - Each agent works in isolation on its designated files
- Monitor for completion — wait for ALL agents to finish
- Collect outputs from every agent
目标： 并发启动所有Agent（通过工具）并跟踪完成情况。
Agent- 在同一条消息中调用多次工具，并发启动所有任务
Agent - 每个Agent在指定文件上独立工作
- 监控执行进度 —— 等待所有Agent执行完成
- 收集每个Agent的输出结果
Dispatch Tracking Table
调度跟踪表
| 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 | 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 | — |Failure Handling During Dispatch
调度过程中的故障处理
| Scenario | Action |
|---|---|
| One agent fails, others succeed | Retry failed agent independently (via the |
| Multiple agents fail independently | Retry each independently (via the |
| Agent reports out-of-scope issue | Note for post-integration review |
| Agent exceeds scope (modifies wrong files) | Reject output, re-dispatch (via the |
| 场景 | 处理方式 |
|---|---|
| 一个Agent执行失败，其他成功 | 单独重试失败的Agent（通过 |
| 多个Agent独立执行失败 | 分别单独重试每个Agent（通过 |
| Agent上报范围外的问题 | 记录下来，留待集成后审核 |
| 超出执行范围（修改了错误的文件） | 拒绝输出，使用更严格的约束重新调度（通过 |
Phase 4: Integration and Verification
阶段4：集成与验证
Goal: Combine all agent outputs and verify the integrated result.
- Collect outputs — Gather results from every agent
- Check for conflicts — Verify no file was modified by multiple agents
- Apply changes — Integrate all outputs into the codebase
- Run integration checks — Execute the full test suite
- Resolve issues — If integration fails, identify which agent's changes caused it
- Commit atomically — All changes go in together or not at all
目标： 合并所有Agent的输出并验证集成结果。
- 收集输出 —— 汇总每个Agent的执行结果
- 冲突检查 —— 确认没有文件被多个Agent修改
- 应用变更 —— 将所有输出集成到代码库中
- 运行集成检查 —— 执行完整的测试套件
- 问题解决 —— 如果集成失败，定位是哪个Agent的变更导致的
- 原子提交 —— 所有变更要么全部生效，要么全部回滚
Integration Verification Checklist
集成验证检查清单
| Check | Command | Must Pass |
|---|---|---|
| No file conflicts | Diff outputs for shared files | Yes |
| Tests pass | Full test suite | Yes |
| Build passes | Build command | Yes |
| Lint passes | Lint command | Yes |
| No regressions | Compare test count before/after | Yes |
| 检查项 | 执行命令 | 必须通过 |
|---|---|---|
| 无文件冲突 | 对比共享文件的diff输出 | 是 |
| 测试通过 | 完整测试套件 | 是 |
| 构建通过 | 构建命令 | 是 |
| 语法检查通过 | Lint命令 | 是 |
| 无功能回退 | 对比变更前后的测试用例数量 | 是 |
Integration Failure Decision Table
集成失败决策表
| Failure Type | Diagnosis | Action |
|---|---|---|
| Test failure in Agent 1's files | Agent 1's changes have a bug | Re-dispatch Agent 1 (via the |
| Test failure in unrelated files | Cross-cutting regression | Identify root cause, fix manually or re-dispatch (via the |
| Build failure | Import/type issue | Check which agent's changes caused it, fix |
| Merge conflict | Agents touched same file (should not happen) | Rollback, serialize those tasks |
STOP — Do NOT commit until:
- All agent outputs collected
- No file conflicts detected
- Full test suite passes
- Build and lint pass
| 故障类型 | 诊断 | 处理方式 |
|---|---|---|
| Agent1负责的文件测试失败 | Agent1的变更存在bug | 携带测试失败上下文重新调度Agent1（通过 |
| 无关文件测试失败 | 跨域功能回退 | 定位根因，手动修复或重新调度（通过 |
| 构建失败 | 导入/类型问题 | 定位是哪个Agent的变更导致的，修复问题 |
| 合并冲突 | Agent修改了同一文件（本应避免） | 回滚变更，串行执行这些任务 |
暂停 — 满足以下条件前请勿提交：
- 已收集所有Agent的输出
- 未检测到文件冲突
- 完整测试套件执行通过
- 构建和语法检查通过
Common Parallel Patterns
常见并行模式
Pattern Decision Table
模式决策表
| Pattern | When to Use | Example |
|---|---|---|
| By Module | Independent modules or packages | One |
| By Layer | Layers touch different files | API agent, service agent, data agent |
| By Feature Area | Independent vertical slices | Auth agent, profile agent, billing agent |
| By Task Type | Code, tests, docs touch different files | Code agent, test agent, docs agent |
| 模式 | 使用场景 | 示例 |
|---|---|---|
| 按模块拆分 | 独立模块或包 | 每个微服务对应一次 |
| 按层级拆分 | 不同层级操作不同文件 | API Agent、服务层Agent、数据层Agent |
| 按功能域拆分 | 独立的垂直业务切片 | 认证Agent、用户资料Agent、计费Agent |
| 按任务类型拆分 | 代码、测试、文档操作不同文件 | 编码Agent、测试Agent、文档Agent |
Example: Full Dispatch
示例：完整调度流程
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 testsTASK: "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 testsAnti-Patterns / Common Mistakes
反模式/常见错误
| Anti-Pattern | Why It Fails | Correct Approach |
|---|---|---|
| Two agents modifying the same file | Merge conflicts, data loss | One file owner per |
| Shared mutable state between agents | Race conditions, inconsistency | Eliminate shared state |
| Incomplete context in prompts | Agents explore and step on each other | Provide ALL needed context |
| Vague file boundaries | Agents guess scope, modify wrong files | Explicit file lists in constraints |
| No integration check after completion | Cross-cutting bugs go undetected | Full test suite after integration |
| Parallelizing sequential tasks | Agent B needs Agent A's output | Verify independence first |
| Not tracking which agent touched which file | Cannot diagnose integration failures | Maintain dispatch tracking table |
| Dispatching too many agents (10+) | Coordination overhead exceeds savings | 2-5 |
| Skipping rollback preparation | Cannot recover from integration failure | Keep pre-dispatch state recoverable |
| 反模式 | 失败原因 | 正确做法 |
|---|---|---|
| 两个Agent修改同一文件 | 合并冲突、数据丢失 | 每次 |
| Agent间共享可变状态 | 竞态条件、数据不一致 | 消除共享状态 |
| 提示词上下文不完整 | Agent探索时互相干扰 | 提供全部所需上下文 |
| 文件边界模糊 | Agent猜测范围，修改错误文件 | 在约束中明确列出文件清单 |
| 完成后不做集成检查 | 跨域bug未被发现 | 集成后运行完整测试套件 |
| 并行化有顺序依赖的任务 | AgentB需要AgentA的输出 | 先验证独立性 |
| 不跟踪Agent修改的文件 | 无法定位集成失败原因 | 维护调度跟踪表 |
| 调度过多Agent（10个以上） | 协调开销超过收益 | 每轮调度执行2-5次 |
| 未准备回滚方案 | 集成失败后无法恢复 | 确保调度前的状态可恢复 |
Anti-Rationalization Guards
反合理化防护
<HARD-GATE>
Do NOT dispatch agents (via the `Agent` tool) that modify the same file. Do NOT parallelize tasks with data dependencies. Do NOT skip integration verification. If independence criteria are not met, serialize the tasks.
</HARD-GATE>
If you catch yourself thinking:
- "These agents probably won't conflict..." — Verify. Do not assume.
- "The integration will be fine..." — Run the full test suite. Always.
- "I can merge their changes to the same file manually..." — No. One file, one owner.
<HARD-GATE>
请勿调度（通过`Agent`工具）修改同一文件的Agent。请勿并行化存在数据依赖的任务。请勿跳过集成验证。如果不满足独立性标准，请串行执行任务。
</HARD-GATE>
如果你发现自己有以下想法：
- "这些Agent应该不会冲突吧..." —— 验证，不要假设。
- "集成应该没问题吧..." —— 始终运行完整测试套件。
- "我可以手动合并他们对同一文件的修改..." —— 不行，一个文件仅归一个负责人。
Integration Points
集成点
| Skill | Relationship | When |
|---|---|---|
| Upstream — identifies independent task clusters | Before dispatching |
| Complementary — provides review gates | Quality gates for agent output |
| Upstream — may delegate independent tasks | During plan execution |
| Downstream — verifies integrated result | After integration |
| Downstream — reviews integrated changes | After all agents complete |
| On failure — retries failed agents | When individual agents fail |
| 技能 | 关系 | 时机 |
|---|---|---|
| 上游技能 —— 识别独立任务集群 | 调度前 |
| 互补技能 —— 提供审核关卡 | Agent输出质量校验 |
| 上游技能 —— 可委托独立任务 | 计划执行期间 |
| 下游技能 —— 验证集成结果 | 集成后 |
| 下游技能 —— 审核集成后的变更 | 所有Agent执行完成后 |
| 故障处理技能 —— 重试失败的Agent | 单个Agent执行失败时 |
Parallelism Safety Rules Summary
并行安全规则汇总
| Rule | Rationale |
|---|---|
| No two agents modify the same file | Prevents merge conflicts and race conditions |
| No shared mutable state | Eliminates data races |
| Each agent gets complete context | Prevents agents from exploring and stepping on each other |
| Define file boundaries explicitly | Makes ownership unambiguous |
| Review integration after completion | Catches cross-cutting issues |
| Atomic commit for all changes | All in or all out |
| Always have a rollback path | Keep pre-dispatch state recoverable |
| 规则 | 逻辑 |
|---|---|
| 禁止两个Agent修改同一文件 | 避免合并冲突和竞态条件 |
| 禁止共享可变状态 | 消除数据竞态 |
| 每个Agent获取完整上下文 | 避免Agent探索时互相干扰 |
| 明确定义文件边界 | 明确所有权 |
| 完成后审核集成结果 | 发现跨域问题 |
| 所有变更原子提交 | 要么全部生效要么全部回滚 |
| 始终保留回滚路径 | 确保调度前的状态可恢复 |
Skill Type
技能类型
RIGID — Follow this process exactly. Independence verification is mandatory. All four prompt sections are mandatory. Integration verification is mandatory. No shortcuts on parallelism safety.
严格型 —— 必须严格遵循本流程。独立性验证为强制要求。提示词的四个部分为必填项。集成验证为强制要求。并行安全规则无捷径可走。