用分层规范约束 AI 开发的八项技能
作者把 ProjectSpec 作为 AI 执行任务的契约,按项目、模块和功能分层,并为硬约束编号。八项技能覆盖设计、开发与评审,其中四项围绕议题处理,旨在减少多轮对话造成的规范漂移。
AI 深度解读
AI 写完一个功能,怎么确认它遵守了设计?开发中发现设计有问题,又该由谁决定改代码还是改文档?作者团队从实际事故中整理出八个 SKILL,把这两个问题放进同一套流程。讨论结束后,确认过的决定进入项目规范。实现出现偏差时,Agent 拿出证据,由人决定改哪边。对经常用 AI 改代码的团队,这篇最值得看的地方是每一步的写入权限和验收责任。
为什么先给项目规范分层和编号
八个 SKILL 都围绕项目规范文档 ProjectSpec 运转。这份文档供人阅读,也让 AI 把它当作执行和验收的契约。作者把它严格分成项目、模块、功能三层,并给每条硬约束编号。编号让开发和审查能指向同一条规则,分层则让 Agent 知道这条规则在什么范围内生效。
以一个全栈项目为例,项目层可以规定统一的错误响应格式,模块层可以约束账户接口的权限校验,功能层则可以约定某个表单提交失败后保留输入。如果最后一条被写进项目层,一个页面的决定就可能被套到所有页面。作者特别在意这种错误,因为落错层的规则看起来照样有权威,后续 Agent 还可能据此审查代码。
编号也让验收有了明确的落点。看到一处表单改动,审查可以引用具体约束,再指出失败分支里哪段实现有偏差。原文没有展示这些约束的文件格式,也没有说明其中多少条能由工具自动验证。有了编号,规则可以被精确引用。能否机器判定,还取决于规则是否写出了可观察的行为,以及项目有没有对应的检查。
聊天里的决定,什么时候可以写进规范
作者团队日常主要用 spec-start 和 spec-close。前者先列清待决事项,把讨论变成可以逐项收口的议程。比如讨论表单失败后的行为,可以先确定两件事:哪些输入要保留,重试时要不要重新校验。议程上的问题都有结论后,spec-close 再把确认过的决定写进 ProjectSpec 的对应层级。关掉聊天窗口和完成决策是两件事,后者还要看规则有没有落到正确的位置。
另两个技能用于处理讨论中断。话题需要跨多个 AI 会话时,spec-pause 用详细的会话日志保存当前进度,正式定案前,项目文档保持原样。异常中断留下待清理状态时,spec-archive 的权限只够移动状态,文件的删除和修改都超出它的权限。一个用于续接讨论,一个用于收拾异常留下的状态,作者团队很少用到前者。
这里容易忽略的是,待讨论事项和正式约束可能长得很像。聊天里一句「也可以在失败后清空表单」,单独摘出来就可能被后续 Agent 当成需求。先把这类想法留在会话日志里,等人确认后再写进规范,可以减少代码依据临时提议开工的机会。
开发中发现设计有问题,由谁决定怎么改
spec-dev-loop 先做设计审查。遇到冲突或语义不清的地方,主 Agent 向用户提问,并把问题记进开发日志。进入开发后,它检查本地仓库的分支状态,创建以 dev-loop/ 为前缀的分支,所有改动都在该分支上进行。作者的做法是先定下代码骨架,再把具体实现交给子 Agent。主 Agent 负责整体验收,验收后提交改动,通知用户复核,由用户手动合并。
实际实现偏离规范时,spec-code-review 要把差异和证据摆出来,由人决定修代码还是更新规范。在作者的流程里,代码里的变化只能从这个入口回写 ProjectSpec。这样,开发中确实有道理的调整可以被采纳,同时留下证据,说明原先的设计哪里需要变。
spec-code-smell 单独检查代码质量。一段实现可以满足表单行为约定,同时让多个组件各自维护同一套错误处理。前一个问题归设计一致性审查,后一个归代码质量检查。spec-smart-git 则按改动意图拆提交。例如,调整表单行为和整理独立的公共逻辑,如果以后需要分别撤销,就应该分别提交。提交时划出的边界,就是以后可以单独回滚的边界。
我的判断
我认同把确认规范和确认实现设为两个独立的时点。普通的 PR 审查也可以做这件事,前提是审查人找得到当时确认的规则。否则,PR 里往往只剩当前代码和一段需求摘要,审查人还得回聊天记录里确认,当初到底同意了什么。ProjectSpec 的分层和编号给这类问题提供了明确的引用位置。至于团队原有的 CI/CD,作者希望这组技能能独立运行,尽量少介入发布流程。
八个 SKILL 来自团队处理事故的经验。作者明确说日常主要使用哪两个,也给出了跑一遍最小 Loop 的办法,但没有交代事故规模、采用前后的返工率,也没有和普通 PR 审查做对照。文中的 30 分钟是首次试跑的建议时长,试跑覆盖一轮议题讨论和决策写入。它能帮你感受交接是否顺手,完整的开发验收、回写和回滚需要另行验证。
流程能提前暴露一部分偏差,设计的对错仍由人判断。哪些规则必须强制执行、两个架构该选哪个,都是作者刻意保留给人的决定,所以他们拒绝提供一键执行。团队能否从这套做法获益,还看规范有没有持续维护。需求频繁变化时,如果没人负责确认并更新相应条款,Agent 仍可能严格实现一份过期设计。已有 PR 模板和分支保护的团队,可以评估其中哪些环节已经有明确负责人,再补上缺失的决策记录或回写入口。
能拿来做什么
- 用 30 分钟试跑一个足够小的决定,比如确定表单提交失败后保留哪些字段。初始化项目并加载 SKILL 后,开一个议题,讨论、保存并关闭各一次,最后检查已确认的决定写进了 ProjectSpec 的哪一层。
- 给跨页面或跨前后端的硬约束加编号。比如给 Node 接口的错误响应格式写一条带编号的规则,同时写清哪些接口适用,让 Agent 在验收时引用编号并指出对应代码或验证结果。
- 开发中遇到设计冲突时,让 Agent 先记录规范编号、代码位置和观察到的差异。由评审人决定修实现还是更新规范,并在同一轮评审中确认这个决定已经落实。
- 拆提交时按能否独立回滚来判断边界。若页面行为改动和公共模块重构确实可以分别撤销,就把它们放进不同提交,便于日后只撤回出问题的那一项。