Lesson 0012 · Engineering · 人和 AI 都能启动（model-invoked）· 纪律课

tdd：让红绿循环产出值得留下的测试

你让 AI 给购物车加一个折扣功能。它一口气写出十二个测试，再一口气写完全部实现， 跑一遍全绿，看起来很专业。两周后你把内部一个函数改了个名字，十二个测试红了九个—— 行为其实一点没变。这就是 tdd 这条 skill 要防的事： 测试写了一大堆，却什么也没锁住。 tdd 是 red → green 循环（先写一个失败的测试，再写刚好够让它通过的代码）的纪律参考书： 什么是好测试、测试写在哪、三个反面模式、循环的三条规则。 它是 model-invoked 的（人和 AI 都能启动），也是 implement 在内部驱动的那台引擎。 学完这节课，你能说出它什么时候被触发、每个循环会改哪些文件、 为什么它坚持「一次只切一片」、以及行为不对时该改哪个文件的哪一段。

1. 它在整个系统里站在哪

0001 把 22 个已发布 skill 分成三层：配置层（跑一次性的初始设置）、编排层（你手动启动的完整流程）、 纪律层（被反复调用的基本功，一般不独立交付什么，而是被编排层调用）。 tdd 属于纪律层，和 codebase-design（0005）、domain-modeling（0004）同层。 但同层里有分工：那两个是词汇地板（只统一用词，不规定动作）， tdd 是动作纪律——它规定一个循环怎么转：先红后绿、一次一片、重构不进循环。

它在主流程里的位置很特殊：它不是主流程上独立的一步，而是某一步内部的引擎。 主流程的构建链是 grill-with-docs → to-spec → to-tickets → implement → code-review， 其中 implement（只能人启动）是构建步骤，它在内部驱动 tdd 把每张工单（Issue）test-first 地做出来，然后才交给 code-review。 人读文档的原话是：tdd 是「the engine inside that step rather than a step of its own」 （那一步内部的引擎，而不是独立的一步）。

grill-with-docs → to-spec → to-tickets → implement → code-review
                                              │
                                              ├─ 内部驱动 /tdd（一次一片红绿切片）
                                              │     · 会读 CONTEXT.md / ADR 对齐命名
                                              │     · 只在预先确认的接缝上写测试
                                              │
                                              └─ 收尾跑 /code-review，然后 commit

它同时也是一个可以单独伸手拿的工具：当你手里有一个具体行为要做、 又不想走完整的 spec 流程时，直接 /tdd 就行。 ask-matt 的路由原话：「Reach for /tdd on its own when you just want to build a concrete behaviour test-first without a full spec」 （只想 test-first 地做一个具体行为、不需要完整 spec 时，单独用它）。

地图：0001 系统地图（纪律层一行、主流程一节）· 路由：ask-matt/SKILL.md 主流程第 3 步 · 人读文档：docs/engineering/tdd.md 的 Where it fits 一节

2. 调用方式与触发场景

2.1 两种启动方式

tdd 的 SKILL.md frontmatter 里没有 disable-model-invocation 字段，目录下的 agents/openai.yaml 也只有展示名（display_name: "TDD"）和一句展示简介，没有禁止隐式调用的策略—— 所以它是 model-invoked：你可以手动敲 /tdd， AI 也会在任务合适时自己加载它。AI 自动加载的依据是 frontmatter 的 description 字段，原文是：

Test-driven development. Use when the user wants to build features
or fix bugs test-first, mentions "red-green-refactor", or wants
integration tests.

三个触发条件，逐个翻译一下：

• 想 test-first 地做功能或修 bug——「先写测试再写实现」这个意图本身就是触发词。
• 提到 "red-green-refactor"——这个经典口号被写进了触发词。注意一个张力：口号里有 refactor，但循环规则把重构赶出了循环（见第 3 节和第 9.3 节，行为不对该改哪里）。
• 想要 integration tests（集成测试）——因为这套纪律里的好测试就是「集成风格」的：走真实接口，不 mock 内部零件（见第 5 节）。

2.2 什么时候该用，什么时候别用

