AI 辅助开发下的规格质量门禁

让 AI 生成的代码不会不经审查就上线的四道质量门禁：prompt 前规格校验、生成后 diff 审查、测试证据核验，以及人工签字放行规则。我见过团队把这四道全部跳过，然后花一整个周末回滚一个"看起来无害"的一行变更，事实证明它一点都不无害。

发布于 2026-03-09 · ✓ 已更新 2026-05-06 · 阅读约 8 分钟 · 作者：Spec Coding 编辑部 · 审校：编辑与事实核查政策

现场笔记：能拦住漂亮但不安全 diff 的门禁

常见失败不是生成代码很丑，而是代码很顺眼，却没有回滚故事。质量门禁要问的是：本地测试跑完以后，还留下什么证据。

质量门禁行：
风险等级：中
合并前必须有：单元测试、集成测试、回滚说明
发布前必须有：日志查询和告警阈值
发布责任人：on-call lead
止损信号：error_rate_refund_worker 连续 10 分钟超过 1%

四道门禁，按顺序，不容商量

在我主导 AI 辅助开发工作时，我会强制执行四道门禁，而且必须按顺序走。第一道在模型看到 prompt 之前就触发：规格必须完整。第二道在生成之后立刻触发：diff 必须匹配 prompt 声明要改动的范围。第三道在代码接通之后触发：测试必须存在，而且在行为被破坏时确实会失败。第四道在合并之前触发：必须有一个具名的人真正读过这份改动，而不是随手点个 approve。

任何团队只要跳过其中一道，就是在赌另外三道能把问题兜住。我的经验是，漏洞往往是同时出现的，而不是错开的。

门禁 1：Prompt 前规格校验

在让模型生成任何一个 token 之前，有一个自动化脚本会扫描规格文件。它检查五个小节：问题描述、范围、非目标、验收标准、风险。只要其中任何一项是空的、缺失的、或被压缩成"让它能跑"这样的一句话，runner 就会拒绝调用模型。没有规格，就不生成。

听起来很官僚，直到你看到它真的起作用。一旦要有人写出一个非目标，多少"快速小需求"就当场原地蒸发，这个数量会让你吃惊。一个特性如果撑不过五个标题，它既没准备好交给 AI，说实话也没准备好交给人。

陷阱在于让门禁 1 变成走过场的 checkbox。如果每份规格都能通过，这道门就什么也没在测。我每两周会随机抽查一批通过的规格，专门挑那些用填充文字凑数的。这些会被打回去，而且作者要当众被告知。

门禁 2：生成后 diff 审查

模型刚写完、在任何测试跑起来之前，我会对照 prompt 检查 diff。三个问题：diff 是否只碰了我让它碰的文件？它有没有擅自添加未经授权的依赖？它有没有在声明的输出路径之外创建文件？

这三件事我全部自动化。一个脚本读取 prompt 里声明的文件列表，和实际改动的文件做 diff，把任何出乎意料的地方标红。package.json、pyproject.toml 或 go.mod 里新增的条目会触发硬停。出现在奇怪目录里的生成文件会触发硬停。

我最常见的失败模式是：模型偷偷加了一个工具类依赖，理由是"这样更干净"。有时候确实更干净。但我要的是这个决策被摆上桌面，而不是被偷偷夹带进来。

门禁 3：测试证据，外加 mutation 检查

测试通过不算证据。测试通过、并且在你故意把代码改坏之后能失败，才算证据。这两件我都要。

每一条验收标准，都必须至少对应一条测试。我用 Given/When/Then 写验收标准，这样映射就是机械的：

- Given a user with an expired session token
  When they request a protected resource
  Then the response is 401 and no row is written to the audit log

- Given a payment webhook with a replayed event ID
  When the handler receives it
  Then the handler returns 200 and does not re-charge the card

测试通过之后，我会在关键路径上跑 mutation 检查。如果我能把函数体改坏，而测试还能通过，那这些测试就是在说谎。我宁可现在发现这件事，也不要等到事故里才发现。门禁 3 的失败频率比大家预期的高得多，几乎全是因为 AI 写了一个 mock 掉它本该验证的东西的测试。

门禁 4："我真的读过"按钮

门禁 4 是团队最喜欢盖橡皮图章的一道，也是救你命的一道。必须有一个具名的人从头到尾读一遍 diff，并对它背书。不是"approved"，不是点赞 emoji。要写一条引用具体行号、具体选择或具体风险的评论。要有证据证明他真的来过。

我对这件事较真的原因是：门禁 1 到 3 都是机器能检查的，也就意味着它们也是机器能糊弄的。一份看起来合理的规格、一份老老实实待在车道里的 diff、一套全绿的测试套件，是可以一路畅通无阻的。这些东西都抓不住那种"代码在技术上正确，但行为已经悄悄不再是业务想要的"的变化。

一个通过了 1-3、在门禁 4 被抓住的 PR

上个季度有一个 PR，重构了我们的定价舍入逻辑。规格完整。diff 有边界。测试通过，而且扛过了 mutation。看起来完美。

