parallel-agentlisted
Install: claude install-skill AriesOxO/claude-skills-hub
# 并行子代理编排指南
此 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 分支的标准流程：**
```bash
# 1. 查看子代理返回的分支名（从 Agent 结果中获取）
git branch # 确认分支存在
# 2. 逐个合并（推荐，可控性高）
git merge <branch-name-1> --no-edit
git merge <branch-name-2> --no-edit
# 3. 如果有冲突，手动解决后
git add <conflicted-files>
git commit
# 4. 合并完成后清理 worktree
git worktree remove <worktree-path>
git branch -