Parallel Do

---
name: parallel-do
description: 当下一步工作能拆成 2 个以上互相独立、无共享状态的子任务(并行调研多个方案、给多个互不相关的文件/模块分别改动、多路并行探索代码),且并行推进比一条线串行更省时时使用。用户说"并行/parallel/同时做/分头做/一起推进"时也适用。
---

# parallel-do — 拆分任务并用 Codex subagents 并行执行

把一个工作步骤拆分成可并行的子任务,分波并行 spawn subagent 并发执行,最后汇总结果。目标是**真正提速**,不是为了并行而并行。用户调用本 skill 即构成对并行 spawn subagent 的明确授权,无需再询问。

## 流程

### 1. 确定目标任务

按优先级取任务:
1. 用户消息里给出的工作描述
2. 当前对话上下文中明确的"下一步工作"
3. **上下文里没有详细任务时 → 从项目 plan 接着干**(对接同插件 scaffold skill 铺的 docs 布局):
   - 读 `docs/Progress.md`(最新在上)→ 确认已经做完到哪了
   - 读 `docs/PLAN.md` → 找**第一个没打 `✅` 的 Phase**;再看底部「Spec 索引」区(旧项目可能是「计划索引」)指向的详细文档
   - 钻进「Spec 索引」指向的最新一条 `docs/specs/<日期>-<主题>-design.md` → 按 spec 里的验收条款拆出**第一个尚未实现的独立单元**作为目标任务;旧项目走「计划索引」指向的存量计划 `docs/plans/<日期>-<主题>.md` → 取里面**第一个尚未完成的步骤**(`- [ ]`)
   - 拿 Progress 已记录的"做完"交叉核对,跳过已完成项,只取下一个真正待办
   - 这些文档都不存在(项目没铺脚手架)→ 退回看 README / 顶层 TODO / 任意 PLAN 文件里标注的下一个待办
4. 以上都拿不到 → 问用户要做什么

### 2. 拆分与依赖分析

把任务拆成子任务,对每个子任务标注:

- **类型**:「只读」(探索/调研/读代码/分析/设计) 还是「写入」(改代码/建文件/改配置)
- **依赖**:它依赖哪些其他子任务的产出

只有**互相独立**(无依赖、无共享可变状态)的子任务才能进同一波并行。有依赖关系的排成波次:第一波结果出来后,作为输入喂给第二波。

### 3. 价值门槛(防过度并行)

满足以下任一条就**不并行,直接做**,并向用户一句话说明原因:

- 拆不出 ≥2 个真正独立的子任务
- 任务本身几分钟就能直接做完(每个 subagent 都是全新 context、要重新读文件,启动有开销)
- 子任务之间是纯串行链(A→B→C),并行没有收益

### 4. 写入冲突分流

- **只读子任务** → 直接并行
- **写入子任务** → 先列出每个子任务**预计要改的文件清单**:
  - 文件集**不重叠** → 可以并行
  - 文件集**重叠** → 合并成一个子任务交给单个 subagent,或排进下一波串行执行(合并更稳)
  - 拿不准会不会重叠 → 按重叠处理(保守优先)
- **共享接缝先落地**:拆分时若多个同波子任务都依赖尚不存在的地基文件(模块定义如 go.mod/package.json、共享类型与接口定义、目录骨架、公共配置),由**主对话在开波之前**先把这层接缝写死并单独原子 commit,再把「接缝已固定、你只写自己的目录」写进每个子代理的 prompt;不要指望子任务各自创建——那等于让两个看不见对方的子代理同时写同一个文件。判断口诀:一波里凡是「两个子任务都会想去创建」的文件,都属于接缝,先落地

### 5. 分波 spawn subagents 执行

不逐个串行做,把同一波的独立子任务一次性并行 spawn(Codex 原生 subagents):