做门禁 4 审查的那位同事发现，有一个分支现在用的是银行家舍入（banker's rounding），而旧代码用的是四舍五入向上（half-up）。测试之所以没抓到，是因为测试输入恰好在两种规则下舍入结果相同。但在真正流过生产的那些数字上，大约每两百张发票里就有一张会偏差一分钱。一个月下来，这就是一个四位数的对账头疼问题，很可能还会引发一次监管通报。

门禁 1、2、3 对舍入策略没有任何意见。一个给这批产品定了三年价的人读了 diff，说："等等，这里为什么变了？"——这才是门禁。

橡皮图章问题

门禁 4 会悄无声息地死掉。审查人看到 CI 全绿，随手扫一眼 diff，点下 approve，然后继续干别的。几个月之后，这道门就沦为一个虚荣印章，直到有东西真的漏出去才被人注意到。

我的对策是：轮换审查人，让同一个人不要每周都在给同一个作者盖章；要求审查评论引用具体的某一行或某个决策；每月抽查一批已批准的记录，请审查人口头复述一下他当时看了什么。如果他说不出来，这本身就是数据。

门禁健康度值得去度量。我会跟踪每道门禁拒掉了多少个 PR，更重要的是，哪些拒绝是有价值的、哪些是噪声。一道什么都不拒的门禁，要么是完美的，要么是坏的——而它从来不是完美的。

CI 管什么，人管什么

门禁 1、2、3 是 CI 的活。规格 schema 校验、diff 范围检查、测试到验收标准的映射、mutation 抽样——全部不需要人参与。如果让人自己记得去做这些，他一定会忘。

门禁 4 没法自动化。它的重点就在于"一个带着上下文的人看过了这次变更"。我能自动化的是证据链：审查人必须留下一条引用 diff 的评论，然后 bot 把它记录到 PR 上。等以后审计来问"这个谁签的字"，有人能答得上来。

绕行策略

有时候你确实得临时跳过一道门禁。生产在着火，规格就一句话，修复必须现在就发出去。我接受这一点，但有规则：只有两个具名的人可以绕行；每次绕行都要在审计表里写一行，注明原因；每次绕行都会生成一张后续 ticket，必须在一周内关闭。没有这套，"紧急"会变成默认路径，门禁也就不存在了。

那道大概应该存在的门禁

我目前还没跑合并后的回归门禁，我觉得这件事我是错的。一个 24 小时的冒烟检查，把关键指标和前一天对比——错误率、延迟分位数、转化这种业务指标——能抓住测试抓不到的静默回归。过去一年我见过两起事故，如果有这道门禁，就能在几小时而不是几天内被发现。这在我的待办列表上。

周一具体该干什么

挑一道门禁，这周把它做实。如果你什么都没有，从门禁 1 开始，因为它最便宜自动化、杠杆最大。如果已经有门禁 1，就在最关键的十个文件上加 mutation 检查，把门禁 3 做硬。如果四道门禁在纸面上都有、但都是软的，就把上个月的批准记录抽查一遍，看看还有多少审查人说得清自己当时看了什么。答案会告诉你该先修哪一道。

可复制产物：AI 编码评审包

在 AI 生成 diff 进入代码评审前使用。它把提示词范围、允许变更和证据要求合并成一个可审查产物。

AI 编码评审包：AI 辅助开发下的规格质量门禁

本次要做的决策：
- 确认 AI 只在批准范围内生成变更，并为每条验收标准提供证据。

责任人检查：
- 产品责任人：
- 工程责任人：
- QA 或运维评审：

范围边界：
- 本次包含：
- 本次不包含：
- 仍需确认的假设：

验收证据：
- 测试或 fixture：
- 日志、指标或截图：
- 人工复核步骤：

AI 边界：生成变更必须留在书面范围内，每条验收标准都要能找到证据。

评审追问：
- 没参加需求会的人还会误解哪里？
- 哪个证据能证明这次改动足够安全，可以发布？

二次审阅记录：门禁需要阈值

这次补充的重点是让页面更贴近发布操作。门禁只有在能说明缺什么证据、什么信号该停止发布时才有用。

门禁措辞：
- 不写“测试通过”，写清哪些测试。
- 不写“已有监控”，写清哪个指标。
- 不写“可回滚”，写清谁能触发。
- 不写“已评审”，写清接受了什么风险。

编辑复核记录

复核日期：2026-04-28。本次补充了可复用产物，按相关主题 Hub 检查了文章定位，并收紧下一步链接，让页面更像可操作参考，而不是孤立长文。

门禁落地清单

质量门禁只有在能用明确理由挡住正确的变更时才有价值。先定义负责人、证据和绕过规则，再要求团队全面执行。

下载：ai-quality-gate-policy-v2.md

• 为规格完整性、diff 范围、测试证据和人工评审分别指定负责人。
• 把可机器检查的门禁放进 CI，不让 reviewer 靠记忆执行。
• 要求人工评审评论引用具体行、决策或风险，而不是空泛批准。
• 每次绕过都记录原因、批准人、过期时间和后续工单。
• 每月抽查被拒和被绕过的变更，移除噪声检查，强化真正有用的检查。

需要追踪的证据

追踪拒绝原因、绕过次数、评审延迟、合并后的缺陷逃逸，以及被门禁挡住的 PR 是否产生了更清晰的规格。一个从不拒绝任何东西的门禁，不一定健康，也可能只是没人真正用它。