Back to Details

dispatching-parallel-agents

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Dispatching Parallel Agents

并行Agent调度

Operator Context

操作者上下文

This skill operates as an operator for parallel dispatch workflows, configuring Claude's behavior for concurrent investigation of independent problems. It implements the Fan-Out / Fan-In architectural pattern -- dispatch isolated agents, collect results, integrate -- with Domain Separation ensuring agents never interfere with each other.
本技能作为并行调度工作流的操作者，配置Claude的行为以并行排查独立问题。它实现了Fan-Out / Fan-In（扇出/扇入）架构模式——调度独立Agent、收集结果、整合——并通过领域隔离确保Agent之间互不干扰。

Hardcoded Behaviors (Always Apply)

硬编码行为（始终生效）

  • CLAUDE.md Compliance: Read and follow repository CLAUDE.md before dispatching agents
  • Over-Engineering Prevention: Fix only what is broken. No speculative improvements across domains
  • Independence Verification: MUST confirm problems are independent before parallel dispatch
  • Single Message Dispatch: MUST launch all parallel agents in ONE message for true concurrency
  • Scoped Prompts: Each agent MUST receive explicit scope, constraints, and expected output
  • Post-Integration Verification: MUST run full test suite after all agents return
  • CLAUDE.md合规性：调度Agent前需阅读并遵循仓库中的CLAUDE.md
  • 防止过度设计：仅修复已损坏的部分，不得跨领域进行推测性改进
  • 独立性验证：并行调度前必须确认问题是相互独立的
  • 单消息调度：必须在一条消息中启动所有并行Agent以实现真正的并发
  • 范围明确的提示词：每个Agent必须收到明确的范围、约束条件和预期输出
  • 集成后验证：所有Agent返回结果后必须运行完整测试套件

Default Behaviors (ON unless disabled)

默认行为（默认开启，可禁用）

  • Conflict Detection: Check if agents modified overlapping files after completion
  • Prompt Template: Use structured prompt with scope, goal, constraints, and output format
  • Summary Collection: Require each agent to return root cause and files modified
  • Maximum Parallelism: Cap at 10 concurrent agents to avoid coordination overhead
  • Result Spot-Check: Verify at least one agent's fix manually before declaring done
  • Sequential Fallback: If agents report same root cause, stop and investigate holistically
  • 冲突检测：完成后检查Agent是否修改了重叠文件
  • 提示词模板：使用包含范围、目标、约束条件和输出格式的结构化提示词
  • 结果汇总收集：要求每个Agent返回根本原因和修改的文件
  • 最大并行数：限制最多10个并发Agent以避免协调开销
  • 结果抽样检查：在宣布完成前手动验证至少一个Agent的修复
  • 顺序回退：如果Agent报告相同根本原因，则停止并整体排查

Optional Behaviors (OFF unless enabled)

可选行为（默认关闭，需启用）

  • Dependency Graph: Map subsystem dependencies before dispatching
  • Resource Isolation: Assign exclusive file/port ranges to each agent
  • Retry on Failure: Re-dispatch failed agents with additional context
  • 依赖关系图：调度前绘制子系统依赖关系图
  • 资源隔离：为每个Agent分配专属的文件/端口范围
  • 失败重试：重新调度失败的Agent并提供额外上下文

What This Skill CAN Do

本技能可实现的功能

  • Dispatch multiple agents to work on independent problems concurrently
  • Reduce total investigation time proportional to number of independent problems
  • Detect conflicts between agent fixes during integration
  • Provide structured prompts that keep agents focused on their domain
  • Integrate results and verify the combined fix
  • 调度多个Agent并发处理独立问题
  • 根据独立问题的数量成比例减少总排查时间
  • 整合过程中检测Agent修复之间的冲突
  • 提供结构化提示词，确保Agent专注于各自领域
  • 整合结果并验证组合修复方案

What This Skill CANNOT Do

