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)时写明必须实现退出:最长存活时间到点结束整个进程组、关闭先正常后强制且等待有上限、同时存活数有上限、出错/超时/取消/启动失败的路径都关、每次调用带超时、容器加内存与进程数上限,另配不依赖启动方的定时清理——按登记表定时扫、结束前核对还是原来那个进程、最长存活与数量上限、清理记日志,时限加在真正长跑的命令上而不是马上返回的客户端上(timeout -k,macOS 用 gtimeout;后台容器打标签由宿主机按标签清),部署或会话里留下的后台进程同样要配(细则见项目 AGENTS.md §3 第 10 条),测试覆盖卡住或出错后进程确实退出、定时清理能收掉超时的进程
  • 输出:期望的返回格式(发现清单 / 改动摘要 / 结论),写入子任务额外要求附上测试命令与通过结果
• 模型:用会话默认模型;确有大量琐碎子任务时,可建议用户在 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. 给用户简报:任务怎么拆的、哪些并行了、哪些串行了(及原因);每个子任务的结果与验收结论;验证结果与遗留事项