用五步验收流程约束 AI 编程交付
将 OpenCode 开发拆成规格、实现、验证、审查和交付五个阶段,以 SPEC.md、PLAN.md、ACCEPTANCE.md 明确目标与完成条件。要求每次有意义的修改后执行构建、检查和测试,通过后再进入后续阶段。
AI 深度解读
AI 能把功能写出来,为什么仓库还是不敢交付?作者给出的答案是:模型周围缺少约束。需求没有验收标准,修改后没有检查,提交前也没人核对差异,演示能跑就容易被当成工作完成。
作者为 OpenCode 提出了一套循环:写规格、实现、验证、审查、交付。值得借鉴的是,每一步都有放行条件。不过,原文没有提供效率或缺陷率的对照数据,应该把它当作一套可试用的工程流程。
先写清楚怎样才算完成,再让 Agent 写代码
作者把规格拆成三个短文件,每个控制在一页以内:
SPEC.md写问题、目标用户和验收标准。PLAN.md写有先后顺序的实施步骤。ACCEPTANCE.md写证明任务已经交付的检查项。
三份文件分别回答「做什么」「怎么做」「怎样证明做完」。价值不在文件数量,而在于给 Agent 一个可以核对的目标,也让完成标准在会话结束后继续留在仓库里。
实施时,OpenCode 按照 SPEC.md 编码,同时更新 PLAN.md。作者强调两条规则:一次只推进一个任务;每次有实质性修改就运行验证,不能等全部写完才检查。
任务越小,验证失败后需要排查的改动范围就越小。
原文没有规定「实质性修改」的具体边界。实际使用时,需要团队自己约定,否则 Agent 仍可能把一大批修改解释成一个任务。
验证负责拦错误,审查负责核对方向
作者希望用一个入口统一不同项目的检查:
wf-verify
注意这里只有一行命令:作者称它能识别 Go、Bun/Node、Rust、Python、Make 等项目,运行相应的构建、lint 和测试,并返回明确的通过或失败结果。
这能让 Agent 少猜一次「当前仓库该跑什么命令」。但原文没有展示安装方法、识别规则、配置方式或实际执行日志,无法据此确认它对具体仓库的覆盖程度。
验证失败就修复,不进入审查和交付。
验证通过之后,还要单独看一遍 diff,最好换一个 Agent 角色。审查核对四件事:改动是否符合 SPEC.md、新行为有没有测试、是否混入密钥或硬编码路径及不安全默认值、验证是否确实执行过。
两道检查各有用途。构建和测试可以检查已有规则覆盖的行为;审查则要追问,需求有没有理解错,范围有没有扩大,测试本身有没有漏项。
交付也有明确条件:验证与审查都通过,再写清楚「改了什么、为什么改」的提交信息;如果是发布版本就打 tag;行为变化时更新 README 和安装说明,并记录当天工作。作者把 push 也列在交付阶段,但没有展开具体发布操作。
我的判断
这套流程最有价值的地方,是把「完成」变成可检查的条件。它适合用来约束 AI 编程过程中常见的范围漂移和过早收工。
但作者最后断言「瓶颈不在模型,而在缺少关卡」,说得偏满。模型能力、需求复杂度、现有测试质量都会影响交付。原文没有给出对照实验,也没有证明换一个 Agent 角色审查就能稳定发现更多问题,这些仍是作者的实践判断。
统一验证入口也有前提:仓库已经有值得运行的检查。没有测试,或者 lint 只覆盖格式,命令返回成功也不能证明功能正确。与现有 package.json scripts 或 CI 相比,wf-verify 的潜在价值是统一调用方式;原文没有证明它的检查更全面。
另外,文章同时在推广工具包:免费版包含 core + prompts,Pro 标价 $29,包含 full loop、sweep/doctor 和 verifier;作者称模板及 GitHub 仓库采用 MIT 许可。免费内容与 Pro verifier 的具体边界没有说清,选用前需要核实。
能拿来做什么
- 给前端或 Node 功能写几条可观察的验收条件,例如成功、失败和边界输入分别应出现什么结果,再让 Agent 开始实现。
- 在现有仓库中明确验证入口,让 Agent 每次完成一项有实质内容的修改后执行,并保留结果;采用
wf-verify前,先确认它实际调用了哪些检查。 - 验证通过后单独审查 diff,对照需求检查范围、新行为测试、密钥和硬编码路径,并核实验证记录。
- 把 README、安装说明和必要的发布 tag 纳入完成条件,避免代码已经提交,使用者仍不知道如何运行或升级。