- **一波 = 一次并行 spawn**:每个子任务一个 subagent;明确表述「spawn N 个并行 agent,agent 1 做 X,agent 2 做 Y……等全部完成再继续」
- **并发上限**:`config.toml` `[agents]` 的 `max_threads` 默认 6(最高 8);同一波子任务多于上限时分批 spawn。调高 `max_threads` 只在机器 CPU/内存有余量时做,别在已吃紧的机器上拉高——过载反而更慢(2026-09-19 一台机器被空转进程 + 会话堆积拖到负载 108,即此类);分批前先看 CPU 占用(macOS `top -l 2 -n 0 -s 1`、Linux `top -bn2 -d1`,取最后一条 CPU 行——macOS 的 `CPU usage`、Linux 的 `%Cpu(s)`——占用 = 100 − idle;内存 macOS `memory_pressure`、Linux `free -m`):超过 70% 每波并发按当前值减半(最少 1),超过 90% 或可用内存低于 20% 改串行;`top` 取不到读数时才退回看 `uptime` 的 1 分钟负载对比核数(macOS `sysctl -n hw.ncpu`、Linux `nproc`;超过核数 70% 减半、超过核数串行)
- **有依赖的波次**:等上一波全部返回,把关键结论写进下一波每个 subagent 的 prompt
- 每个 subagent 的 prompt 必须**自包含**(subagent 看不到主对话):
  - 背景:在做什么、为什么做
  - 输入:具体文件路径、相关约定(如项目 AGENTS.md 里的硬规则)
  - 边界:只允许改哪些文件、不许碰什么;点名生产红线——FORBIDDEN FILES 逐个列出、绝不重启共享服务、绝不读写生产数据、禁止 force push 与丢改动的历史改写;**写入子任务一律遵守 TDD**——先写能复现目标行为的测试、跑到失败,再写实现让测试通过,禁止先写实现再补测试;**测试启动的进程测完即关**——开发服务器、mock 服务、无界面浏览器、临时容器,失败或中途放弃也要关,启动时记下 PID / 端口 / 会话名,报告完成前逐个核对已退出(`npm` / `npx` 这类包装命令带起的子进程一起关、一起核对),只关自己启动的,不用 `pkill -f` / `killall` 按名字批量结束,别人留下的残留进程只列出来报告;**并发前先看 CPU 占用**——要并行跑测试时先看 CPU 占用(macOS `top -l 2 -n 0 -s 1`、Linux `top -bn2 -d1`,取最后一条 CPU 行——macOS 的 `CPU usage`、Linux 的 `%Cpu(s)`——占用 = 100 − idle;内存 macOS `memory_pressure`、Linux `free -m`):超过 70% 并发按当前值减半(最少 1),超过 90% 或可用内存低于 20% 改串行;`top` 取不到读数时才退回看 `uptime` 的 1 分钟负载对比核数(macOS `sysctl -n hw.ncpu`、Linux `nproc`;超过核数 70% 减半、超过核数串行),报告写明 CPU 占用、可用内存与实际并发数;**子任务的代码要启动外部进程**(无界面浏览器、子进程、常驻 worker)时写明必须实现退出:最长存活时间到点结束整个进程组、关闭先正常后强制且等待有上限、同时存活数有上限、出错/超时/取消/启动失败的路径都关、每次调用带超时、容器加内存与进程数上限,测试覆盖卡住或出错后进程确实退出
  - 输出:期望的返回格式(发现清单 / 改动摘要 / 结论),写入子任务额外要求附上测试命令与通过结果
- **模型**:用会话默认模型;确有大量琐碎子任务时,可建议用户在 `config.toml` `[agents]` 里配轻量角色
- 需要架构判断、方案取舍、结果裁决的工作 → **不派 subagent**,留在主对话做
- **有依赖的多波**:每一波(尤其含写入子任务时)返回后,先走一遍下面步骤 6 的验收,确认真实可信后再把结论写进下一波 prompt——不要把未经验收的 subagent 自述当结论传下去,以免错误在波次间累积

措辞示例(两波:先并行调研,再把结论喂给并行实现):

> 第一波:spawn 3 个并行 agent 做只读调研。agent 1:〈自包含 prompt:背景/输入/边界/输出〉;agent 2:……;agent 3:……。等全部完成。
> 第二波:把第一波结论分别写进实现 prompt,spawn 2 个并行 agent:agent A 只改〈文件集 A〉,agent B 只改〈文件集 B〉(两个文件集互不重叠)。

