sdd-full 4.2.0 → 4.3.0

package/skills/development-execution/systematic-debugging/SKILL.md

@@ -0,0 +1,298 @@
+【claude code调用标识：systematic-debugging】【trae调用标识：systematic-debugging+系统性调试】【流程场景：4.Bug处理】
+
+---
+name: systematic-debugging
+description: 在遇到任何错误、测试失败或意外行为时使用，在提出修复方案之前
+---
+
+# 系统性调试
+
+## 概述
+
+随机修复浪费时间并创建新错误。快速补丁掩盖潜在问题。
+
+**核心原则：** 在尝试修复之前始终找到根本原因。症状修复是失败。
+
+**违反此流程的字面意思就是违反调试的精神。**
+
+## 铁律
+
+```
+没有根本原因调查，就没有修复
+```
+
+如果你还没有完成第 1 阶段，你不能提出修复方案。
+
+## 何时使用
+
+用于任何技术问题：
+- 测试失败
+- 生产中的错误
+- 意外行为
+- 性能问题
+- 构建失败
+- 集成问题
+
+**特别使用当：**
+- 在时间压力下（紧急情况使猜测变得诱人）
+- "只需一个快速修复"看起来很明显
+- 你已经尝试了多个修复
+- 之前的修复不起作用
+- 你不完全理解问题
+
+**不要跳过当：**
+- 问题看起来简单（简单错误也有根本原因）
+- 你很匆忙（匆忙保证返工）
+- 经理希望立即修复（系统性比混乱更快）
+
+## 四个阶段
+
+你必须完成每个阶段才能进入下一个阶段。
+
+### 阶段 1：根本原因调查
+
+**在尝试任何修复之前：**
+
+1. **仔细阅读错误消息**
+   - 不要跳过错误或警告
+   - 它们通常包含确切的解决方案
+   - 完全阅读堆栈跟踪
+   - 注意行号、文件路径、错误代码
+
+2. **一致地重现**
+   - 你能可靠地触发它吗？
+   - 确切的步骤是什么？
+   - 它每次都会发生吗？
+   - 如果不可重现 → 收集更多数据，不要猜测
+
+3. **检查最近的更改**
+   - 什么更改可能导致此问题？
+   - Git diff，最近的提交
+   - 新依赖项，配置更改
+   - 环境差异
+
+4. **在多组件系统中收集证据**
+
+   **当系统有多个组件时（CI → 构建 → 签名，API → 服务 → 数据库）：**
+
+   **在提出修复之前，添加诊断工具：**
+   ```
+   对于每个组件边界：
+     - 记录什么数据进入组件
+     - 记录什么数据离开组件
+     - 验证环境/配置传播
+     - 检查每层的状态
+
+   运行一次以收集显示它在哪里中断的证据
+   然后分析证据以识别失败的组件
+   然后调查该特定组件
+   ```
+
+   **示例（多层系统）：**
+   ```bash
+   # 第 1 层：工作流
+   echo "=== 工作流中可用的密钥：==="
+   echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
+
+   # 第 2 层：构建脚本
+   echo "=== 构建脚本中的环境变量：==="
+   env | grep IDENTITY || echo "IDENTITY 不在环境中"
+
+   # 第 3 层：签名脚本
+   echo "=== 钥匙串状态：==="
+   security list-keychains
+   security find-identity -v
+
+   # 第 4 层：实际签名
+   codesign --sign "$IDENTITY" --verbose=4 "$APP"
+   ```
+
+   **这揭示：** 哪一层失败（密钥 → 工作流 ✓，工作流 → 构建 ✗）
+
+5. **跟踪数据流**
+
+   **当错误在调用堆栈深处时：**
+
+   请参阅此目录中的 `root-cause-tracing.md` 了解完整的向后跟踪技术。
+
+   **快速版本：**
+   - 坏值源自哪里？
+   - 什么用坏值调用了这个？
+   - 继续向上跟踪直到找到源
+   - 在源处修复，而不是在症状处
+
+### 阶段 2：模式分析
+
+**在修复前找到模式：**
+
+1. **找到工作示例**
+   - 在同一代码库中定位类似的工作代码
+   - 什么与损坏的代码类似但能工作？
+
+2. **与参考进行比较**
+   - 如果实现模式，完全阅读参考实现
+   - 不要浏览 - 阅读每一行
+   - 在应用前完全理解模式
+
+3. **识别差异**
+   - 工作的和损坏的之间有什么不同？
+   - 列出每个差异，无论多小
+   - 不要假设"那不重要"
+
+4. **理解依赖关系**
+   - 这需要其他哪些组件？
+   - 需要什么设置、配置、环境？
+   - 它做了什么假设？
+
+### 阶段 3：假设和测试
+
+**科学方法：**
+
+1. **形成单一假设**
+   - 明确说明："我认为 X 是根本原因，因为 Y"
+   - 写下来
+   - 具体，不要模糊
+
+2. **最小测试**
+   - 做最小可能的更改来测试假设
+   - 一次一个变量
+   - 不要一次修复多个问题
+
+3. **继续前验证**
+   - 它工作了吗？是 → 阶段 4
+   - 没工作？形成新假设
+   - 不要在上面添加更多修复
+
+4. **当你不知道时**
+   - 说"我不理解 X"
+   - 不要假装知道
+   - 寻求帮助
+   - 研究更多
+
+### 阶段 4：实施
+
+**修复根本原因，不是症状：**
+
+1. **创建失败测试用例**
+   - 最简单的可能复现
+   - 尽可能自动测试
+   - 如果没有框架，使用一次性测试脚本
+   - 修复前必须有
+   - 使用 `superpowers:test-driven-development` 技能编写适当的失败测试
+
+2. **实施单一修复**
+   - 解决已识别的根本原因
+   - 一次一个更改
+   - 没有"顺便"改进
+   - 没有捆绑重构
+
+3. **验证修复**
+   - 测试现在通过了吗？
+   - 没有其他测试损坏？
+   - 问题实际解决了？
+
+4. **如果修复不起作用**
+   - 停止
+   - 计数：你尝试了多少个修复？
+   - 如果 < 3：返回阶段 1，用新信息重新分析
+   - **如果 ≥ 3：停止并质疑架构（见下面的步骤 5）**
+   - 不要在没有架构讨论的情况下尝试修复 #4
+
+5. **如果 3+ 修复失败：质疑架构**
+
+   **表明架构问题的模式：**
+   - 每个修复都揭示不同地方的新共享状态/耦合/问题
+   - 修复需要"大规模重构"来实现
+   - 每个修复都在其他地方创建新症状
+
+   **停止并质疑基础：**
+   - 这个模式从根本上是否健全？
+   - 我们是否"仅仅因为惯性而坚持它"？
+   - 我们应该重构架构还是继续修复症状？
+
+   **在尝试更多修复之前与你的人类伙伴讨论**
+
+   这不是失败的假设 - 这是错误的架构。
+
+## 红旗 - 停止并遵循流程
+
+如果你发现自己在想：
+- "现在快速修复，以后调查"
+- "只需尝试更改 X 看看是否有效"
+- "添加多个更改，运行测试"
+- "跳过测试，我会手动验证"
+- "可能是 X，让我修复它"
+- "我不完全理解，但这可能有效"
+- "模式说 X 但我会以不同方式适应它"
+- "这里是主要问题：[列出没有调查的修复]"
+- 在跟踪数据流之前提出解决方案
+- **"再尝试一次修复"（已经尝试了 2+）**
+- **每个修复都揭示不同地方的新问题**
+
+**所有这些都意味着：停止。返回阶段 1。**
+
+**如果 3+ 修复失败：** 质疑架构（见阶段 4.5）
+
+## 你的人类伙伴的信号你做错了
+
+**注意这些重定向：**
+- "那不是发生了吗？" - 你未经验证就假设
+- "它会告诉我们...？" - 你应该添加证据收集
+- "停止猜测" - 你在不理解的情况下提出修复
+- "超级思考这个" - 质疑基础，而不仅仅是症状
+- "我们卡住了？"（沮丧）- 你的方法不起作用
+
+**当你看到这些：** 停止。返回阶段 1。
+
+## 常见的合理化
+
+| 借口 | 现实 |
+|------|------|
+| "问题简单，不需要流程" | 简单问题也有根本原因。流程对简单错误很快。 |
+| "紧急情况，没时间流程" | 系统性调试比猜测和检查的混乱更快。 |
+| "先试试这个，然后调查" | 第一个修复设定模式。从一开始就做对。 |
+| "我会在确认修复有效后写测试" | 未经测试的修复不会持久。先测试证明它。 |
+| "一次多个修复节省时间" | 无法隔离什么有效。导致新错误。 |
+| "参考太长，我会适应模式" | 部分理解保证错误。完全阅读它。 |
+| "我看到问题了，让我修复它" | 看到症状 ≠ 理解根本原因。 |
+| "再尝试一次修复"（2+ 失败后） | 3+ 失败 = 架构问题。质疑模式，不要再修复。 |
+
+## 快速参考
+
+| 阶段 | 关键活动 | 成功标准 |
+|------|----------|----------|
+| **1. 根本原因** | 阅读错误，重现，检查更改，收集证据 | 理解 WHAT 和 WHY |
+| **2. 模式** | 找到工作示例，比较 | 识别差异 |
+| **3. 假设** | 形成理论，最小测试 | 确认或新假设 |
+| **4. 实施** | 创建测试，修复，验证 | 错误解决，测试通过 |
+
+## 当流程揭示"无根本原因"时
+
+如果系统性调查揭示问题确实是环境性、时间依赖性或外部的：
+
+1. 你已经完成了流程
+2. 记录你调查了什么
+3. 实施适当的处理（重试，超时，错误消息）
+4. 添加监控/日志以便将来调查
+
+**但：** 95% 的"无根本原因"案例是调查不完整。
+
+## 支持技术
+
+这些技术是系统性调试的一部分，在此目录中可用：
+
+- **`root-cause-tracing.md`** - 通过调用堆栈向后跟踪错误以找到原始触发器
+- **`defense-in-depth.md`** - 在找到根本原因后在多个层添加验证
+- **`condition-based-waiting.md`** - 用条件轮询替换任意超时
+
+**相关技能：**
+- **superpowers:test-driven-development** - 用于创建失败测试用例（阶段 4，步骤 1）
+- **superpowers:verification-before-completion** - 在声称成功之前验证修复有效
+
+## 现实影响
+
+来自调试会话：
+- 系统方法：15-30 分钟修复
+- 随机修复方法：2-3 小时混乱
+- 首次修复率：95% 对 40%
+- 引入的新错误：几乎为零对常见

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