人读文档把边界划得很清楚：手里有一个具体行为（concrete behaviour）要构建， 并且想要扛得住重构的测试——用它。行为本身还没定下来、或者问题出在别处时，去别的地方：

触发条件： skills/engineering/tdd/SKILL.md 的 frontmatter · 展示配置：agents/openai.yaml · 边界划分：docs/engineering/tdd.md 的 When to reach for it 一节 · 硬 bug 路由：ask-matt/SKILL.md 的 On-ramps 一节

3. 红绿循环的三条规则

SKILL.md 开篇第一句给这个 skill 定了性： 「TDD is the red → green loop. This skill is the reference that makes that loop produce tests worth keeping」（TDD 就是红 → 绿循环；这条 skill 是让这个循环 产出值得留下的测试的参考书）。它还立了一条使用规矩： 「Every section applies on every cycle — consult them before and during the loop, not after」（每一节在每个循环上都适用——在循环之前和之中查阅，而不是事后）。 换句话说，这不是一份「出问题了才翻」的故障手册，而是每转一圈循环都要对照的戒律。

循环本身只有三条规则，全部照录 SKILL.md 的 Rules of the loop 一节：

规则原文： skills/engineering/tdd/SKILL.md 的 Rules of the loop 一节 · 展示简介：agents/openai.yaml · 「绿了才重构」：docs/engineering/tdd.md 的 Red-green, one slice at a time 一节

4. 接缝：测试写在哪，谁来定

seam（接缝）这个词你在 0005 已经学过：codebase-design 给它的定义是 「不用改那处代码就能换行为的位置，也就是接口所在的位置」。 tdd 的 SKILL.md 给了同一个词一个面向测试的工作定义： 「A seam is the public boundary you test at: the interface where you observe behavior without reaching inside」（接缝是你在上面做测试的公共边界：不伸手进内部、 就能观察到行为的那个接口）。两句话说的是同一件事： 测试活在接缝上，永远不顶着内部写。

为什么要先确认？SKILL.md 给了理由：你不可能什么都测， 事先约定接缝，是让测试火力落在关键路径和复杂逻辑上、而不是撒在每个边角案例上的方法。 这也解释了为什么这条 skill 和 codebase-design 是邻居： 找「值得测的接缝」需要的正是深模块词汇——接缝选在哪，本质上是模块形状问题（0005 第 3、6 节）。 人读文档明说：tdd 在规划阶段会调用 codebase-design 的深模块词汇。

上游也在为这句话做准备：to-spec 写需求文档时会先画测试接缝的草图并和你确认 （0009 会讲），implement 的正文只有几行，其中一行就是 「Use /tdd where possible, at pre-agreed seams」（尽量用 /tdd，在预先约定的接缝上）。 所以「先确认接缝」不是 tdd 一条 skill 的怪癖，而是从 spec 到 implement 到 tdd 一路传下来的接力棒。

接缝定义与确认纪律： skills/engineering/tdd/SKILL.md 的 Seams 一节 · 词汇同源：codebase-design/SKILL.md（0005 第 3 节）· 接力棒：implement/SKILL.md

5. 什么是好测试

SKILL.md 的判据：测试通过公共接口验证行为，不验证实现细节 （implementation details，代码内部的具体写法）。代码可以整个换掉，测试不应该跟着动。 一个标志是：好测试读起来像一份规格说明—— 「user can checkout with valid cart」（用户能用有效购物车结账）这种名字， 一看就知道系统具备什么能力，而且它不关心内部结构，所以扛得住重构。

sibling 文件 tests.md 把好测试的特征列成了五条，照录并翻译：

• 测的是用户或调用者关心的行为；
• 只走公共 API；
• 扛得住内部重构；
• 描述 WHAT（是什么能力），不描述 HOW（怎么实现的）；
• 每个测试只有一个逻辑断言（one logical assertion：一个测试只验证一件事，中间可以有多行准备，但断言的是同一件事的同一个结果）。

tests.md 给的对照例（「绕过接口去外部验证」是最常见的坏味道）：

