用途
Verify Between Waves 是一种为多文件重构命名的检查点节奏。它把成功的大型重构中实际发生的做法固化下来,也针对那些中途失控的重构指出缺失的环节。
其核心判断是:重构失败往往源于编辑在尚未验证前就不断叠加。典型失败模式是:第 1 波编辑看起来没问题;第 2 波破坏了第 1 波中某个细微之处;到第 4 波时 tsc 错误已经纠缠不清,复现问题比重做还费时间。
主要能力
- 以“波次(wave)”为单位组织编辑:一波是一组逻辑一致、可作为一次变更来推理的编辑。
- 每波执行固定流程:批量并行读取目标文件 → 批量并行编辑(保持编辑范围窄且相关)→ 运行门禁(typecheck 与测试)→ 根据结果决定修复或提交。
- 门禁为红色(RED)时:不再添加新编辑,在当前波内修复回归,重复运行门禁直到绿色;若修复使该波超出“一次一致变更”的范围,则拆成两波并在其间设置提交边界。
- 门禁为绿色(GREEN)时:以命名该波的范围化提交信息提交,然后进入下一波。
- 完成 N 波后推送。
使用方式
每波的门禁命令示例为:npx tsc --noEmit && pnpm test,资料强调“无例外”。
“绿色”的最低标准是:类型检查无错误;所有既有测试通过,且本波新增测试也通过。更好的标准(若可用)包括:lint 干净、覆盖率高于配置阈值,以及在单元测试无法覆盖处进行少量显式人工冒烟检查(例如 MCP stdio 传输往返)。
提交信息示例:
- wave 1 — security hardening
- wave 2 — tools.ts cleanup + schema visibility
- wave 3 — pino redact + telemetry race + HNSW init
- wave 4 — Puppeteer page pool
- wave 5 — safePaginate helper, vector dirty flag
每条信息说明该波的一致主题,正文记录改了什么、留下了什么。
波次规模的经验法则:机械式 replace_all(例如用 errMsg 辅助函数替换 11 处三元表达式)单独作为一波;同一文件内的相关修复为一波;同一模式应用于 2–3 个文件为一波;横切变更(接口抽取、广泛使用符号的重命名)为一波,随后验证,再做清理波;新功能与测试分开,功能一波、测试一波。反模式是把“安全修复 + 清理 + 新测试 + 文档更新”塞进同一波。
回滚配方(当某一波出问题时):
git reset --mixed HEAD~1 # undo the wave commit but keep files
git checkout -- <files> # drop the bad edits
# or: git stash # keep them for inspection
之后要么以更小步骤重做该波,要么放弃该变更继续前进。
适用场景
适用于任何满足以下条件之一的编辑集合:涉及超过 3 个文件;涉及超过 3 类不同关注点(安全、性能、DX、清理等);人工耗时超过 20 分钟;或机械清理与新代码新增混在一起。
单文件修复、单行编辑和纯文档提交可跳过此节奏。
会话证据
资料给出的证据来自 scrapin-aint-easy Tier-A 重构(一次真实会话,n=1):7 波、24 项升级、9 次提交;每波提交前执行 tsc + 测试;回归在引入它的那一波内被捕获——this._initialized 重命名破坏了两个写入点(重命名波后立即被 tsc 捕获),死比较器移除波后出现 now 未使用(同一次 tsc 通过中被捕获);9 次提交全部为绿,从未需要分支中途回滚。
与其他模式的关系
- Refactor Pipeline(cc-orchestrate.md Template 5):verify-between-waves 是把“Verifier”角色形式化为重复节奏,而非单一最终步骤。
- Checkpointing(skills/checkpointing/SKILL.md):checkpointing 周期性保存编排器状态;verify-between-waves 周期性保存代码状态(提交)。二者互补。
- Context Budget(skills/context-budgeting/SKILL.md):波次是天然的 /compact 边界——每次绿色提交后,周边上下文适合被总结。
限制与警示信号
未运行此节奏的红旗包括:10 次以上编辑后仍未运行 tsc;指望测试“最后”通过;有超过 5 个未提交的已改文件;在自首次编辑以来未运行类型检查的情况下准备提交 200 行以上 diff。出现任一情况,应停止编辑、运行门禁、提交绿色部分,并把其余重新规划为新波次。
资料未提供该技能的安装命令、收费方式、支持平台或具体实现细节。