Parallel Agent

并行子代理编排指南

此 skill 处理 CLAUDE.md 基础并行规则覆盖不了的复杂场景。 基础并行（2-3 个独立搜索/分析）不需要读这里，直接执行。

零、快速决策（30 秒定策略）

需要并行写代码？
├─ 是 → 用 worktree 隔离（§二）
│       写同一文件？→ 合并为一个代理，不要并行
└─ 否（只读/分析）→ 直接 foreground 并行

需要分阶段？
├─ 先研究再动手 → 模式 A（§四）
├─ 先广搜再深挖 → 模式 B（§四）
└─ 各功能完全独立 → 模式 C（§四）

子代理数量？
├─ 2-3 个 → 直接编排
├─ 4-6 个 → 分批，每批 ≤4
└─ 7+ 个 → 重新拆解任务粒度，大概率设计有问题

---

一、Foreground vs Background 决策

| 场景 | 选择 | 原因 | |------|------|------| | 研究型（需要结果做下一步决策） | foreground | 必须等结果才能继续 | | 独立代码修改（互不影响） | background | 主线程可继续其他工作 | | 搜索/定位（用户在等答案） | foreground | 延迟敏感 | | 长时间构建/测试 | background | 不阻塞对话 | | 需要用户权限审批的操作 | foreground | background 会自动拒绝权限请求 |

关键约束：

• background 代理遇到权限请求会静默失败，涉及文件写入、命令执行时优先用 foreground
• 多个 background 代理同时运行时，等全部完成后统一汇总，不逐个转述

---

二、Worktree 隔离（并行写代码的关键）

当多个子代理需要同时修改代码时，直接并行会产生文件冲突。 解决方案：使用 isolation: "worktree" 让每个代理在独立 git 分支工作。

适用场景：

• 2+ 个子代理需要编辑文件（即使是不同文件，worktree 更安全）
• 并行开发多个独立功能点
• 需要隔离实验性修改

使用方式：

Agent({
  description: "修改用户模块",
  subagent_type: "general-purpose",
  isolation: "worktree",
  prompt: "在 src/modules/user/ 下添加..."
})

行为：

• 每个代理获得独立的工作目录副本
• 如果代理没有做任何修改，worktree 自动清理
• 如果有修改，返回结果中包含 worktree 路径和分支名
• 主线程负责合并各分支的修改

合并 worktree 分支的标准流程：

# 1. 查看子代理返回的分支名（从 Agent 结果中获取）
git branch  # 确认分支存在

# 2. 逐个合并（推荐，可控性高）
git merge  --no-edit
git merge  --no-edit

# 3. 如果有冲突，手动解决后
git add 
git commit

# 4. 合并完成后清理 worktree
git worktree remove 
git branch -d 

如果多个分支修改了同一文件的不同区域，git merge 通常能自动合并。 如果修改了同一区域，需要手动解决 — 这说明任务拆分粒度不够细。

非 git 环境的降级方案：

• worktree 仅在 git 仓库中可用
• 非 git 环境下，改为串行执行写代码的子代理（一个完成后再启动下一个）
• 只读/分析类子代理不受影响，仍可并行

---

三、Model 选择策略

按能力需求分级，而非绑定具体模型名（模型迭代时只需更新此表）：

| 能力需求 | 推荐 model | 典型子任务 | |---------|-----------|-----------| | 快速检索，无需推理 | 不指定（Explore 内置优化） | 文件定位、符号搜索 | | 低延迟格式转换 | haiku | JSON 提取、简单模板填充 | | 平衡分析与速度 | sonnet | 代码审查、文档摘要 | | 深度推理/复杂决策 | opus | 架构设计、多约束权衡 | | 代码编写/修改 | 不指定（继承主线程） | 保持与主线程一致的能力 |

成本感知： 5 个 opus 子代理 ≈ 主对话 token 消耗的 3-5 倍。 搜索/定位类任务用 Explore 或 haiku 可节省 80%+ 成本，且延迟更低。

