写明的规则都守住了
工单写了什么,agent 就做到了什么。三次 Opus 5.5 运行里,"无效优惠码不影响支付"对过期、停用和不存在的优惠码都成立。
我们把同一个结账仓库交给 Claude Code,一次只给一句话工单:"Add coupon codes to checkout. Make sure invalid codes do not break payment."(给结账加优惠码,确保无效优惠码不会影响支付。)另一次给一份 spec。每个结果都由一套在第一次运行前就写好的 11 项隐藏检查打分,其中 5 项检查的规则在一句话工单里完全没提到。在 Opus 5.5 上,模糊运行通过了工单写明的每一项检查;所有失败都出在没写明的规则上:
| 隐藏检查 | 一句话工单里提到了吗? | 模糊运行 | Spec 运行 | 覆盖它的 spec 条目 |
|---|---|---|---|---|
| 过期、停用或不存在的优惠码不影响结账 | 是 | 3 / 3 | 3 / 3 | AC-2 |
| 实际扣款金额等于页面显示的总额 | 是 | 3 / 3 | 3 / 3 | AC-1 |
| 同一用户不能重复使用同一张优惠券 | 否 | 2 / 3 | 3 / 3 | 规则:每个用户一次;AC-3 |
| 两个未完成的结账不能同时用掉一张限用一次的优惠券 | 否 | 2 / 3 | 3 / 3 | AC-4:支付时重新检查 |
| 只应用不支付,不会消耗优惠券 | 否 | 3 / 3 | 3 / 3 | 规则:支付后才算使用 |
| 第二张优惠券替换第一张 | 否 | 3 / 3 | 3 / 3 | 规则:后者替换前者 |
节选自优惠券运行页面上 11 项检查中的部分行,模型为 Opus 5.5。在 Haiku 4.5 上,三次模糊运行都没通过两项重复使用检查;带 spec 时三次都通过了全部检查。
工单写了什么,agent 就做到了什么。三次 Opus 5.5 运行里,"无效优惠码不影响支付"对过期、停用和不存在的优惠码都成立。
有一次运行认定优惠券不限使用次数,还在总结里说明了这一点。它自己写的测试也通过了,因为测试是按它自己选的规则写的。
每次模糊运行遇到无效优惠码都会抛异常;spec 运行则按 AC-2 的要求返回 { ok: false, reason }。没有哪项隐藏检查因此失败,但按其中一种写的前端,换到另一种就会出错。
| 规则 | 弱写法 | 强写法 |
|---|---|---|
| 每条都编号 | 一串期望的要点 | AC-1 到 AC-n,测试、工单和评审意见都引用编号 |
| 写明接口和确切结果 | "无效优惠码显示错误" | "applyCoupon 返回 { ok: false, reason: 'expired' },不抛异常" |
| 写下需求默认的规则 | 完全没提使用次数 | "一张优惠券每个用户只能用一次,订单支付后才算使用。" |
| 覆盖两个步骤之间可能变化的状态 | 应用优惠券时校验一次 | "在 pay 里重新检查是否已被使用" |
| 描述行为,而不是实现 | "用一个 helper 校验优惠券" | 写接口上可观察的结果;helper 是任务,不是验收标准 |
| 确认每条现在都不成立 | 当前代码已经满足的标准 | 说出能证明它不成立的观察,并确认改动前它确实失败 |
第三条和第四条,是人类同事几乎从不需要写下来、而 agent 每次都需要的。同事知道业务,会默认优惠券只能用一次;agent 去读数据,发现没有限制,于是就不加限制。更通用的 Given/When/Then 写法,可以看我们的验收标准示例指南。
把这段放进 spec.md 或工单里。规则那一节即使看起来理所当然也要保留,没写明的决定就放在那里。
## Rules - [需求默认的业务规则:次数限制、适用对象、什么时候算数] ## Acceptance Criteria - AC-1 主要行为:Given [状态],when [在指定接口上的动作], then [确切的可观察结果]。 - AC-2 失败路径:Given [无效输入或外部服务失败],when [动作], then [确切的错误码或返回结构];[哪些保持不变]。 - AC-3 规则检查:Given [违反上面某条规则的状态],when [动作], then [拒绝,以及拒绝原因]。 - AC-4 步骤之间:Given [第一步之后发生变化的状态], when [不可撤销的那一步执行],then [它重新检查,以及检查后怎么做]。 - AC-5 非目标守卫:Given 改动完成,when 评审 diff, then 范围之外的文件、schema、API 和依赖都没有变化。 ## Evidence - 每条 AC 一个测试,以 AC 命名(ac1_...、ac2_...)。 - 每个测试在改动之前的提交上都会失败。
下面是 agent 实际收到的 spec 中的验收标准部分,原文取自运行记录包。有了它,三次 Opus 5.5 运行都通过了全部隐藏检查,并做出了相同的决定。
## Rules
- A coupon is either percentOff (of the subtotal) or amountOffCents.
- A coupon can be redeemed once per user. It counts as redeemed only
when an order is paid, not when it is applied.
- Applying a second coupon replaces the first.
## Acceptance criteria
- AC-1 Valid coupon: getSummary shows the discount and the discounted
total; pay charges exactly that total.
- AC-2 Unknown, disabled or expired code: applyCoupon returns
{ ok: false, reason } with reason unknown, disabled or expired.
It does not throw, and the checkout keeps its previous total
and stays payable.
- AC-3 Code already redeemed by this user: returns
{ ok: false, reason: 'already_redeemed' }.
- AC-4 Redemption is re-checked inside pay: if the user redeemed the
coupon on another order after it was applied here, pay drops the
coupon and charges the undiscounted total.
- AC-5 An amount-off coupon larger than the subtotal brings the pre-tax
amount to 0, never below.
- AC-6 A successful apply returns { ok: true, code, discountCents }.
它留下的缺口。这份 spec 没说优惠券在应用之后、支付之前过期该怎么办。三次 spec 运行做了同一个选择:按折后价收费,其中一次在总结里指出了这个问题。一个一致的答案比三个不同的答案容易评审,但它仍然是一个没人做过的决定。AC-4 要求在两个步骤之间重新检查是否已被使用;完整的 spec 还应该在那里重新检查是否过期。
AI 验收标准生成器(包括本站的)擅长格式和显而易见的情况,却恰恰在最要紧的地方很弱:需求没说清的那些决定。让模型写验收标准,它会用看似合理的猜测把空白填上。更好的做法是让它把空白列出来。
你在为一个编码 agent 起草验收标准。不要自己决定业务规则。 针对下面的需求: 1. 把需求里所有没定下来的决定列成问题:次数限制、适用对象、 什么时候算数、失败时怎么办、两个步骤之间可能变化的状态。 2. 只为已经定下来的部分起草编号的验收标准 AC-1..n。 每条都写明函数、端点或页面,输入,以及确切的结果或错误码。 3. 标出当前代码已经能通过的那些标准。 需求: [粘贴工单]
Gherkin 生成器能把用户故事转成 .feature 文件里的 Given/When/Then 场景。规格包生成器会把验收标准连同范围、任务和证据清单一起起草。两者都在浏览器里运行,无需注册;把它们的输出当作初稿,按左边的清单检查。
验收标准的价值在评审时兑现。要求每条标准一个测试,以标准编号命名,并确认每个测试在改动之前的提交上会失败;一个从没失败过的测试,证明不了让它通过的那段代码。然后读 diff,找出对应不到任何标准的行为:多出来的状态、改了名的字段、新加的依赖。把它们当作漂移,移到后续 spec 里,而不是因为看起来有用就顺手合并。AI PR 评审清单逐步讲了这一步。
它是一组编号的、可测试的陈述,说明一项改动必须做到什么,写法要让编码 agent 能据此实现,测试或评审者不必追问含义就能检查结果。和写给人看的验收标准相比,它需要写明接口和确切结果,并把人类同事会默认的业务规则也写出来。
它能把格式和显而易见的情况起草得很好,但不应该替你做决定,比如一张优惠券能用几次、两个步骤之间状态变了怎么办,因为这些正是需求没说清的空白。让模型把未决事项列成问题,再由人来回答。
通常三到七条:主要行为、至少一条失败路径,以及边界或权限情况。我们实测中使用的优惠券 spec 有六条验收标准,外加三条写明的业务规则。
要写出观察行为所依赖的公开接口,比如函数、端点或页面,因为测试就在那里运行。不要写要改哪些内部 helper 或文件,那些属于范围或计划,不属于验收标准。
只要每条标准都写明起始状态、动作和可观察的结果,两种都可以。Given/When/Then 让这三部分很难漏掉;普通句子更短。优惠券 spec 用的是普通句子,但写明了函数名和返回值。
在 agent 写代码之前,写出评审者不需要你帮忙也能测试的验收标准,包括那些你从没想过要说出口的规则。
复制模板