本技能不可实现的功能

  • Parallelize problems that share state or root cause
  • Guarantee agents will not edit overlapping files
  • Replace systematic debugging for single complex bugs (use systematic-debugging instead)
  • Plan implementation work (use workflow-orchestrator instead)
  • Execute sequential dependent tasks (use subagent-driven-development instead)
  • 并行处理共享状态或具有相同根本原因的问题
  • 保证Agent不会修改重叠文件
  • 替代针对单个复杂Bug的系统化调试（请使用systematic-debugging技能）
  • 规划实现工作（请使用workflow-orchestrator技能）
  • 执行顺序依赖任务（请使用subagent-driven-development技能）

Instructions

操作步骤

Phase 1: CLASSIFY

阶段1：分类

Goal: Determine whether problems are independent and suitable for parallel dispatch.
Step 1: List all problems
markdown
undefined
目标：确定问题是否独立，是否适合并行调度。
步骤1：列出所有问题
markdown
undefined

Problems Identified

已识别的问题

  1. [Problem A] - [Subsystem] - [Error summary]
  2. [Problem B] - [Subsystem] - [Error summary]
  3. [Problem C] - [Subsystem] - [Error summary]

**Step 2: Test independence**

For each pair of problems, ask: "If I fix problem A, does it affect problem B?"
- If NO for all pairs --> Independent, proceed to parallel dispatch
- If YES or MAYBE for any pair --> Investigate those together first, parallelize the rest

**Step 3: Verify no shared state**

Check that agents will not compete for:
- Same source files
- Same database tables or ports
- Same configuration files
- Same external services

**Gate**: All dispatched problems confirmed independent with no shared state. Proceed only when gate passes.
  1. [问题A] - [子系统] - [错误摘要]
  2. [问题B] - [子系统] - [错误摘要]
  3. [问题C] - [子系统] - [错误摘要]

**步骤2：测试独立性**

针对每对问题，提问：「如果我修复了问题A，是否会影响问题B？」
- 若所有配对的答案均为「否」→ 问题独立，可进行并行调度
- 若任意配对的答案为「是」或「可能」→ 先共同排查这些问题，其余问题并行处理

**步骤3：验证无共享状态**

检查Agent是否不会竞争以下资源：
- 相同的源文件
- 相同的数据库表或端口
- 相同的配置文件
- 相同的外部服务

**准入条件**：所有待调度问题均被确认独立且无共享状态。仅当满足条件时方可继续。

Phase 2: DISPATCH

阶段2：调度

Goal: Launch focused agents with clear scope in a single message.
Step 1: Create agent prompts
Each agent prompt MUST include:
markdown
Fix [N] failing tests in [FILE/SUBSYSTEM]:

1. "[Specific failure]" - [error summary]
2. "[Specific failure]" - [error summary]

Context: [What this subsystem does]

Your task:
1. Read the relevant code and understand what it does
2. Identify root cause - is this a code issue or test issue?
3. Fix the issue (prefer fixing implementation over changing test expectations)
4. Run tests to verify fix

Constraints:
- Only modify files in [SCOPE]
- Do NOT change [OUT OF SCOPE FILES]

Return:
- Root cause (1-2 sentences)
- Files modified
- How to verify the fix
Step 2: Dispatch all agents in ONE message
Use multiple Task tool calls in a single response. All agents run concurrently.
Gate: All agents dispatched with scoped prompts and constraints. Proceed only when all agents return.
目标：在一条消息中启动带有明确范围的聚焦Agent。
步骤1：创建Agent提示词
每个Agent的提示词必须包含：
markdown
修复[FILE/SUBSYSTEM]中的[N]个失败测试：

1. "[具体故障]" - [错误摘要]
2. "[具体故障]" - [错误摘要]

上下文：[本子系统的功能]

你的任务：
1. 阅读相关代码并理解其功能
2. 确定根本原因——是代码问题还是测试问题？
3. 修复问题（优先修复实现代码而非修改测试预期）
4. 运行测试以验证修复

约束条件：
- 仅修改[SCOPE]范围内的文件
- 不得修改[OUT OF SCOPE FILES]

返回内容：
- 根本原因（1-2句话）
- 修改的文件
- 验证修复的方法
步骤2：在一条消息中调度所有Agent
在单个响应中使用多个Task工具调用。所有Agent并发运行。
准入条件：所有Agent均已通过范围明确的提示词和约束条件调度。仅当所有Agent返回结果后方可继续。