使用方式：在 Agent 调用中加 model: "sonnet" 参数。不指定时继承主对话的模型。

---

四、分阶段并行编排

复杂任务通常不是"全部并行"，而是分阶段：每阶段内部并行，阶段之间串行。

模式 A：研究 → 决策 → 执行

阶段 1（并行研究，foreground）：
  Explore: 搜索现有实现模式
  claude-code-guide: 查阅框架文档
  Explore: 分析依赖关系

↓ 主线程汇总研究结果，制定修改方案 ↓
  （这一步不能委托 — "never delegate understanding"）

阶段 2（并行执行，foreground + worktree）：
  general-purpose: 修改模块 A（isolation: worktree）
  general-purpose: 修改模块 B（isolation: worktree）
  general-purpose: 更新相关测试（isolation: worktree）

↓ 主线程合并各 worktree 分支，验证结果 ↓

关键：阶段 2 的每个 prompt 必须包含阶段 1 的关键发现。 不要写"根据之前的研究来修改" — 子代理看不到之前的上下文。

模式 B：广度搜索 → 深度分析

阶段 1（并行广度搜索）：
  Explore(quick): 在 src/ 下搜索关键词 X
  Explore(quick): 在 tests/ 下搜索关键词 X
  Explore(quick): 在 config/ 下搜索关键词 X

↓ 主线程确定目标文件 ↓

阶段 2（并行深度分析）：
  code-explorer: 追踪 fileA.ts 的调用链
  code-explorer: 追踪 fileB.ts 的调用链

模式 C：独立功能并行开发

同时进行（background + worktree）：
  general-purpose: 实现功能 A（独立分支）
  general-purpose: 实现功能 B（独立分支）
  general-purpose: 编写功能 C（独立分支）

↓ 全部完成后，主线程逐个审查并合并 ↓

子代理间数据传递

当阶段 2 的代理 B 需要代理 A 的部分输出时：

• 方案 1（推荐）：主线程中转 — A 完成后，主线程提取关键信息，写入 B 的 prompt
• 方案 2：文件中转 — A 将结果写入约定路径（如 /tmp/agent-a-output.json），B 的 prompt 中指定读取该文件
• 方案 3：重新设计 — 如果 A/B 有数据依赖，它们可能不该并行，改为串行

判断标准：如果 B 只需要 A 的 1-2 个结论 → 方案 1；需要 A 的完整输出 → 方案 2；需要 A 的中间推理过程 → 方案 3。

---

五、子代理类型选择

选择代理类型时要理解每种类型的真实能力边界：

| 子任务 | 推荐类型 | 能力边界 | |--------|---------|---------| | 定位文件/符号 | Explore(quick) | 只读摘录，超出读取窗口的内容会丢失 | | 跨多目录搜索 | Explore(very thorough) | 广度搜索，但仍是摘录而非全文 | | 深度代码追踪 | feature-dev:code-explorer | 能追踪调用链，但不能写代码 | | 代码审查 | feature-dev:code-reviewer | 只读分析，不能修复 | | 架构蓝图 | feature-dev:code-architect | 出方案，不能实施 | | 写代码/修改文件 | general-purpose | 完整工具集，能读写执行 | | 查框架/API 文档 | claude-code-guide | 专精文档查询，不能写代码 |

Explore 的关键限制：它读的是摘录而非完整文件。不要用它做：

• 代码审查（会漏掉上下文）
• 跨文件一致性检查
• 开放式分析（"看看这个模块怎么样"）

需要完整阅读文件时，用 general-purpose 或 code-explorer。

---

六、结果验证（Trust but Verify）

子代理的返回摘要描述的是它"打算做什么"，不是"实际做了什么"。

验证清单：

1. 如果子代理写了代码 → 检查实际文件变更（git diff 或直接读文件）
2. 如果子代理声称找到了 X → 确认路径/行号是否真实存在
3. 如果多个子代理的结果有矛盾 → 以实际文件状态为准
4. worktree 代理完成后 → 审查分支 diff 再决定是否合并