只有一波时直接一次 spawn;波次更多时同理顺延。

### 5.1 共享 worktree 下的提交与文档同步

同一波 subagent 若共享同一个 worktree(没有各自独立 worktree/分支隔离),**subagent 只改文件、不 commit**:

- **谁 commit**:统一由**主对话**在步骤 6「逐任务验收」通过后提交,对齐 `AGENTS.md` §7.1「主对话验收——逐任务
  对照 diff 核实,不采信 subagent 自述」的语义——subagent 各自返回时机不同、都在同一份工作区改文件,谁改完谁自己 commit 会互相踩
  对方还没验收完的改动,也绕过了「不采信 subagent 自述」的验收纪律。**验收 = commit 前置条件**,没验收
  的子任务不能进 commit。验收阶段此时还没有逐任务 commit 可 `git show`,取真实 diff 用
  `git diff -- <该任务的文件集>`(文件集不重叠由步骤 4 拆分时保证,见步骤 6 第 2 条)。
- **粒度**:每个写入子任务验收通过后单独一个原子 commit(不要等一整波全部验收完才打包成一个大
  commit),对齐 `AGENTS.md`「一个操作 ≈ 一个原子 commit」;commit 后按 `AGENTS.md` 里约定的分支推送策略立即 push 当前
  feature/wip 分支(若项目未约定,先与用户确认再 push)。
- **八件套文档同步谁做**:同样由**主对话**在验收通过、commit 前一并补齐(`docs/Progress.md` 变更日志必
  改;按 `AGENTS.md` 第 2 节「文档同步规则」表判断还要不要动 PLAN/DECISIONS/ARCHITECTURE/DEPLOYMENT 等其
  余几件)——不要求 subagent 在 prompt 里顺带写文档,subagent 交的是代码 diff,文档由主对话汇总时统一写,
  避免多个 subagent 并发改同一份 Progress.md 互相覆盖。
- **例外**:确有独立 worktree/分支隔离(各 subagent 互不共享工作区)时,可以让 subagent 自己 commit 到各自
  分支,但仍需主对话验收通过后才能合并/push 到共享分支——判断标准是「会不会有两个 subagent 同时改同一份
  未提交的工作区」,会就走上面的统一 commit 路径。

### 6. 汇总与验证

每一波 subagent 返回后(单波任务则是全部返回后)按顺序走完下面四步,全部由**主对话亲自**做——汇总、验收、裁决属于检查类工作,不派 subagent 去做(例外:盲审轮与接力轮可派只读验收 subagent 出报告,合并与裁决仍由主对话做,见 AGENTS.md §7.1);多波任务在全部波次结束后再整体过一遍第 4 步给用户简报:

1. **读结果**:结果为空或形状不对时,查看对应线程的实际输出,再下结论
2. **逐任务验收**(有写入子任务时必做;subagent 自述只当线索,不当证据):
   - 对每个写入子任务,拿真实 diff(共享工作区未提交时用 `git diff -- <该任务的文件集>`;已逐任务 commit 时用 `git show`)对照该任务的规格逐条核对——规格以 `docs/specs/` 对应 design spec 里的条目为准(旧项目以「计划索引」指向的存量计划条目为准),没有 spec/计划文档时以第 2 步拆分时定的边界与输出为准:行为要求都实现了、只改了允许改的文件
   - 跨任务的集成缝合点单独核一遍:接口/字段/密钥等约定是否对得上、中间件/路由是否真的挂上、共享配置或依赖有没有互相覆盖(各 subagent 互相看不见对方,缝合处最容易断)
   - 不合格的子任务:小问题当场改,大问题重派一个 subagent 返工,返工后重新验收;返工后的重新验收只报与前面各轮的差异(新发现/推翻项),不重复复述已核对项
3. **跑真实验证**:有代码改动 → 跑项目对应的检查/测试(看项目 AGENTS.md / package.json / Makefile 里定义的验证方式);确认新增行为真的被测试覆盖到,套件全绿不等于新代码被测过
4. **给用户简报**:任务怎么拆的、哪些并行了、哪些串行了(及原因);每个子任务的结果与验收结论;验证结果与遗留事项