用例子写规格:Gherkin 和 Matt Pocock 的 skills 有什么不同
Gherkin 把验收例子写成人人看得懂、机器能执行的句子;Matt Pocock 的 skills 把讨论、规格、拆票、测试做成给 AI agent 走的流水线。两者怎么分工、怎么接在一起。
先说结论:两套东西想解决同一件事,在动手写代码之前,先把「做完是什么样」说清楚。不同的是落点。Gherkin 把验收例子写成大家都看得懂的句子,再让机器照着跑。Matt Pocock 的 skills 把「讨论 → 规格 → 拆票 → 测试」做成一条给 AI agent 走的流水线,验收最后落在代码测试里。
这篇是我的个人笔记。我在工作仓库里见过一批中文 .feature 文件,又在本机装了 Matt Pocock 那几个 skill,就把两边放在一起对照了一下。
第一部分:Gherkin、.feature 和 Cucumber
三个名字,各管一件事
打个比方:做菜要有菜谱的格式、写好的菜谱、照菜谱做菜的厨师。
| 比方 | 真名 | 它是什么 |
|---|---|---|
| 菜谱的格式 | Gherkin | 一套写法规则。关键词是 Feature、Scenario、Given、When、Then。 |
| 一本写好的菜谱 | .feature 文件 | 用 Gherkin 写出来的文件。一个文件讲一个功能。 |
| 照菜谱做菜的厨师 | Cucumber | 运行器。它读 .feature,把每句话连到一段代码去执行,跑完告诉你过没过。 |
每句话连到代码的那一段,叫 step definition(步骤定义)。Cucumber 本身有很多语言的版本,Go 里常用 godog,JS 里可以用 playwright-bdd。
Gherkin 支持中文。文件第一行写 # language: zh-CN,关键词就能换成中文:
| 英文 | 中文 | 意思 |
|---|---|---|
Feature | 功能 | 这个文件讲哪个功能 |
Scenario | 场景 | 一个具体的例子 |
Given | 假如 | 开始时是什么状态 |
When | 当 | 发生了一个动作 |
Then | 那么 | 能检查的结果 |
And / But | 而且 / 但是 | 接着上一句补充 |
背后的想法:用例子说清规格
这一派叫 BDD(行为驱动开发),它的核心想法叫 Specification by Example:别写一大段抽象的需求,而是对着具体的例子,讲清楚做完是什么样。
- 用业务的话写。产品、测试、开发都能读懂,不用懂代码。
- 一个场景就是一个例子。「假如」写开始的状态,「当」写一个动作,「那么」写能检查的结果。
- 接上 Cucumber 就成了活文档。规格和代码对不上,测试就变红。文档不会悄悄过期。
一个例子
下面是我自己编的通用场景:发布新版本时,出错率超过阈值,系统先暂停,再由人决定要不要回滚。
# language: zh-CN
功能: 灰度发布出错时先暂停,由人决定回滚
背景:
假如 服务 "订单" 正在灰度发布新版本
而且 出错率阈值是 5%
@AC-01
场景: 出错率超过阈值时暂停发布
假如 新版本已经放量到 20%
当 最近 5 分钟的出错率达到 8%
那么 发布状态变成 "已暂停"
而且 值班人收到一条告警,里面写着出错率 8%
但是 系统不会自动回滚
@AC-02
场景: 人确认回滚后才回滚
假如 发布状态是 "已暂停"
当 值班人点了 "回滚"
那么 流量全部切回旧版本
而且 发布记录里写下操作人
@AC-03
场景大纲: 出错率没到阈值时继续放量
假如 新版本已经放量到 <当前比例>
当 最近 5 分钟的出错率是 <出错率>
那么 放量比例变成 <下一比例>
例子:
| 当前比例 | 出错率 | 下一比例 |
| 20% | 1% | 50% |
| 50% | 4.9% | 100% |
几个写法要点
- 背景(
Background)放所有场景都要的前提,免得每个场景重复写。 - 场景大纲 + 例子表(
Scenario Outline+Examples):同一个句式换几组数,用一张表写完。 - 标签(如
@AC-01)把场景连到验收规则。一条规则有没有场景覆盖,一查就知道。 - 用「但是」写不该发生的事。上面的「但是 系统不会自动回滚」就是在守一条边界。
- 「假如」里不写动作,只写状态。「当」只写一个动作。一个场景里出现两个「当」,多半该拆成两个场景。
常见的坑
- 把界面点击写进去。「当 我点击右上角第二个按钮」——这是脚本,不是规格。界面一改,句子就全错了。要写「当 值班人选择回滚」这种业务动作。
- 步骤定义越写越多,没人维护。每种说法都对应一段胶水代码,说法一多,胶水就乱。
- 写了
.feature却从没接运行器。那它就只是一份文档,会和代码慢慢对不上,失去「活文档」的意义。
一句话:Gherkin 是格式,.feature 是按格式写好的例子,Cucumber 让这些例子真的能跑。
第二部分:Matt Pocock 的 skills
Matt Pocock 写了一组给 Claude Code 用的 skill(技能,就是一段写给 AI agent 的工作说明)。我本机装的有四个,串起来正好是一条从想法到代码的流水线:
grilling → to-spec → to-tickets → tdd
grilling:先把问题问透
比方:动工前,师傅追着你一条条问清楚。
- 把决策树的每条分支都走一遍,一个决定一个决定地解决。
- 一次只问一个问题,等你回答完再问下一个。原文的理由是:一次问一堆会让人发懵。
- 每个问题都附上它推荐的答案。
- 事实自己查,决定交给人。文件里、工具里能查到的事实,agent 自己去查;要拍板的事,一条条问你。
- 没确认「我们已经想法一致」之前,不动手。
to-spec:把聊过的东西写成规格
这一步不再访谈,直接把前面聊过的内容合成一份规格(也就是 PRD)。
- 先定测试缝。缝(seam)就是测试站的那条公开边界:从这里看行为,不伸手进内部。原文要求:优先用已有的缝;越高越好;越少越好,理想是只有一条。定好后要和人确认。
- 规格的固定段落:问题(用户视角)、方案(用户视角)、用户故事、实现决定、测试决定、不做什么、补充说明。
- 用户故事要列很长一串,格式是
As an <actor>, I want a <feature>, so that <benefit>(作为谁,我想要什么,为了什么)。 - 规格里不写具体文件路径和代码片段,因为它们很快会过时。
to-tickets:拆成能单独演示的小票
比方:不是先盖完一整层地基再盖一整层墙,而是先打通一条从地下到楼顶的细管子。
- 每张票是一个 tracer bullet(曳光弹)式的纵向切片:窄,但穿透每一层(数据结构、接口、界面、测试),做完就能单独演示或验证。
- 每张票的大小,要能放进一次全新的上下文里做完。
- 每张票写明被哪些票卡住(blocking 边)。没被卡的票马上能做。
- 开工从「前沿」开始:所有卡它的票都做完了,它就能做。
- 拆完先给人看:粒度合不合适、依赖对不对、要不要合并或再拆。
- 例外:大面积的机械改动(比如改一个到处都在用的字段名),一改就会弄坏成千上万处调用,没法切成纵向小票。这时用 expand–contract:先加新形式、旧的留着;再分批把调用方迁过去;最后没人用旧的了再删掉。
tdd:红 → 绿
- 先写一个会失败的测试(红),再写刚好够它通过的代码(绿)。
- 只在事先商量好的缝上写测试,测外部行为,不测内部实现。好测试读起来就像规格。
- 一次只做一个切片:一条缝、一个测试、一点实现。
- 要避开的写法:和实现绑死的测试(一重构就坏、行为却没变);同义反复的测试(用和代码一样的算法算期望值,永远不会失败);先把所有测试一口气写完再写实现。
- 值得一提:这个版本的 skill 明确说重构不在这个循环里,而是放到之后的代码审查阶段。所以它是「红 → 绿」,不是常说的「红 → 绿 → 重构」。
一句话:先问透,再写规格,再拆成能演示的小票,最后用测试一点点做出来。
两边对照
| Gherkin / Cucumber | Matt Pocock 的 skills | |
|---|---|---|
| 主要写给谁 | 人(产品、测试、开发)和运行器 | AI agent,人在关键点拍板 |
| 规格长什么样 | 一个个具体例子:假如 / 当 / 那么 | 一份 PRD:一长串用户故事 + 实现和测试决定 |
| 验收落在哪 | .feature 文件本身,由 Cucumber 执行 | 代码测试,挂在少数几条高层的缝上 |
| 要维护什么 | 自然语言句子 + 步骤定义胶水 | 测试代码;没有自然语言胶水 |
| 覆盖的范围 | 「做完是什么样」这一段 | 从讨论到拆票到写代码的整条路 |
| 主要风险 | 胶水没人维护;没接运行器就过期 | 用户故事和测试之间靠人和 agent 自己对齐 |
相同的地方:都从用户故事或具体例子出发;都要求「做完的定义」写在代码之前;都只看外部行为,不看内部怎么实现。
可以合起来用:to-tickets 拆出来的每张票,验收标准可以直接写成「假如 / 当 / 那么」的场景。到 tdd 阶段,把这些场景一条条写成缝上的测试。这样既有人人看得懂的例子,又不用维护一套步骤定义胶水。
一句话:Gherkin 让「例子」本身变成能跑的规格;Matt Pocock 的 skills 把「从想法到代码」变成 agent 能走的流程。前者重在把话说清,后者重在把事做完,两者可以接在一起。