@@ -0,0 +1,373 @@
+【claude code调用标识：test-driven-development】【trae调用标识：test-driven-development+测试驱动开发】【流程场景：1.完整3阶段SDD流程、3.小型功能迭代、4.Bug处理】
+
+---
+name: test-driven-development
+description: 在编写实现代码之前，实现任何功能或错误修复时使用
+---
+
+# 测试驱动开发 (TDD)
+
+## 概述
+
+先写测试。看着它失败。编写最小代码使其通过。
+
+**核心原则：** 如果你没有看到测试失败，你就不知道它是否测试了正确的东西。
+
+**违反规则的字面意思就是违反规则的精神。**
+
+## 何时使用
+
+**始终：**
+- 新功能
+- 错误修复
+- 重构
+- 行为变更
+
+**例外（询问你的人类伙伴）：**
+- 一次性原型
+- 生成的代码
+- 配置文件
+
+想“就这一次跳过 TDD”？停止。那是合理化。
+
+## 铁律
+
+```
+没有先失败的测试，就没有生产代码
+```
+
+在测试之前写代码？删除它。重新开始。
+
+**没有例外：**
+- 不要将其作为“参考”保留
+- 不要在编写测试时“适应”它
+- 不要看它
+- 删除意味着删除
+
+从测试中重新实现。就这样。
+
+## 红-绿-重构
+
+```dot
+digraph tdd_cycle {
+    rankdir=LR;
+    red [label="RED\n编写失败的测试", shape=box, style=filled, fillcolor="#ffcccc"];
+    verify_red [label="验证失败\n正确", shape=diamond];
+    green [label="GREEN\n最小代码", shape=box, style=filled, fillcolor="#ccffcc"];
+    verify_green [label="验证通过\n全部绿色", shape=diamond];
+    refactor [label="REFACTOR\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('重试失败操作 3 次', 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('重试有效', async () => {
+  const mock = jest.fn()
+    .mockRejectedValueOnce(new Error())
+    .mockRejectedValueOnce(new Error())
+    .mockResolvedValueOnce('success');
+  await retryOperation(mock);
+  expect(mock).toHaveBeenCalledTimes(3);
+});
+```
+名称模糊，测试模拟而非代码
+</Bad>
+
+**要求：**
+- 一个行为
+- 清晰的名称
+- 真实代码（除非不可避免，否则不要使用模拟）
+
+### 验证红 - 看着它失败
+
+**必须执行。永远不要跳过。**
+
+```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
+```
+
+确认：
+- 测试通过
+- 其他测试仍然通过
+- 输出纯净（无错误、警告）
+
+**测试失败？** 修复代码，不是测试。
+
+**其他测试失败？** 立即修复。
+
+### 重构 - 清理
+
+仅在绿色之后：
+- 移除重复
+- 改进名称
+- 提取辅助函数
+
+保持测试绿色。不要添加行为。
+
+### 重复
+
+下一个失败的测试用于下一个功能。
+
+## 好的测试
+
+| 质量 | 好 | 坏 |
+|------|----|----|
+| **最小** | 一个行为。名称中有 "and"？拆分它。 | `test('validates email and domain and whitespace')` |
+| **清晰** | 名称描述行为 | `test('test1')` |
+| **展示意图** | 演示期望的 API | 掩盖代码应该做什么 |
+
+## 为什么顺序很重要
+
+**"我会在之后写测试来验证它有效"**
+
+在代码之后写的测试立即通过。立即通过证明不了什么：
+- 可能测试错误的东西
+- 可能测试实现，而不是行为
+- 可能遗漏你忘记的边缘情况
+- 你从未看到它捕获错误
+
+测试优先迫使你看到测试失败，证明它实际上测试了某些东西。
+
+**"我已经手动测试了所有边缘情况"**
+
+手动测试是临时的。你认为你测试了一切，但：
+- 没有记录你测试了什么
+- 代码更改时无法重新运行
+- 在压力下容易忘记情况
+- "我尝试时它有效" ≠ 全面
+
+自动化测试是系统的。它们每次都以相同的方式运行。
+
+**"删除 X 小时的工作是浪费的"**
+
+沉没成本谬误。时间已经过去了。你现在的选择：
+- 删除并重写 TDD（再 X 小时，高信心）
+- 保留它并在之后添加测试（30 分钟，低信心，可能有错误）
+
+"浪费"是保留你不能信任的代码。没有真实测试的工作代码是技术债务。
+
+**"TDD 是教条的，务实意味着适应"**
+
+TDD 就是务实：
+- 在提交前发现错误（比之后调试更快）
+- 防止回归（测试立即捕获中断）
+- 记录行为（测试展示如何使用代码）
+- 启用重构（自由更改，测试捕获中断）
+
+"务实"的捷径 = 在生产中调试 = 更慢。
+
+**"测试之后达到相同的目标 - 这是精神不是仪式"**
+
+不。测试之后回答"这做什么？"。测试之前回答"这应该做什么？"。
+
+测试之后被你的实现所偏见。你测试你构建的东西，而不是需要的东西。你验证记住的边缘情况，而不是发现的边缘情况。
+
+测试之前迫使在实现之前发现边缘情况。测试之后验证你记住了一切（你没有）。
+
+30 分钟的测试之后 ≠ TDD。你获得覆盖率，失去测试工作的证明。
+
+## 常见的合理化
+
+| 借口 | 现实 |
+|------|------|
+| "太简单了，不需要测试" | 简单代码会中断。测试需要 30 秒。 |
+| "我会之后测试" | 立即通过的测试证明不了什么。 |
+| "测试之后达到相同的目标" | 测试之后 = "这做什么？" 测试之前 = "这应该做什么？" |
+| "已经手动测试过了" | 临时 ≠ 系统。无记录，无法重新运行。 |
+| "删除 X 小时是浪费的" | 沉没成本谬误。保留未验证的代码是技术债务。 |
+| "保留作为参考，先写测试" | 你会适应它。那是测试之后。删除意味着删除。 |
+| "需要先探索" | 很好。扔掉探索，从 TDD 开始。 |
+| "测试难 = 设计不清" | 听测试的。难测试 = 难使用。 |
+| "TDD 会减慢我" | TDD 比调试快。务实 = 测试优先。 |
+| "手动测试更快" | 手动不能证明边缘情况。你会重新测试每个更改。 |
+| "现有代码没有测试" | 你正在改进它。为现有代码添加测试。 |
+
+## 红旗 - 停止并重新开始
+
+- 测试之前的代码
+- 实现之后的测试
+- 测试立即通过
+- 无法解释测试为什么失败
+- "稍后"添加的测试
+- 合理化"就这一次"
+- "我已经手动测试过了"
+- "测试之后达到相同的目的"
+- "这是精神不是仪式"
+- "保留作为参考"或"适应现有代码"
+- "已经花了 X 小时，删除是浪费的"
+- "TDD 是教条的，我在务实"
+- "这不同因为..."
+
+**所有这些都意味着：删除代码。用 TDD 重新开始。**
+
+## 示例：错误修复
+
+**错误：** 接受空电子邮件
+
+**红**
+```typescript
+test('拒绝空电子邮件', async () => {
+  const result = await submitForm({ email: '' });
+  expect(result.error).toBe('Email required');
+});
+```
+
+**验证红**
+```bash
+$ npm test
+失败：期望 'Email required'，得到 undefined
+```
+
+**绿**
+```typescript
+function submitForm(data: FormData) {
+  if (!data.email?.trim()) {
+    return { error: 'Email required' };
+  }
+  // ...
+}
+```
+
+**验证绿**
+```bash
+$ npm test
+通过
+```
+
+**重构**
+如果需要，提取多个字段的验证。
+
+## 验证清单
+
+在标记工作完成之前：
+
+- [ ] 每个新函数/方法都有测试
+- [ ] 每个测试在实现前都看到失败
+- [ ] 每个测试因预期原因失败（功能缺失，不是拼写错误）
+- [ ] 为每个测试编写最小代码以通过
+- [ ] 所有测试通过
+- [ ] 输出纯净（无错误、警告）
+- [ ] 测试使用真实代码（仅在不可避免时使用模拟）
+- [ ] 覆盖边缘情况和错误
+
+无法检查所有框？你跳过了 TDD。重新开始。
+
+## 卡住时
+
+| 问题 | 解决方案 |
+|------|----------|
+| 不知道如何测试 | 编写期望的 API。先编写断言。询问你的人类伙伴。 |
+| 测试太复杂 | 设计太复杂。简化接口。 |
+| 必须模拟一切 | 代码耦合度太高。使用依赖注入。 |
+| 测试设置庞大 | 提取辅助函数。仍然复杂？简化设计。 |
+
+## 调试集成
+
+发现错误？编写重现错误的失败测试。遵循 TDD 循环。测试证明修复并防止回归。
+
+永远不要没有测试就修复错误。
+
+## 测试反模式
+
+添加模拟或测试实用程序时，阅读 @testing-anti-patterns.md 以避免常见陷阱：
+- 测试模拟行为而不是真实行为
+- 向生产类添加仅测试方法
+- 在不理解依赖关系的情况下模拟
+
+## 最终规则
+
+```
+生产代码 → 测试存在且首先失败
+否则 → 不是 TDD
+```
+
+未经你的人类伙伴许可，无例外。