dispatching-parallel-agents

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Dispatching 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

Agent

tool. Parameters:

```
prompt
```
(required) — task description with full context
```
description
```
(required) — short label (3-5 words)

subagent_type

—

"Explore"

(codebase search),

"Plan"

(architecture),

"general-purpose"

(default)

```
run_in_background
```
—
```
true
```
for async (you'll be notified on completion)
```
model
```
— optional override:
```
"sonnet"
```
,
```
"opus"
```
,
```
"haiku"
```

Parallel: Multiple

Agent

calls in one message run concurrently. Background:

run_in_background=true

for non-blocking work. Named agents: Use

subagent_type

to reference installed agent templates (e.g.,

"superpowers:code-reviewer"

所有调度都使用

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"

）。

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
```
/decompose
```
output reveals independent task clusters

一个任务可拆解为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
Agent
tool) until:

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 replaced

Section 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 it

Agent Prompt Template

Agent提示词模板

You are a focused agent with a single task.

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

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

undefined

Prompt 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
Agent
tool) until:

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

Agent

tool) concurrently and track completion.

Launch all agents concurrently by invoking multiple
```
Agent
```
tool calls in a single message
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 `Agent` tool)
Multiple agents fail independently	Retry each independently (via the `Agent` tool)
Agent reports out-of-scope issue	Note for post-integration review
Agent exceeds scope (modifies wrong files)	Reject output, re-dispatch (via the `Agent` tool) with stricter constraints

场景	处理方式
一个Agent执行失败，其他成功	单独重试失败的Agent（通过 `Agent` 工具）
多个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 `Agent` tool) with test failure context
Test failure in unrelated files	Cross-cutting regression	Identify root cause, fix manually or re-dispatch (via the `Agent` tool)
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的变更导致的，修复问题
合并冲突	Agent修改了同一文件（本应避免）	回滚变更，串行执行这些任务

暂停 — 满足以下条件前请勿提交：

已收集所有Agent的输出
未检测到文件冲突
完整测试套件执行通过
构建和语法检查通过

Common Parallel Patterns

常见并行模式

Pattern Decision Table

模式决策表

Pattern	When to Use	Example
By Module	Independent modules or packages	One `Agent` call per microservice
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

模式	使用场景	示例
按模块拆分	独立模块或包	每个微服务对应一次 `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 tests

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

Anti-Patterns / Common Mistakes

反模式/常见错误

Anti-Pattern	Why It Fails	Correct Approach
Two agents modifying the same file	Merge conflicts, data loss	One file owner per `Agent` dispatch
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 `Agent` calls per dispatch round
Skipping rollback preparation	Cannot recover from integration failure	Keep pre-dispatch state recoverable

反模式	失败原因	正确做法
两个Agent修改同一文件	合并冲突、数据丢失	每次 `Agent` 调度中每个文件仅归一个Agent负责
Agent间共享可变状态	竞态条件、数据不一致	消除共享状态
提示词上下文不完整	Agent探索时互相干扰	提供全部所需上下文
文件边界模糊	Agent猜测范围，修改错误文件	在约束中明确列出文件清单
完成后不做集成检查	跨域bug未被发现	集成后运行完整测试套件
并行化有顺序依赖的任务	AgentB需要AgentA的输出	先验证独立性
不跟踪Agent修改的文件	无法定位集成失败原因	维护调度跟踪表
调度过多Agent（10个以上）	协调开销超过收益	每轮调度执行2-5次 `Agent` 调用
未准备回滚方案	集成失败后无法恢复	确保调度前的状态可恢复

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
`task-decomposition`	Upstream — identifies independent task clusters	Before dispatching
`subagent-driven-development`	Complementary — provides review gates	Quality gates for agent output
`executing-plans`	Upstream — may delegate independent tasks	During plan execution
`verification-before-completion`	Downstream — verifies integrated result	After integration
`code-review`	Downstream — reviews integrated changes	After all agents complete
`resilient-execution`	On failure — retries failed agents	When individual agents fail

技能	关系	时机
`task-decomposition`	上游技能 —— 识别独立任务集群	调度前
`subagent-driven-development`	互补技能 —— 提供审核关卡	Agent输出质量校验
`executing-plans`	上游技能 —— 可委托独立任务	计划执行期间
`verification-before-completion`	下游技能 —— 验证集成结果	集成后
`code-review`	下游技能 —— 审核集成后的变更	所有Agent执行完成后
`resilient-execution`	故障处理技能 —— 重试失败的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.

严格型 —— 必须严格遵循本流程。独立性验证为强制要求。提示词的四个部分为必填项。集成验证为强制要求。并行安全规则无捷径可走。