sdd-full 4.2.0 → 4.3.1

package/skills/test-driven-development/SKILL.md

@@ -1,371 +0,0 @@
----
-name: test-driven-development
-description: 在实现任何功能或修复 bug 时使用，在编写实现代码之前
----
-
-# 测试驱动开发（TDD）
-
-## 概述
-
-先写测试。看它失败。写最少的代码让它通过。
-
-**核心原则：** 如果你没有看到测试失败，你就不知道它是否测试了正确的东西。
-
-**违反规则的字面意思就是违反规则的精神。**
-
-## 何时使用
-
-**始终使用：**
-- 新功能
-- Bug 修复
-- 重构
-- 行为变更
-
-**例外（需询问你的人类伙伴）：**
-- 一次性原型
-- 生成的代码
-- 配置文件
-
-想着"就这一次跳过 TDD"？停下来。那是在给自己找借口。
-
-## 铁律
-
-```
-没有失败的测试，就不写生产代码
-```
-
-先写了代码再写测试？删掉它。从头来过。
-
-**没有例外：**
-- 不要保留作为"参考"
-- 不要在写测试时"改编"它
-- 不要看它
-- 删除就是删除
-
-从测试出发，重新实现。句号。
-
-## 红-绿-重构
-
-```dot
-digraph tdd_cycle {
-    rankdir=LR;
-    red [label="红灯\n编写失败的测试", shape=box, style=filled, fillcolor="#ffcccc"];
-    verify_red [label="验证正确失败", shape=diamond];
-    green [label="绿灯\n最少代码", shape=box, style=filled, fillcolor="#ccffcc"];
-    verify_green [label="验证通过\n全部绿灯", shape=diamond];
-    refactor [label="重构\n清理代码", shape=box, style=filled, fillcolor="#ccccff"];
-    next [label="下一个", shape=ellipse];
-
-    red -> verify_red;
-    verify_red -> green [label="是"];
-    verify_red -> red [label="错误的\n失败"];
-    green -> verify_green;
-    verify_green -> refactor [label="是"];
-    verify_green -> green [label="否"];
-    refactor -> verify_green [label="保持\n绿灯"];
-    verify_green -> next;
-    next -> red;
-}
-```
-
-### 红灯 - 编写失败的测试
-
-写一个最小的测试来展示期望行为。
-
-<Good>
-```typescript
-test('retries failed operations 3 times', async () => {
-  let attempts = 0;
-  const operation = () => {
-    attempts++;
-    if (attempts < 3) throw new Error('fail');
-    return 'success';
-  };
-
-  const result = await retryOperation(operation);
-
-  expect(result).toBe('success');
-  expect(attempts).toBe(3);
-});
-```
-名称清晰，测试真实行为，只测一件事
-</Good>
-
-<Bad>
-```typescript
-test('retry works', async () => {
-  const mock = jest.fn()
-    .mockRejectedValueOnce(new Error())
-    .mockRejectedValueOnce(new Error())
-    .mockResolvedValueOnce('success');
-  await retryOperation(mock);
-  expect(mock).toHaveBeenCalledTimes(3);
-});
-```
-名称模糊，测试的是 mock 而非代码
-</Bad>
-
-**要求：**
-- 一个行为
-- 清晰的名称
-- 使用真实代码（除非不得已才用 mock）
-
-### 验证红灯 - 看它失败
-
-**必须执行。绝不跳过。**
-
-```bash
-npm test path/to/test.test.ts
-```
-
-确认：
-- 测试失败（不是报错）
-- 失败信息符合预期
-- 失败原因是功能缺失（不是拼写错误）
-
-**测试通过了？** 你在测试已有的行为。修改测试。
-
-**测试报错了？** 修复错误，重新运行直到它正确地失败。
-
-### 绿灯 - 最少代码
-
-写最简单的代码让测试通过。
-
-<Good>
-```typescript
-async function retryOperation<T>(fn: () => Promise<T>): Promise<T> {
-  for (let i = 0; i < 3; i++) {
-    try {
-      return await fn();
-    } catch (e) {
-      if (i === 2) throw e;
-    }
-  }
-  throw new Error('unreachable');
-}
-```
-刚好够通过测试
-</Good>
-
-<Bad>
-```typescript
-async function retryOperation<T>(
-  fn: () => Promise<T>,
-  options?: {
-    maxRetries?: number;
-    backoff?: 'linear' | 'exponential';
-    onRetry?: (attempt: number) => void;
-  }
-): Promise<T> {
-  // YAGNI
-}
-```
-过度设计
-</Bad>
-
-不要添加功能、重构其他代码或做超出测试要求的"改进"。
-
-### 验证绿灯 - 看它通过
-
-**必须执行。**
-
-```bash
-npm test path/to/test.test.ts
-```
-
-确认：
-- 测试通过
-- 其他测试仍然通过
-- 输出干净（没有错误、警告）
-
-**测试失败了？** 修改代码，不是测试。
-
-**其他测试失败了？** 立即修复。
-
-### 重构 - 清理代码
-
-只有在绿灯之后才重构：
-- 消除重复
-- 改善命名
-- 提取辅助函数
-
-保持测试绿灯。不要添加行为。
-
-### 重复
-
-为下一个功能写下一个失败的测试。
-
-## 好的测试
-
-| 特质 | 好的 | 差的 |
-|------|------|------|
-| **最小化** | 只测一件事。名称中有"和"？拆分它。 | `test('validates email and domain and whitespace')` |
-| **清晰** | 名称描述行为 | `test('test1')` |
-| **展示意图** | 展示期望的 API | 掩盖了代码应该做什么 |
-
-## 为什么顺序很重要
-
-**"我先写完再补测试来验证"**
-
-后写的测试立即通过。立即通过什么也证明不了：
-- 可能测试了错误的东西
-- 可能测试的是实现而非行为
-- 可能遗漏了你忘掉的边界情况
-- 你从未看到它捕获 bug
-
-先写测试迫使你看到测试失败，证明它确实在测试某些东西。
-
-**"我已经手动测试了所有边界情况"**
-
-手动测试是临时的。你以为你测试了所有情况，但是：
-- 没有测试记录
-- 代码变更后无法重新运行
-- 在压力下容易遗忘
-- "我试过了能跑" 不等于 全面测试
-
-自动化测试是系统性的。它们每次以相同方式运行。
-
-**"删除 X 小时的工作太浪费了"**
-
-沉没成本谬误。时间已经花了。你现在的选择：
-- 删除并用 TDD 重写（再花 X 小时，高信心）
-- 保留并后补测试（30 分钟，低信心，可能有 bug）
-
-"浪费"的是保留你无法信任的代码。没有真正测试的可运行代码就是技术债。
-
-**"TDD 太教条了，务实意味着灵活变通"**
-
-TDD 就是务实的：
-- 在 commit 前发现 bug（比事后调试快）
-- 防止回归（测试立即发现破坏）
-- 记录行为（测试展示如何使用代码）
-- 支持重构（放心修改，测试捕获破坏）
-
-"务实的"捷径 = 在生产环境调试 = 更慢。
-
-**"后补测试也能达到相同目的——重要的是精神不是仪式"**
-
-不对。后补测试回答"这段代码做了什么？"先写测试回答"这段代码应该做什么？"
-
-后补测试受你实现的偏见影响。你测试的是你构建的东西，而非需求要求的。你验证的是你记得的边界情况，而非发现的。
-
-先写测试迫使你在实现前发现边界情况。后补测试验证的是你记住了所有情况（你没有）。
-
-30 分钟的后补测试 ≠ TDD。你得到了覆盖率，但失去了测试有效的证明。
-
-## 常见借口
-
-| 借口 | 现实 |
-|------|------|
-| "太简单了不用测" | 简单的代码也会出 bug。测试只需 30 秒。 |
-| "我之后补测试" | 立即通过的测试什么也证明不了。 |
-| "后补测试也能达到相同目的" | 后补测试 = "这做了什么？" 先写测试 = "这应该做什么？" |
-| "已经手动测试过了" | 临时测试 ≠ 系统测试。无记录，无法重现。 |
-| "删除 X 小时的工作太浪费" | 沉没成本谬误。保留未验证的代码就是技术债。 |
-| "留作参考，然后先写测试" | 你会去改编它。那就是后补测试。删除就是删除。 |
-| "需要先探索一下" | 可以。探索完了扔掉，从 TDD 开始。 |
-| "测试难写 = 设计不清楚" | 听测试的。难以测试 = 难以使用。 |
-| "TDD 会拖慢我" | TDD 比调试快。务实 = 先写测试。 |
-| "手动测试更快" | 手动测试无法证明边界情况。每次修改你都得重新测。 |
-| "现有代码没有测试" | 你在改进它。为现有代码补测试。 |
-
-## 危险信号 - 停下来，从头开始
-
-- 先写了代码再写测试
-- 实现完了才补测试
-- 测试立即通过
-- 无法解释测试为什么失败
-- "之后再补"测试
-- 说服自己"就这一次"
-- "我已经手动测试过了"
-- "后补测试也能达到相同目的"
-- "重要的是精神不是仪式"
-- "留作参考"或"改编现有代码"
-- "已经花了 X 小时了，删掉太浪费"
-- "TDD 太教条了，我是在务实"
-- "这次情况不同，因为……"
-
-**以上所有情况都意味着：删除代码。用 TDD 从头开始。**
-
-## 示例：Bug 修复
-
-**Bug：** 空邮箱被接受了
-
-**红灯**
-```typescript
-test('rejects empty email', async () => {
-  const result = await submitForm({ email: '' });
-  expect(result.error).toBe('Email required');
-});
-```
-
-**验证红灯**
-```bash
-$ npm test
-FAIL: expected 'Email required', got undefined
-```
-
-**绿灯**
-```typescript
-function submitForm(data: FormData) {
-  if (!data.email?.trim()) {
-    return { error: 'Email required' };
-  }
-  // ...
-}
-```
-
-**验证绿灯**
-```bash
-$ npm test
-PASS
-```
-
-**重构**
-如果需要，提取验证逻辑以支持多个字段。
-
-## 验证清单
-
-在标记工作完成之前：
-
-- [ ] 每个新函数/方法都有测试
-- [ ] 在实现之前看到每个测试失败
-- [ ] 每个测试因预期原因失败（功能缺失，不是拼写错误）
-- [ ] 为每个测试编写了最少代码使其通过
-- [ ] 所有测试通过
-- [ ] 输出干净（没有错误、警告）
-- [ ] 测试使用真实代码（只在不可避免时用 mock）
-- [ ] 覆盖了边界情况和错误场景
-
-不能全部勾选？你跳过了 TDD。从头开始。
-
-## 遇到困难时
-
-| 问题 | 解决方案 |
-|------|----------|
-| 不知道怎么测试 | 写出你期望的 API。先写断言。问你的人类伙伴。 |
-| 测试太复杂 | 设计太复杂。简化接口。 |
-| 必须 mock 所有东西 | 代码耦合太紧。使用依赖注入。 |
-| 测试 setup 太庞大 | 提取辅助函数。还是复杂？简化设计。 |
-
-## 调试集成
-
-发现 bug？写一个重现 bug 的失败测试。按 TDD 循环走。测试既证明了修复有效，又防止了回归。
-
-绝不在没有测试的情况下修复 bug。
-
-## 测试反模式
-
-添加 mock 或测试工具时，阅读 @testing-anti-patterns.md 以避免常见陷阱：
-- 测试 mock 行为而非真实行为
-- 在生产类中添加仅测试用的方法
-- 在不理解依赖的情况下使用 mock
-
-## 最终规则
-
-```
-生产代码 → 测试存在且先失败
-否则 → 不是 TDD
-```
-
-没有你的人类伙伴的许可，没有例外。

