@tanlinfeng/project-docs-workflow 0.0.0-stage → 2.0.0

package/skills/tdd/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: tdd
+description: 测试驱动开发。当用户想以测试先行方式构建功能或修 bug、提到 "red-green-refactor"、或需要集成测试时使用。
+---
+
+# TDD（测试驱动开发）
+
+> 轻量精简版，裁剪自 [mattpocock/skills](https://github.com/mattpocock/skills) 的 tdd（MIT License, Copyright (c) 2026 Matt Pocock）。若环境已安装同名完整 skill，请优先使用完整版。
+
+TDD 就是 red → green 循环。本 skill 是让这个循环产出**值得保留**的测试的参考：什么算好测试、测试放哪里、反模式、以及循环的规则。每一节在**每个循环**都适用——在循环前和循环中都查阅，而不是事后。
+
+探索代码库时读 `CONTEXT.md`（若存在），让测试名与接口词汇匹配项目领域语言，并遵守所涉区域的 ADR。
+
+## 什么是好测试
+
+测试通过**公共接口**验证行为，而非实现细节。代码可以整个换掉，测试不应跟着变。好测试读起来像规格说明：「user can checkout with valid cart」准确告诉你存在什么能力，且因为不关心内部结构，能扛住重构。
+
+特征：测试用户/调用方真正关心的行为；只用公共 API；重构后仍存活；描述 WHAT 而非 HOW；每个测试一个逻辑断言。
+
+## Seam：测试放哪里
+
+**seam（接缝）** 是你据以测试的公共边界：无需伸手进内部即可观察行为的接口。测试住在 seam 上，绝不针对内部。
+
+- **只在事先约定的 seam 上测试。** 写任何测试前，先写下待测 seam 并与用户确认。未确认的 seam 上不写测试。你无法测试一切，事先约定 seam 才能把测试精力落在关键路径和复杂逻辑上，而不是每个边界情况。
+- 问：「公共接口是什么？我们该测哪些 seam？」
+
+当接口形状本身存疑（模块多深、seam 该在哪、接口暴露什么）时，调用 `codebase-design` skill 获取 module / interface / depth / seam / adapter / leverage / locality 的共享词汇；它是参考，不是要跑的一次会话。
+
+## 反模式
+
+- **耦合实现**：mock 内部协作者、测私有方法、或走旁路验证（绕过接口直接查数据库）。信号：重构后行为未变，测试却坏了。
+- **同义反复（tautological）**：断言以代码的算法重算期望值（`expect(add(a, b)).toBe(a + b)`、手工按同样方式推出的快照、常量自比），于是它只会通过、永远无法与代码唱反调。期望值必须来自独立真相源：已知良好的字面量、算好的例子、规格。
+- **横切切片**：先写完所有测试，再写所有实现。批量测试验证的是**想象中**的行为：测的是事物的**形状**而非面向用户的行为，测试对真实变化变得迟钝，且你在理解实现前就锁定了测试结构。改用**纵向切片**：一个测试 → 一个实现 → 重复，每个测试都是**曳光弹**，回应上一轮学到的东西。
+
+## 循环规则
+
+- **先红后绿。** 先写失败的测试，再只写刚好让它通过的代码。不要预判未来测试或加投机功能。
+- **一次一片。** 每个循环一个 seam、一个测试、一个最小实现。
+- **重构不属于循环。** 它属于评审阶段（见 `code-review` skill），不属于 red → green 实现循环。
+
+## 模拟（mock）
+
+**只在系统边界 mock**：外部 API（支付、邮件等）、数据库（有时——优先用测试库）、时间/随机性、文件系统（有时）。
+
+**不要 mock**：你自己的类/模块、内部协作者、任何你控制得了的东西。
+
+边界接口的设计要便于 mock：
+
+- **依赖注入**：把外部依赖传进来，而不是在内部创建。`processPayment(order, paymentClient)` 好过内部 `new StripeClient(...)`。
+- **优先 SDK 式接口而非通用 fetcher**：每个外部操作一个具体函数（`getUser` / `getOrders` / `createOrder`），而不是一个带条件逻辑的通用 `fetch`。这样每个 mock 只返回一种确定形状，测试准备里没有条件逻辑，也更容易看出测试覆盖了哪些端点。

package/skills/tdd/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "TDD"
+  short_description: "Test-driven red-green-refactor"