# Systematic Debugging

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

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

---


# 系统化调试

## 概述

随机修复会浪费时间并制造新的 bug。快速补丁会掩盖底层问题。

**核心原则：** 尝试修复之前，始终先找到根本原因。修症状就是失败。

**违反这个流程的字面要求，就是违反调试的精神。**

## 铁律

```
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
```

如果你还没有完成第 1 阶段，就不能提出修复方案。

## 何时使用

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

**尤其在以下情况使用：**
- 有时间压力（紧急情况会让猜测很诱人）
- “只做一个快速修复”看起来很明显
- 你已经尝试过多个修复
- 上一个修复没有奏效
- 你没有完全理解问题

**不要在以下情况跳过：**
- 问题看起来简单（简单 bug 也有根本原因）
- 你很赶时间（仓促必然导致返工）
- 经理要求现在就修好（系统化比乱试更快）

## 四个阶段

进入下一阶段前，你必须完成当前阶段。

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

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

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

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

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

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

   **当系统有多个组件时（CI → build → signing，API → service → database）：**

   **提出修复前，添加诊断插桩：**
   ```
   For EACH component boundary:
     - Log what data enters component
     - Log what data exits component
     - Verify environment/config propagation
     - Check state at each layer

   Run once to gather evidence showing WHERE it breaks
   THEN analyze evidence to identify failing component
   THEN investigate that specific component
   ```

   **示例（多层系统）：**
   ```bash
   # Layer 1: Workflow
   echo "=== Secrets available in workflow: ==="
   echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"

   # Layer 2: Build script
   echo "=== Env vars in build script: ==="
   env | grep IDENTITY || echo "IDENTITY not in environment"

   # Layer 3: Signing script
   echo "=== Keychain state: ==="
   security list-keychains
   security find-identity -v

   # Layer 4: Actual signing
   codesign --sign "$IDENTITY" --verbose=4 "$APP"
   ```

   **这会揭示：** 哪一层失败（secrets → workflow ✓，workflow → build ✗）

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 阶段。

## 常见合理化借口

| 借口 | 现实 |
|--------|---------|
| “问题很简单，不需要流程” | 简单问题也有根本原因。对简单 bug 来说，流程很快。 |
| “紧急情况，没时间走流程” | 系统化调试比猜测-检查式乱试更快。 |
| “先试这个，然后再调查” | 第一个修复会设定模式。从一开始就做对。 |
| “确认修复有效后我再写测试” | 未经测试的修复站不住。先写测试才能证明。 |
| “一次修复多个问题能省时间” | 无法隔离到底什么起作用。还会制造新 bug。 |
| “参考太长了，我会改编这个模式” | 理解不完整必然导致 bug。完整阅读。 |
| “我看出问题了，让我修” | 看见症状 ≠ 理解根本原因。 |
| “再尝试一个修复”（2 次以上失败后） | 3 次以上失败 = 架构问题。质疑模式，不要再修。 |

## 快速参考

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

## 当流程显示“没有根本原因”时

如果系统化调查显示问题确实是环境性、时序依赖或外部问题：

1. 你已经完成流程
2. 记录你调查过的内容
3. 实现适当处理（retry、timeout、error message）
4. 添加监控/日志，供未来调查使用

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

## 支撑技术

这些技术是 systematic debugging 的一部分，可在本目录中找到：

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

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

## 真实世界影响

来自调试会话：
- 系统化方法：15-30 分钟修复
- 随机修复方法：2-3 小时乱试
- 首次修复成功率：95% vs 40%
- 引入的新 bug：接近零 vs 常见