---
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，但我会用不同的方式调整它”
- “以下是主要问题：[lists fixes without investigation]”
- 在追踪数据流之前提出解决方案
- **“再尝试修一次”（已经尝试 2+ 次时）**
- **每次修复都会在不同位置暴露出新问题**

**所有这些都意味着：停止。回到阶段 1。**

**如果 3+ 次修复均告失败：**质疑架构（见阶段 4.5）

## 你的人类伙伴发出的、表明你做错了的信号

**留意这些纠偏信号：**
- “那不是正在发生吗？”——你未经验证就作出了假设
- “它会向我们显示……吗？”——你本应加入证据收集环节
- “别再猜了”——你在尚未理解问题时就提出修复方案
- “超深入地思考这个问题”——质疑根本前提，而不只是症状
- “我们卡住了吗？”（感到沮丧）——你的方法行不通

**看到这些信号时：**停止。回到阶段 1。

## 常见的自我合理化

| 借口 | 事实 |
|--------|---------|
| “问题很简单，不需要流程” | 简单问题也有根本原因。对于简单缺陷，这个流程也很快。 |
| “紧急情况，没时间走流程” | 系统化调试比猜测—检验式的反复折腾快得多。 |
| “先试一下这个，然后再调查” | 第一次修复会定下后续模式。从一开始就把它做对。 |
| “确认修复有效后，我再写测试” | 未经测试的修复无法持久。先写测试才能证明它。 |
| “同时进行多项修复能节省时间” | 无法确定究竟是哪项改动起了作用。还会引入新的缺陷。 |
| “参考资料太长了，我会调整这个模式” | 一知半解必然导致缺陷。完整阅读它。 |
| “我看到了问题，让我修复它” | 看到症状 ≠ 理解根本原因。 |
| “再尝试修一次”（在 2+ 次失败后） | 3+ 次失败 = 架构问题。质疑这个模式，不要再次尝试修复。 |

## 快速参考

| 阶段 | 关键活动 | 成功标准 |
|-------|---------------|------------------|
| **1. 根本原因** | 阅读错误信息、复现问题、检查变更、收集证据 | 理解发生了什么以及为什么会发生 |
| **2. 模式** | 找到可正常工作的示例、进行比较 | 识别差异 |
| **3. 假设** | 形成理论，以最小范围进行测试 | 假设得到确认，或形成新假设 |
| **4. 实施** | 创建测试、修复、验证 | 缺陷已解决，测试通过 |

## 当流程揭示“没有根本原因”时
如果系统化调查表明问题确实由环境因素、时序依赖或外部因素导致：

1. 你已经完成了该流程
2. 记录你调查过的内容
3. 实施适当的处理措施（重试、超时、错误消息）
4. 添加监控/日志记录，以供将来调查

**但是：** 95% 的“没有根本原因”案例其实是调查不完整。

## 辅助技术

这些技术是系统化调试的一部分，可在此目录中找到：

- **`root-cause-tracing.md`** - 沿调用栈反向追踪 bug，以找到最初的触发因素
- **`defense-in-depth.md`** - 找到根本原因后，在多个层级添加验证
- **`condition-based-waiting.md`** - 使用条件轮询替代任意超时

**相关技能：**
- **superpowers:test-driven-development** - 用于创建失败的测试用例（第 4 阶段，第 1 步）
- **superpowers:verification-before-completion** - 在宣称成功之前验证修复确实有效

## 实际影响

根据调试会话：
- 系统化方法：15-30 分钟修复
- 随机修复方法：反复折腾 2-3 小时
- 首次修复成功率：95% 对比 40%
- 引入的新 bug：几乎为零 对比 很常见
