可测试的 AI 任务

写给 AI 编码 agent 的验收标准

AI 编码的验收标准,是一组编号的、可测试的陈述,说明一项改动必须做到什么,写法要让 agent 能据此实现、让测试能检查结果。在我们记录的 Claude Code 运行中,一句话提示词通过了它写明的每一项检查,只在没人写下来的规则上出错。本页讲这类验收标准必须包含什么,给出模板和那次实测里真实使用的 spec,并说明怎样用 AI 起草验收标准,又不让它替你做决定。

更新日期:2026-11-11

没有验收标准时,agent 错在哪里

我们把同一个结账仓库交给 Claude Code,一次只给一句话工单:"Add coupon codes to checkout. Make sure invalid codes do not break payment."(给结账加优惠码,确保无效优惠码不会影响支付。)另一次给一份 spec。每个结果都由一套在第一次运行前就写好的 11 项隐藏检查打分,其中 5 项检查的规则在一句话工单里完全没提到。在 Opus 5.5 上,模糊运行通过了工单写明的每一项检查;所有失败都出在没写明的规则上:

隐藏检查一句话工单里提到了吗?模糊运行Spec 运行覆盖它的 spec 条目
过期、停用或不存在的优惠码不影响结账是3 / 33 / 3AC-2
实际扣款金额等于页面显示的总额是3 / 33 / 3AC-1
同一用户不能重复使用同一张优惠券否2 / 33 / 3规则:每个用户一次;AC-3
两个未完成的结账不能同时用掉一张限用一次的优惠券否2 / 33 / 3AC-4:支付时重新检查
只应用不支付,不会消耗优惠券否3 / 33 / 3规则:支付后才算使用
第二张优惠券替换第一张否3 / 33 / 3规则:后者替换前者

节选自优惠券运行页面上 11 项检查中的部分行,模型为 Opus 5.5。在 Haiku 4.5 上,三次模糊运行都没通过两项重复使用检查;带 spec 时三次都通过了全部检查。

写明的规则都守住了

工单写了什么,agent 就做到了什么。三次 Opus 5.5 运行里,"无效优惠码不影响支付"对过期、停用和不存在的优惠码都成立。

没写明的规则全凭运气

有一次运行认定优惠券不限使用次数,还在总结里说明了这一点。它自己写的测试也通过了,因为测试是按它自己选的规则写的。

接口在悄悄漂移

每次模糊运行遇到无效优惠码都会抛异常;spec 运行则按 AC-2 的要求返回 { ok: false, reason }。没有哪项隐藏检查因此失败,但按其中一种写的前端,换到另一种就会出错。

写给 agent 的验收标准:六条规则

规则弱写法强写法
每条都编号一串期望的要点AC-1 到 AC-n,测试、工单和评审意见都引用编号
写明接口和确切结果"无效优惠码显示错误""applyCoupon 返回 { ok: false, reason: 'expired' },不抛异常"
写下需求默认的规则完全没提使用次数"一张优惠券每个用户只能用一次,订单支付后才算使用。"
覆盖两个步骤之间可能变化的状态应用优惠券时校验一次"在 pay 里重新检查是否已被使用"
描述行为,而不是实现"用一个 helper 校验优惠券"写接口上可观察的结果;helper 是任务,不是验收标准
确认每条现在都不成立当前代码已经满足的标准说出能证明它不成立的观察,并确认改动前它确实失败

第三条和第四条,是人类同事几乎从不需要写下来、而 agent 每次都需要的。同事知道业务,会默认优惠券只能用一次;agent 去读数据,发现没有限制,于是就不加限制。更通用的 Given/When/Then 写法,可以看我们的验收标准示例指南。

可复制的验收标准模板

把这段放进 spec.md 或工单里。规则那一节即使看起来理所当然也要保留,没写明的决定就放在那里。

acceptance-criteria.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_...)。
- 每个测试在改动之前的提交上都会失败。

实例:优惠券实测中使用的 spec

