# Systematic Debugging

> 遇到任何 bug、测试失败或意外行为时，在提出修复方案之前使用

- Skill: `dawnmoon1542/systematic-debugging` (Agent Skill, multi-file: 11 files)
- Install (CLI): `npx skillmds@latest add dawnmoon1542/systematic-debugging`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dawnmoon1542/systematic-debugging/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: DawnMoon1542 (https://skillmd.com/u/dawnmoon1542)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/dawnmoon1542/systematic-debugging

---


# 系统化调试

## 概述

随机修复浪费时间并产生新 bug。快速补丁掩盖了底层问题。

**核心原则：** 在尝试修复之前，务必先找到根本原因。仅修复症状即为失败。

**违反此流程的文字精神，即是违反调试的灵魂。**

## 铁律

```
未完成根本原因调查之前，不得进行任何修复
```

如果你尚未完成阶段 1，就不能提出修复方案。

## 何时使用

适用于任何技术问题：
- 测试失败
- 生产环境 bug
- 意外行为
- 性能问题
- 构建失败
- 集成问题

**以下情况尤其需要使用：**
- 时间紧迫时（紧急情况下更容易想靠猜测）
- "快速修一下就行"看起来很明显时
- 已经尝试过多次修复时
- 之前的修复没有效果时
- 对问题不完全理解时

**以下情况不要跳过：**
- 问题看起来很简单（简单 bug 也有根本原因）
- 时间很赶（仓促行事必然导致返工）
- 主管要求立刻修好（系统化方法比反复折腾更快）

## 四个阶段

每个阶段完成之后才能进入下一阶段。

### 阶段 1：根本原因调查

**在尝试任何修复之前：**

1. **仔细阅读错误消息**
   - 不要跳过错误或警告
   - 它们通常包含确切的解决方案
   - 完整阅读堆栈跟踪
   - 注意行号、文件路径、错误码

2. **稳定复现**
   - 能否可靠触发？
   - 确切步骤是什么？
   - 每次都发生吗？
   - 如果无法复现 → 收集更多数据，不要猜测

3. **检查近期变更**
   - 哪些变动可能导致这个问题？
   - Git diff、最近的提交
   - 新的依赖、配置变更
   - 环境差异

4. **在多组件系统中收集证据**

   **当系统有多个组件时（CI → 构建 → 签名，API → 服务 → 数据库）：**

   **在提出修复方案之前，添加诊断工具：**
   ```
   对每个组件边界：
     - 记录进入组件的数据
     - 记录离开组件的数据
     - 验证环境/配置的传递
     - 检查每一层的状态

   运行一次以收集证据，显示问题发生在哪里
   然后分析证据以确定出错的组件
   然后深入调查该特定组件
   ```

   **示例（多层系统）：**
   ```bash
   # 第 1 层：工作流
   echo "=== 工作流中可用的密钥：==="
   echo "IDENTITY: ${IDENTITY:+已设置}${IDENTITY:-未设置}"

   # 第 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. **创建失败的测试用例**
   - 最简复现
   - 尽可能使用自动化测试
   - 如果没有测试框架则使用一次性测试脚本
   - 修复之前必须有测试
   - 使用 `test-driven-development` 技能编写合适的失败测试

2. **实施单一修复**
   - 解决已确定的根本原因
   - 一次只做一个变更
   - 不要"顺便"做其他改进
   - 不要捆绑重构

3. **验证修复**
   - 测试现在通过了吗？
   - 其他测试没有被破坏吗？
   - 问题确实解决了吗？

4. **如果修复不生效**
   - 停止
   - 计数：你已经尝试了多少次修复？
   - 如果 < 3：返回阶段 1，利用新信息重新分析
   - **如果 ≥ 3：停止并质疑架构（见下方第 5 步）**
   - 不要在未进行架构讨论的情况下尝试第 4 次修复

5. **如果 3 次以上修复失败：质疑架构**

   **表明存在架构问题的模式：**
   - 每次修复都会在其他地方暴露新的共享状态/耦合/问题
   - 修复需要"大规模重构"才能实施
   - 每次修复都会在其他地方产生新的症状

   **停止并质疑基础：**
   - 这个模式在根本上合理吗？
   - 我们是否"仅靠惯性在坚持它"？
   - 是否应该重构架构，而不是继续修复症状？

   **与用户讨论后再尝试更多修复**

   这不是假设失败——这是架构错误。

## 红旗信号——停止并按流程行事

如果你发现自己在想：
- "先快速修一下，后面再调查"
- "试试改 X 看看能不能行"
- "加多个改动，跑一下测试"
- "跳过测试，我手动验证"
- "大概是 X，我来修一下"
- "我不完全理解，但这可能管用"
- "模式说是 X，但我换个方式适配"
- "主要问题有：[未做调查就列出修复方案]"
- 在追踪数据流之前就提出解决方案
- **"再试一次修复"（已经尝试了 2 次以上）**
- **每次修复都在不同的地方暴露新问题**

**以上所有情况都意味着：停止。返回阶段 1。**

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

## 用户发出的你做法有误的信号

**注意以下纠正信号：**
- "那不是正在发生吗？"——你在没有验证的情况下做了假设
- "它能告诉我们……吗？"——你本应添加证据收集
- "不要再猜了"——你在不理解的情况下提出修复方案
- "深入思考这个问题"——质疑基础，而不仅仅是症状
- "我们卡住了吗？"（沮丧）——你的方法不起作用

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

## 常见的自我辩解

| 借口 | 现实 |
|--------|---------|
| "问题很简单，不需要流程" | 简单问题也有根本原因。流程对简单 bug 来说也很快。 |
| "紧急情况，没时间走流程" | 系统化调试比猜测-检查式的反复折腾更快。 |
| "先试试这个，然后再调查" | 第一次修复定下基调。从一开始就做对。 |
| "确认修复生效后再写测试" | 未经测试的修复不会稳固。先写测试来证明。 |
| "一次修多个省时间" | 无法隔离什么起了作用。还会产生新 bug。 |
| "参考太长了，我适配一下模式就行" | 部分理解必然导致 bug。完整阅读。 |
| "我看到问题了，我来修" | 看到症状不等于理解根本原因。 |
| "再试一次修复"（2 次以上失败后） | 3 次以上失败 = 架构问题。质疑模式，不要再修了。 |

## 快速参考

| 阶段 | 关键活动 | 成功标准 |
|-------|---------------|------------------|
| **1. 根本原因** | 阅读错误、复现、检查变更、收集证据 | 理解是什么和为什么 |
| **2. 模式** | 寻找正常工作的示例、对比 | 识别差异 |
| **3. 假设** | 形成理论、最小化测试 | 确认或形成新假设 |
| **4. 实施** | 创建测试、修复、验证 | bug 解决、测试通过 |

## 当流程揭示"没有根本原因"时

如果系统化调查显示问题确实是环境性的、时间相关的或外部性的：

1. 你已经完成了流程
2. 记录你调查了什么
3. 实施适当的处理（重试、超时、错误消息）
4. 添加监控/日志以便未来调查

**但是：** 95% 的"没有根本原因"案例都是不完整的调查。

## 辅助技术

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

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

## 实际影响

来自调试实践的数据：
- 系统化方法：15-30 分钟修复
- 随机修复方法：2-3 小时的反复折腾
- 首次修复成功率：95% vs 40%
- 引入新 bug：几乎为零 vs 常见