SeedlingPlanted Tended 6 min read

用例子写规格: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 / CucumberMatt Pocock 的 skills
主要写给谁人(产品、测试、开发)和运行器AI agent,人在关键点拍板
规格长什么样一个个具体例子:假如 / 当 / 那么一份 PRD:一长串用户故事 + 实现和测试决定
验收落在哪.feature 文件本身,由 Cucumber 执行代码测试,挂在少数几条高层的缝上
要维护什么自然语言句子 + 步骤定义胶水测试代码;没有自然语言胶水
覆盖的范围「做完是什么样」这一段从讨论到拆票到写代码的整条路
主要风险胶水没人维护;没接运行器就过期用户故事和测试之间靠人和 agent 自己对齐

相同的地方:都从用户故事或具体例子出发;都要求「做完的定义」写在代码之前;都只看外部行为,不看内部怎么实现。

可以合起来用:to-tickets 拆出来的每张票,验收标准可以直接写成「假如 / 当 / 那么」的场景。到 tdd 阶段,把这些场景一条条写成缝上的测试。这样既有人人看得懂的例子,又不用维护一套步骤定义胶水。

一句话:Gherkin 让「例子」本身变成能跑的规格;Matt Pocock 的 skills 把「从想法到代码」变成 agent 能走的流程。前者重在把话说清,后者重在把事做完,两者可以接在一起。