// BAD：绕过接口，直接查数据库验证
test("createUser saves to database", async () => {
  await createUser({ name: "Alice" });
  const row = await db.query("SELECT * FROM users WHERE name = ?", ["Alice"]);
  expect(row).toBeDefined();
});

// GOOD：通过接口验证——存进去的东西能再取出来
test("createUser makes user retrievable", async () => {
  const user = await createUser({ name: "Alice" });
  const retrieved = await getUser(user.id);
  expect(retrieved.name).toBe("Alice");
});

坏测试的名字「saves to database」描述的是 HOW（怎么存的），好测试的名字 「makes user retrievable」描述的是 WHAT（调用者得到什么能力）。哪天实现从 SQL 数据库换成内存仓库，坏测试全红，好测试照绿。

还有一条容易漏看的规矩：SKILL.md 要求探索代码库时读项目的 CONTEXT.md（如果存在），让测试名字和接口用词与项目的领域语言对齐， 并尊重改动区域里的 ADR（架构决策记录，0004 讲过）。 也就是说 tdd 不只往仓库里写测试，它还消费 0004 那条词汇地板产出的领域语言—— 测试名里的 Order、Account 这些词，应该和 CONTEXT.md 里的一模一样。

判据原文： skills/engineering/tdd/SKILL.md 的 What a good test is 一节 · 五条特征与对照例：skills/engineering/tdd/tests.md · 领域语言对齐：SKILL.md 第 10 行（读 CONTEXT.md、尊重 ADR）

6. 三个反面模式

SKILL.md 的 Anti-patterns 一节列了三个反面模式，每个都给了「识别信号」（tell）。 这张表值得背下来——AI 写测试跑偏，基本都落在这三个坑里。

tests.md 给同义反复测试的对照例，很直观：

// BAD：期望值用和代码一样的方式现算
test("calculateTotal sums line items", () => {
  const items = [{ price: 10 }, { price: 5 }];
  const expected = items.reduce((sum, i) => sum + i.price, 0);
  expect(calculateTotal(items)).toBe(expected);
});

// GOOD：期望值是独立的、已知正确的字面量
test("calculateTotal sums line items", () => {
  expect(calculateTotal([{ price: 10 }, { price: 5 }])).toBe(15);
});

人读文档还给了一段「它运转正常的标志」（It's working if），可以当验收清单用：

• 它写一个测试、让它通过、然后才写下一个——不是一批测试接一批代码；
• 测试命名的是行为而不是内部零件，内部函数改名不会弄红它们；
• 期望值是来自 spec 的字面量，不是用代码同款算法推出来的数字。

三反模式原文： skills/engineering/tdd/SKILL.md 的 Anti-patterns 一节 · 对照例：skills/engineering/tdd/tests.md · 曳光弹与验收清单：docs/engineering/tdd.md

7. mock 纪律：只在系统边界

mock（仿冒：用一个受控的假对象替换真实协作者）是测试变脆的最大来源， 所以 sibling 文件 mocking.md 整篇只做一件事：划定哪里可以 mock。 规则一句话：只在系统边界 mock。

注意「数据库」和「文件系统」都标了「有时」，而且数据库那条附了「优先测试数据库」—— 这和 0005 讲的 DEEPENING 分类完全对得上：本地可替代的依赖（比如用 PGLite 顶替 Postgres） 应该用本地替身，而不是开 mock；只有你控制不了的真外部依赖才落到 mock。

7.1 为「可 mock」而设计

mocking.md 还给了两条设计建议，让边界上的接口天然好 mock：

1. 用依赖注入（dependency injection：把依赖从参数传进来，而不是在函数内部自己 new 一个）。 原文的对照例：processPayment(order, paymentClient) 好 mock， 因为 paymentClient 是传进来的；processPayment(order) 内部 new StripeClient(process.env.STRIPE_KEY) 难 mock，因为边界被焊死在函数体里。 这正是 0005 第 6 节「Accept dependencies, don't create them」的落地。
2. 要 SDK 风格的接口，不要通用 fetcher。 给每个外部操作写一个具体函数（getUser(id)、getOrders(userId)、 createOrder(data)），而不是一个带条件逻辑的通用 fetch(endpoint, options)。好处原文列了四条：每个 mock 只返回一种固定形状； 测试准备里没有条件分支；一眼看出测试覆盖了哪些端点；每个端点有独立的类型安全。