Phase 3: INTEGRATE

阶段3：整合

Goal: Combine agent results, detect conflicts, verify combined fix.
Step 1: Read each agent summary
  • What was the root cause?
  • What files were modified?
  • Did the agent's local tests pass?
Step 2: Check for conflicts
  • Did any two agents modify the same file?
  • Did any agent report the same root cause as another?
  • Did any agent report inability to reproduce?
If conflicts detected: Do NOT auto-merge. Understand which fix is correct. May need sequential re-investigation.
Step 3: Run full test suite
Execute the complete test suite to verify all fixes work together without regressions.
Step 4: Spot-check at least one fix
Read the actual code change from one agent and verify it makes sense.
Gate: Full suite passes, no conflicts, fixes verified. Proceed only when gate passes.
目标：合并Agent结果，检测冲突，验证组合修复方案。
步骤1：阅读每个Agent的摘要
  • 根本原因是什么？
  • 修改了哪些文件？
  • Agent本地的测试是否通过？
步骤2：检查冲突
  • 是否有两个Agent修改了同一个文件？
  • 是否有Agent报告了与其他Agent相同的根本原因？
  • 是否有Agent报告无法复现问题？
若检测到冲突：请勿自动合并。确定哪个修复是正确的。可能需要重新进行顺序排查。
步骤3：运行完整测试套件
执行完整测试套件以验证所有修复组合后不会出现回归问题。
步骤4：抽样检查至少一个修复
查看一个Agent的实际代码变更，确认其合理性。
准入条件：完整测试套件通过，无冲突，修复已验证。仅当满足条件时方可继续。

Phase 4: REPORT

阶段4：报告

Goal: Document what was fixed and how.
markdown
undefined
目标：记录修复内容及方式。
markdown
undefined

Parallel Dispatch Summary

并行调度摘要

Agents dispatched: [N] Problems resolved: [N]
调度的Agent数量：[N] 解决的问题数量：[N]

Agent 1: [Subsystem]

Agent 1：[子系统]

  • Root cause: [description]
  • Files: [list]
  • 根本原因：[描述]
  • 文件：[列表]

Agent 2: [Subsystem]

Agent 2：[子系统]

  • Root cause: [description]
  • Files: [list]
Integration: [No conflicts / Conflicts resolved by...] Verification: Full test suite passes

**Gate**: Summary documented. Task complete.

---
  • 根本原因：[描述]
  • 文件：[列表]
整合情况：[无冲突 / 冲突已通过...解决] 验证情况：完整测试套件通过

**准入条件**：摘要已记录。任务完成。

---

Error Handling

错误处理

Error: "Agents Report Same Root Cause"

错误：「Agent报告相同根本原因」

Cause: Problems were not actually independent; shared underlying issue Solution: Stop parallel execution. Consolidate into single investigation using systematic-debugging skill. The shared root cause must be fixed once, not independently.
原因：问题并非真正独立；存在共享的潜在问题 解决方案：停止并行执行。使用systematic-debugging技能将问题合并为单个排查任务。共享根本原因只需修复一次，无需独立修复。

Error: "Agent Fixes Break Other Agent's Tests"

错误：「Agent的修复破坏了其他Agent的测试」

Cause: Hidden dependency between subsystems; agents modified shared code paths Solution: Revert conflicting changes. Re-investigate the conflicting pair sequentially. Apply the combined fix, then re-run remaining agents if needed.
原因：子系统之间存在隐藏依赖；Agent修改了共享代码路径 解决方案：回滚冲突变更。重新对冲突的问题对进行顺序排查。应用组合修复方案后，若有需要再重新运行其余Agent。

Error: "Agent Cannot Reproduce Problem"

错误：「Agent无法复现问题」

Cause: Problem depends on state from another subsystem, or environment mismatch Solution: Provide additional context. If still cannot reproduce, the problem may not be independent -- move it to a sequential investigation.
原因：问题依赖于其他子系统的状态，或环境不匹配 解决方案：提供额外上下文。若仍无法复现，该问题可能并非独立——将其移至顺序排查任务。