下面是 agent 实际收到的 spec 中的验收标准部分,原文取自运行记录包。有了它,三次 Opus 5.5 运行都通过了全部隐藏检查,并做出了相同的决定。

coupon-spec.md
## 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 起草验收标准

AI 验收标准生成器(包括本站的)擅长格式和显而易见的情况,却恰恰在最要紧的地方很弱:需求没说清的那些决定。让模型写验收标准,它会用看似合理的猜测把空白填上。更好的做法是让它把空白列出来。

draft-criteria-prompt.md
你在为一个编码 agent 起草验收标准。不要自己决定业务规则。
针对下面的需求:

1. 把需求里所有没定下来的决定列成问题:次数限制、适用对象、
   什么时候算数、失败时怎么办、两个步骤之间可能变化的状态。
2. 只为已经定下来的部分起草编号的验收标准 AC-1..n。
   每条都写明函数、端点或页面,输入,以及确切的结果或错误码。
3. 标出当前代码已经能通过的那些标准。

需求:
[粘贴工单]

使用 AI 起草的清单前先检查

  • 它有没有自己编出一条规则(比如使用次数限制),而不是提问?
  • 每条标准都写明了接口和确切结果吗?
  • 至少有一条失败路径、一条边界或权限情况吗?
  • 每条标准在现在的代码上都会失败吗?
  • 有没有哪条描述的是实现而不是行为?

本站的生成器

Gherkin 生成器能把用户故事转成 .feature 文件里的 Given/When/Then 场景。规格包生成器会把验收标准连同范围、任务和证据清单一起起草。两者都在浏览器里运行,无需注册;把它们的输出当作初稿,按左边的清单检查。

从验收标准到评审证据

验收标准的价值在评审时兑现。要求每条标准一个测试,以标准编号命名,并确认每个测试在改动之前的提交上会失败;一个从没失败过的测试,证明不了让它通过的那段代码。然后读 diff,找出对应不到任何标准的行为:多出来的状态、改了名的字段、新加的依赖。把它们当作漂移,移到后续 spec 里,而不是因为看起来有用就顺手合并。AI PR 评审清单逐步讲了这一步。

相关资源

验收标准示例

功能、API 和边界情况的 Given/When/Then 写法。

阅读指南

agent 运行记录

上表背后每次运行的提示词、diff 和隐藏测试分数。

查看运行记录

Vibe coding 与 spec coding

78 次运行里,agent 拿到 spec 而不是一句提示词时,结果有什么不同。

查看对比

常见问题

什么是 AI 编码的验收标准?

它是一组编号的、可测试的陈述,说明一项改动必须做到什么,写法要让编码 agent 能据此实现,测试或评审者不必追问含义就能检查结果。和写给人看的验收标准相比,它需要写明接口和确切结果,并把人类同事会默认的业务规则也写出来。

AI 能写验收标准吗?

它能把格式和显而易见的情况起草得很好,但不应该替你做决定,比如一张优惠券能用几次、两个步骤之间状态变了怎么办,因为这些正是需求没说清的空白。让模型把未决事项列成问题,再由人来回答。

一个 AI 编码任务需要几条验收标准?

通常三到七条:主要行为、至少一条失败路径,以及边界或权限情况。我们实测中使用的优惠券 spec 有六条验收标准,外加三条写明的业务规则。

验收标准要写函数名或文件名吗?

要写出观察行为所依赖的公开接口,比如函数、端点或页面,因为测试就在那里运行。不要写要改哪些内部 helper 或文件,那些属于范围或计划,不属于验收标准。

用 Given/When/Then 还是普通句子?

只要每条标准都写明起始状态、动作和可观察的结果,两种都可以。Given/When/Then 让这三部分很难漏掉;普通句子更短。优惠券 spec 用的是普通句子,但写明了函数名和返回值。

在 agent 写代码之前,写出评审者不需要你帮忙也能测试的验收标准,包括那些你从没想过要说出口的规则。

复制模板