全部引文： skills/engineering/tdd/mocking.md · 对照 0005： codebase-design/DEEPENING.md 的依赖四类

8. 它依赖谁、谁依赖它

                ┌──────────────────────────┐
                │  codebase-design（0005）  │  词汇地板：seam / interface
                └────────────┬─────────────┘
                             │ 规划时引用深模块词汇来找值得测的接缝
                             ▼
   CONTEXT.md / ADR ──读──► ┌──────────┐      写完测试+最小实现
   （domain-modeling 产出） │   tdd    │ ──────────────────────► 代码库
                            └────┬─────┘
                                 ▲
                                 │ 内部驱动（每张工单逐片红绿）
              ┌──────────────────┴───────────┐
              │  implement（0011，User）      │ ──收尾──► code-review（0013）──► commit
              └──────────────────────────────┘

   平级表亲：diagnosing-bugs（0015）——硬 bug 走它，收尾的回归测试与红绿纪律同源

调用方原文：implement/SKILL.md · 路由与表亲：ask-matt/SKILL.md · 词汇来源：docs/engineering/tdd.md 的 Where it fits 一节

9. 会留下什么、用完接什么、想微调改哪里

9.1 副作用：写哪些文件，读哪些文件

9.2 用完之后，下一步去哪

1. 在 implement 内部被驱动的 → 不用你操心：implement 会继续跑完整测试套件、调 /code-review（0013）、提交。看到它在循环里，等它走完就行。
2. 单独用 /tdd 做完一个行为 → 套件全绿后，接 /code-review 做双轴审查（Standards + Spec），重构也在那个阶段做；然后由你或 implement 提交。
3. 循环中发现行为根本没定清楚 → 停下来，回 to-spec（0009）把 spec 定下来再继续；tdd 的触发条件本来就要求「行为已具体」。
4. 发现真正的问题是接口形状（接缝怎么切都不顺手） → 去 codebase-design（0005）做形状设计，必要时走它的 design-it-twice；形状定了再回来转循环。
5. 测试怎么写都脆、找不到能锁住行为的接缝 → 这和 diagnosing-bugs 复盘时的发现是同一类信号：交接给 improve-codebase-architecture（0017）找加深机会。

9.3 行为不对时，去改哪个文件的哪一段

10. 检索练习

先别往回翻，凭记忆答。选项长度刻意对齐，不会从版式泄题。判据以本课和 SKILL.md 的原文为准。

11. 下一课与一手材料

本课主一手材料（请打开原文读，不要只背本页摘要）：

• skills/engineering/tdd/SKILL.md —— 定性、好测试判据、接缝纪律、三个反面模式、循环三规则。本课的单一权威出处。
• …/tests.md —— 好测试五条特征、坏测试红旗清单、旁路验证与同义反复的对照例。
• …/mocking.md —— 只在系统边界 mock、依赖注入、SDK 风格接口。
• docs/engineering/tdd.md —— 给人看的叙事版：曳光弹、「不开过头灯」、验收清单、在流程里的位置 （aihero.dev/skills-tdd）。
• 关系对照： implement（最主要的调用方）· ask-matt（路由与表亲）· codebase-design（词汇来源）。

速查页（本课同步）： reference/tdd.html

导航： 上一课 0011 implement （tdd 最主要的调用方，那条只有几行正文的 user-invoked 入口）。 总览仍回 0001 系统地图； 词汇地板见 0005 codebase-design。

建议下一课（0013）： 0013 code-review——tdd 把重构赶出循环时点名的地方。 红绿循环只管「让行为被测试锁住」，代码干不干净、和 spec 对不对得上， 是 review 阶段那条双轴审查（Standards + Spec）的事。implement 的收尾也是它： 跑完 code-review 才 commit。