Error: "Worktree Agent Commits to Wrong Branch"

错误：「工作区Agent提交至错误分支」

Cause: When multiple worktrees exist, agents may operate on an unexpected branch because the worktree's branch and push target can diverge. Solution:
  1. In each agent's dispatch prompt, explicitly state the target branch name
  2. Include 
    git branch --show-current
    as the first verification step in each agent
  3. After all agents return, verify each commit landed on the intended branch
  4. If a commit landed on the wrong branch, cherry-pick to the correct branch and reset Graduated from learning.db — multi-agent-coordination/worktree-branch-confusion
原因：当存在多个工作区时，Agent可能在意外分支上操作，因为工作区的分支和推送目标可能不一致。 解决方案：
  1. 在每个Agent的调度提示词中明确指定目标分支名称
  2. 在每个Agent的第一步验证步骤中加入
    git branch --show-current
  3. 所有Agent返回后，验证每个提交是否落在预期分支上
  4. 若提交落在错误分支，将其樱桃拣选（cherry-pick）至正确分支并重置原分支 来自learning.db — multi-agent-coordination/worktree-branch-confusion

Anti-Patterns

反模式

Anti-Pattern 1: Parallelizing Related Problems

反模式1：并行处理相关问题

What it looks like: Dispatching agents for failures that share a root cause Why wrong: Multiple agents fix the same thing differently, creating conflicts Do instead: Test independence first. If unsure, investigate sequentially.
表现：为具有相同根本原因的故障调度Agent 危害：多个Agent以不同方式修复同一问题，导致冲突 正确做法：先测试独立性。若不确定，进行顺序排查。

Anti-Pattern 2: Vague Agent Prompts

反模式2：模糊的Agent提示词

What it looks like: "Fix the failing tests" with no scope or constraints Why wrong: Agent wanders, modifies out-of-scope files, takes too long Do instead: Use the structured prompt template with explicit scope and constraints.
表现：仅使用「修复失败的测试」等无范围或约束的提示词 危害：Agent偏离方向，修改范围外文件，耗时过长 正确做法：使用包含明确范围和约束的结构化提示词模板。

Anti-Pattern 3: Skipping Integration Verification

反模式3：跳过整合验证

What it looks like: "All agents reported success, we're done!" Why wrong: Individual fixes may conflict or introduce cross-subsystem regressions Do instead: Run full test suite after all agents return. Spot-check at least one fix.
表现：「所有Agent报告修复完成，任务结束！」 危害：单独的修复可能存在冲突或引入跨子系统的回归问题 正确做法：所有Agent返回后运行完整测试套件。抽样检查至少一个修复。

Anti-Pattern 4: Dispatching Before Understanding

反模式4：未理解就调度

What it looks like: Immediately parallelizing without confirming independence Why wrong: Wastes agent effort; conflicting fixes require rework Do instead: Complete Phase 1 classification. Independence verification is not optional.
表现：未确认独立性就立即并行处理 危害：浪费Agent资源；冲突修复需要返工 正确做法：完成阶段1的分类。独立性验证是必选步骤，不可跳过。

References

参考资料

This skill uses these shared patterns:
  • Anti-Rationalization - Prevents shortcut rationalizations
  • Verification Checklist - Pre-completion checks
本技能使用以下共享模式：
  • 反合理化 - 防止捷径式合理化
  • 验证清单 - 完成前检查

Domain-Specific Anti-Rationalization

领域特定反合理化

RationalizationWhy It's WrongRequired Action
"These problems look independent"Looking ≠ verified independenceTest each pair explicitly
"Agent said it's fixed"Agent report ≠ integrated verificationRun full test suite
"No conflicts in file list"File-level ≠ logic-level conflictSpot-check actual changes
"Too many problems to classify"Skipping classification causes reworkClassify all before dispatch
合理化说法错误原因要求操作
「这些问题看起来是独立的」看起来≠已验证的独立性明确测试每对问题
「Agent说已修复」Agent报告≠整合验证运行完整测试套件
「文件列表中无冲突」文件级≠逻辑级冲突抽样检查实际变更
「问题太多无法分类」跳过分类会导致返工调度前完成所有分类