上下文膨胀控制：

• 子代理 prompt 中明确要求精简输出："报告关键发现，200 字以内"
• 搜索类任务要求只返回文件路径和行号，不要大段引用代码
• 如果预期结果很长，用 background 代理 + 写入文件，而非返回到主上下文

---

七、失败恢复

子代理可能失败。以下是标准处理流程：

| 失败类型 | 症状 | 恢复策略 | |---------|------|---------| | 超时/无响应 | background 代理长时间无通知 | 用 TaskOutput(block:false) 检查状态；如确认卡住，TaskStop 后重新分派 | | 输出无用 | 返回"没找到"或泛泛而谈 | 检查 prompt 是否足够具体；补充路径/行号后重试，换更强模型 | | worktree 冲突 | merge 时报 conflict | 读冲突文件，手动解决或放弃该分支重做 | | 权限被拒 | background 代理静默失败 | 改为 foreground 重试（用户可审批权限） | | 部分完成 | 代理完成了 3/5 个子任务就停了 | 读取已完成的部分，只对剩余部分重新分派 |

恢复原则：

• 不要盲目重试相同的 prompt — 先诊断失败原因
• 如果同一策略失败两次，换方向（更细的拆分、不同的代理类型、串行替代并行）
• worktree 冲突频繁 = 任务拆分粒度不对，应合并相关修改到同一代理

---

八、反模式与边界

| 反模式 | 为什么有问题 | 正确做法 | |--------|------------|---------| | 委托理解 | "根据研究结果来实现" — 子代理没有研究上下文 | 主线程综合研究结果，给出具体指令 | | Explore 做深度分析 | 只读摘录，会漏内容 | 用 code-explorer 或 general-purpose | | 7+ 并行代理 | 主线程上下文被撑爆，汇总质量下降 | 控制每批 ≤4 个，分批执行 | | 并行写同一文件 | 即使用 worktree 也会产生合并冲突 | 合并为一个代理，或明确分工不同区域 | | 所有代理都用 opus | 搜索任务用 opus 是 5x 成本换 <5% 质量提升 | 按§三能力需求选 model | | background 做需要权限的事 | 权限请求会被自动拒绝，代理静默失败 | 需要权限时用 foreground | | prompt 太短/太模糊 | "看看有什么" → 结果无用，浪费一次代理调用 | 明确目标、约束、输出格式 | | 不验证就汇报 | 子代理说"已完成"但实际没改对 | 读文件/diff 确认实际状态 |

并行数量的硬约束来源：

• 每个 foreground 代理返回 200-800 token，4 个 = ~2000 token 进入主上下文
• 超过 6 个时，主线程汇总时容易遗漏或混淆各代理的结果
• background 代理无数量硬限制，但完成通知会打断主线程工作流

---

九、Prompt 编写要点

子代理看不到主对话历史。每个 prompt 必须像给新同事的完整 briefing：

必须包含：

• 目标：做什么，为什么
• 上下文：项目背景、已知信息、已排除的方向
• 约束：文件范围、时间预期、输出格式
• 长度控制：明确说"200 字以内"或"只返回文件路径"

避免：

• "基于你的发现来..." — 把综合判断推给子代理
• "看看这个模块" — 没有明确目标
• 省略已知的文件路径/行号 — 让子代理重新搜索浪费时间

好的 prompt 示例：

在 src/services/auth/ 目录下，找到 JWT token 刷新的实现。
已知入口是 refreshToken() 函数（大约在 auth-service.ts 中）。
我需要知道：1) 刷新失败时的重试逻辑 2) token 过期窗口的配置位置。
只返回文件路径、行号和关键逻辑摘要，200 字以内。

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: AriesOxO
• Source: AriesOxO/claude-skills-hub
• License: MIT

Install and usage instructions live in the source repository linked above.