package/skills/test-driven-development/testing-anti-patterns.md

@@ -1,299 +0,0 @@
-# 测试反模式
-
-**在以下情况加载此参考：** 编写或修改测试、添加 mock、或想在生产代码中添加仅测试用方法时。
-
-## 概述
-
-测试必须验证真实行为，而非 mock 行为。Mock 是隔离的手段，不是被测试的对象。
-
-**核心原则：** 测试代码做了什么，而非 mock 做了什么。
-
-**严格遵循 TDD 可以防止这些反模式。**
-
-## 铁律
-
-```
-1. 绝不测试 mock 行为
-2. 绝不在生产类中添加仅测试用的方法
-3. 绝不在不理解依赖的情况下使用 mock
-```
-
-## 反模式 1：测试 Mock 行为
-
-**违规做法：**
-```typescript
-// ❌ 差：测试 mock 是否存在
-test('renders sidebar', () => {
-  render(<Page />);
-  expect(screen.getByTestId('sidebar-mock')).toBeInTheDocument();
-});
-```
-
-**为什么这是错误的：**
-- 你在验证 mock 能工作，而非组件能工作
-- mock 存在时测试通过，不存在时失败
-- 对真实行为一无所知
-
-**你的人类伙伴的纠正：** "我们是在测试 mock 的行为吗？"
-
-**正确做法：**
-```typescript
-// ✅ 好：测试真实组件或不要 mock 它
-test('renders sidebar', () => {
-  render(<Page />);  // 不要 mock sidebar
-  expect(screen.getByRole('navigation')).toBeInTheDocument();
-});
-
-// 或者如果必须 mock sidebar 来隔离：
-// 不要对 mock 做断言——测试 Page 在 sidebar 存在时的行为
-```
-
-### 门控函数
-
-```
-在对任何 mock 元素做断言之前：
-  问："我是在测试真实组件行为还是仅仅测试 mock 的存在？"
-
-  如果是测试 mock 的存在：
-    停下——删除断言或取消 mock
-
-  改为测试真实行为
-```
-
-## 反模式 2：在生产代码中添加仅测试用方法
-
-**违规做法：**
-```typescript
-// ❌ 差：destroy() 仅在测试中使用
-class Session {
-  async destroy() {  // 看起来像生产 API！
-    await this._workspaceManager?.destroyWorkspace(this.id);
-    // ... 清理
-  }
-}
-
-// 在测试中
-afterEach(() => session.destroy());
-```
-
-**为什么这是错误的：**
-- 生产类被仅测试用的代码污染
-- 如果在生产环境中意外调用会很危险
-- 违反 YAGNI 和关注点分离
-- 混淆了对象生命周期和实体生命周期
-
-**正确做法：**
-```typescript
-// ✅ 好：测试工具处理测试清理
-// Session 没有 destroy()——它在生产中是无状态的
-
-// 在 test-utils/ 中
-export async function cleanupSession(session: Session) {
-  const workspace = session.getWorkspaceInfo();
-  if (workspace) {
-    await workspaceManager.destroyWorkspace(workspace.id);
-  }
-}
-
-// 在测试中
-afterEach(() => cleanupSession(session));
-```
-
-### 门控函数
-
-```
-在向生产类添加任何方法之前：
-  问："这只被测试使用吗？"
-
-  如果是：
-    停下——不要添加
-    放到测试工具中
-
-  问："这个类是否拥有此资源的生命周期？"
-
-  如果否：
-    停下——这个方法不属于这个类
-```
-
-## 反模式 3：不理解依赖就使用 Mock
-
-**违规做法：**
-```typescript
-// ❌ 差：Mock 破坏了测试逻辑
-test('detects duplicate server', () => {
-  // Mock 阻止了测试依赖的配置写入！
-  vi.mock('ToolCatalog', () => ({
-    discoverAndCacheTools: vi.fn().mockResolvedValue(undefined)
-  }));
-
-  await addServer(config);
-  await addServer(config);  // 应该抛异常——但不会！
-});
-```
-
-**为什么这是错误的：**
-- 被 mock 的方法有测试依赖的副作用（写入配置）
-- "保险起见"过度 mock 破坏了实际行为
-- 测试因错误的原因通过或莫名其妙地失败
-
-**正确做法：**
-```typescript
-// ✅ 好：在正确的层级 mock
-test('detects duplicate server', () => {
-  // Mock 慢的部分，保留测试需要的行为
-  vi.mock('MCPServerManager'); // 只 mock 慢的服务器启动
-
-  await addServer(config);  // 配置被写入
-  await addServer(config);  // 检测到重复 ✓
-});
-```
-
-### 门控函数
-
-```
-在 mock 任何方法之前：
-  停下——先不要 mock
-
-  1. 问："真实方法有什么副作用？"
-  2. 问："这个测试是否依赖这些副作用？"
-  3. 问："我完全理解这个测试需要什么吗？"
-
-  如果依赖副作用：
-    在更底层 mock（实际的慢操作/外部操作）
-    或使用保留必要行为的测试替身
-    而非测试依赖的高层方法
-
-  如果不确定测试依赖什么：
-    先用真实实现运行测试
-    观察实际需要发生什么
-    然后在正确的层级添加最少的 mock
-
-  危险信号：
-    - "我 mock 一下保险"
-    - "这可能慢，还是 mock 掉吧"
-    - 不理解依赖链就 mock
-```
-
-## 反模式 4：不完整的 Mock
-
-**违规做法：**
-```typescript
-// ❌ 差：部分 mock——只包含你认为需要的字段
-const mockResponse = {
-  status: 'success',
-  data: { userId: '123', name: 'Alice' }
-  // 缺失：下游代码使用的 metadata
-};
-
-// 之后：代码访问 response.metadata.requestId 时崩溃
-```
-
-**为什么这是错误的：**
-- **部分 mock 隐藏了结构假设** — 你只 mock 了你知道的字段
-- **下游代码可能依赖你没包含的字段** — 静默失败
-- **测试通过但集成失败** — mock 不完整，真实 API 完整
-- **虚假的信心** — 测试对真实行为什么也没证明
-
-**铁律：** Mock 真实存在的完整数据结构，而非只包含你当前测试用到的字段。
-
-**正确做法：**
-```typescript
-// ✅ 好：镜像真实 API 的完整性
-const mockResponse = {
-  status: 'success',
-  data: { userId: '123', name: 'Alice' },
-  metadata: { requestId: 'req-789', timestamp: 1234567890 }
-  // 真实 API 返回的所有字段
-};
-```
-
-### 门控函数
-
-```
-在创建 mock 响应之前：
-  检查："真实 API 响应包含哪些字段？"
-
-  操作：
-    1. 从文档/示例中查看实际 API 响应
-    2. 包含系统下游可能消费的所有字段
-    3. 验证 mock 完全匹配真实响应的结构
-
-  关键：
-    如果你在创建 mock，你必须理解完整的结构
-    部分 mock 在代码依赖遗漏字段时会静默失败
-
-  不确定时：包含所有文档记录的字段
-```
-
-## 反模式 5：集成测试作为事后补充
-
-**违规做法：**
-```
-✅ 实现完成
-❌ 没写测试
-"准备好测试了"
-```
-
-**为什么这是错误的：**
-- 测试是实现的一部分，不是可选的后续
-- TDD 本可以防止这种情况
-- 没有测试就不能声称完成
-
-**正确做法：**
-```
-TDD 循环：
-1. 编写失败的测试
-2. 实现使其通过
-3. 重构
-4. 然后才声称完成
-```
-
-## 当 Mock 变得过于复杂时
-
-**警告信号：**
-- Mock 的 setup 比测试逻辑还长
-- 为了让测试通过而 mock 一切
-- Mock 缺少真实组件拥有的方法
-- Mock 变更时测试就坏了
-
-**你的人类伙伴的问题：** "我们这里真的需要用 mock 吗？"
-
-**考虑：** 使用真实组件的集成测试往往比复杂的 mock 更简单
-
-## TDD 如何防止这些反模式
-
-**TDD 有帮助的原因：**
-1. **先写测试** → 迫使你思考你到底在测什么
-2. **看它失败** → 确认测试测的是真实行为，不是 mock
-3. **最少实现** → 仅测试用方法不会混入
-4. **真实依赖** → 你在 mock 之前看到测试实际需要什么
-
-**如果你在测试 mock 行为，你违反了 TDD** — 你在没有先用真实代码让测试失败的情况下就加了 mock。
-
-## 快速参考
-
-| 反模式 | 修复方式 |
-|--------|----------|
-| 对 mock 元素做断言 | 测试真实组件或取消 mock |
-| 生产代码中的仅测试用方法 | 移到测试工具中 |
-| 不理解就 mock | 先理解依赖，最少 mock |
-| 不完整的 mock | 完整镜像真实 API |
-| 测试作为事后补充 | TDD——先写测试 |
-| 过于复杂的 mock | 考虑集成测试 |
-
-## 危险信号
-
-- 断言检查 `*-mock` test ID
-- 方法仅在测试文件中被调用
-- Mock setup 占测试的 >50%
-- 移除 mock 测试就失败
-- 无法解释为什么需要 mock
-- "保险起见" mock 掉
-
-## 底线
-
-**Mock 是隔离的工具，不是被测试的对象。**
-
-如果 TDD 揭示你在测试 mock 行为，你已经走偏了。
-
-修复方法：测试真实行为，或质疑为什么要 mock。