Systematic Debugging Zh

---
name: systematic-debugging-zh
description: 系统化调试、任何 Bug 或测试失败在提出修复方案之前必须先找到根因、症状式修复一律算失败、修了三次还没好就该质疑架构。当用户说「这个 bug 怎么修」「测试挂了」「线上报错」「构建失败」「行为跟预期不一样」「性能突然变差」「我已经试了好几种改法都不行」「先别猜，查清楚」时使用。四个阶段必须依次完成：根因调查（读全报错、稳定复现、查最近改动、在多组件系统的每个边界加探针取证、反向追溯数据流）→ 模式分析（找可用的同类代码、逐行读参考实现、列出全部差异、理清依赖）→ 假设与验证（一次只提一个假设、做最小改动验证、不通过就换新假设而不是叠加修复）→ 实施（先写复现用例、只改根因一处、验证、修够三次仍不好就停下来质疑架构）。附反向追溯、纵深防御校验、条件式等待三份参考。
author: Captain
version: 0.1.0
display_name: "系统化调试四阶段"
display_name_en: "Systematic Debugging (zh)"
description_zh: "任何 Bug 都先找根因再修：四阶段流程（根因调查→模式分析→假设验证→实施），含多组件取证、三次失败即质疑架构的熔断规则与借口反驳表。"
description_en: "Find the root cause before proposing any fix: a four-phase process with multi-component evidence gathering, a three-failed-fixes architecture circuit breaker, and a rationalization rebuttal table."
examples_zh:
  - "这个 bug 怎么修，先别猜，查清楚"
  - "测试挂了，行为跟预期不一样"
  - "我已经试了好几种改法都不行"
examples_en:
  - "This test keeps failing and I do not know why"
  - "Find the root cause before you suggest a fix"
  - "Three fixes in and it is still broken"
metadata:
  { "openclaw": { "requires": { "bins": [] }, "os": ["darwin", "linux", "windows"], "emoji": "🔬" } }
---

# 系统化调试四阶段

**核心原则：永远先找到根因，再动手修。症状式修复等于失败。**

违反这套流程的字面规定，就是违反调试的精神。

## 铁律

```
没做完根因调查，不许提修复方案
```

第 1 阶段没完成，你就没有资格提出任何修法。

## 何时用

任何技术问题都适用：测试失败、线上 Bug、行为异常、性能问题、构建失败、集成问题。

**尤其要用的时候：**

- 有时间压力（越紧急越想瞎猜）
- 「就改一行，一看就知道」的时候
- 你已经试过好几种修法
- 上一次修复没起作用
- 你对这个问题并没有完全搞懂

**不许跳过的借口：** 问题看起来很简单（简单 Bug 也有根因）；你很赶（赶只会返工）；有人催着现在就修好（系统化比乱试快）。

## 流程：四个阶段

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

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

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

1. **逐字读报错**——不要跳过错误和警告，它们经常直接写着答案；完整读堆栈；记下行号、文件路径、错误码。
2. **稳定复现**——能可靠触发吗？确切步骤是什么？每次都出现吗？复现不了就去收集更多数据，**不要猜**。
3. **查最近改动**——`git diff`、最近提交、新依赖、配置变更、环境差异。
4. **多组件系统要先取证**（CI → 构建 → 签名，接口 → 服务 → 数据库）：

   ```
   对每一个组件边界：
     - 记录进入该组件的数据
     - 记录离开该组件的数据
     - 验证环境变量/配置是否传递到位
     - 检查每一层的状态

   先跑一次，拿到「在哪一层断的」的证据
   再分析证据，锁定出问题的组件
   再去查那一个组件
   ```

   多层取证示例：

   ```bash
   # 第 1 层：流水线
   echo "=== 流水线里可见的密文变量 ==="
   echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"

   # 第 2 层：构建脚本
   echo "=== 构建脚本里的环境变量 ==="
   env | grep IDENTITY || echo "IDENTITY 不在环境里"

   # 第 3 层：真正执行的那一步
   echo "=== 执行前的状态 ==="
   ```

   **这样能看出：** 到底是哪一层断了（密文 → 流水线 ✓，流水线 → 构建 ✗）。

5. **反向追溯数据流**——报错出现在调用栈深处时，往回追到坏值的源头，在源头修，不在症状处修。完整手法见 `{baseDir}/references/root-cause-tracing.md`。

### 第 2 阶段：模式分析

1. **找可用的同类代码**——同一个代码库里有没有类似但正常工作的实现？
2. **对照参考实现**——要照搬某个模式就把参考实现**完整读完**，不要扫一眼；先完全理解再套用。
3. **列出全部差异**——正常的和坏的之间每一处不同都写下来，别想当然认为「这个肯定没影响」。
4. **理清依赖**——还需要哪些组件、哪些配置与环境、做了哪些前提假设。

### 第 3 阶段：假设与验证

1. **一次只提一个假设**——写清楚「我认为根因是 X，因为 Y」，要具体。
2. **最小化验证**——做**能验证这个假设的最小改动**，一次只动一个变量，不要同时修好几处。
3. **验证后再往下**——成立就进第 4 阶段；不成立就**换一个新假设**，不要在旧修复上继续叠加。
4. **不懂就说不懂**——说「我不明白 X」，不要装懂，去问、去查。

### 第 4 阶段：实施

1. **先写能复现的失败用例**——尽可能简化的复现；有框架就写自动化测试，没有就写一次性脚本；**修之前必须有**。写失败测试的方法可参考仓库里的测试驱动开发技能（如 `tdd-zh`）。
2. **只做一处修复**——针对已确认的根因；一次一个改动；不要「顺手」改进；不要捎带重构。
3. **验证修复**——测试现在过了吗？有没有弄坏别的测试？问题真的解决了吗？宣布完成前先走一遍「完成前验证门禁」技能（`verification-before-completion-zh`）。
4. **修复无效怎么办**——**停**。数一下你已经试了几次：少于 3 次就回第 1 阶段，带着新信息重新分析；**达到或超过 3 次就停下来质疑架构**。不要在没有架构讨论的情况下尝试第 4 次修复。
5. **三次以上失败＝质疑架构**——特征是：每次修复都在另一处暴露出新的共享状态/耦合；修复需要「大规模重构」才能落地；每个修复都在别处制造新症状。此时要停下来问根本问题：这个模式本身站得住吗？我们是不是纯靠惯性在硬扛？该重构架构还是继续修症状？**先和用户讨论，再谈下一次修复。** 这不是假设失败，这是架构错了。

## 输出契约

每个阶段结束时给出可核对的结论：

```
阶段 1 根因：<一句话> —— 证据：<报错原文 / 探针输出 / 提交号>
阶段 2 差异：<正常实现 vs 坏实现的差异清单>
阶段 3 假设：「我认为根因是 X，因为 Y」→ 最小验证：<命令> → 结果
阶段 4 修复：<文件:行>，复现用例：<路径>，验证：<命令> → <通过数>
```

## 红线——出现就停，回第 1 阶段

如果你发现自己在想：

- 「先快速修一下，回头再查」
- 「改改 X 试试看行不行」
- 「一起改几处，然后跑测试」
- 「跳过测试，我手动验一下」
- 「八成是 X，我改掉它」
- 「我没完全搞懂，但这样也许能行」
- 「参考实现说是 X，但我换个写法应该也行」
- 「主要问题有这些：」（还没调查就开始列修法）
- 还没追踪数据流就先提解决方案
- **「再试最后一次」（你已经试了 2 次以上）**
- **每次修复都在别处冒出新问题**

**以上全部意味着：停，回第 1 阶段。** 已经失败 3 次以上的，去质疑架构（第 4 阶段第 5 条）。

## 用户在暗示你做错了的信号

- 「不是应该发生 X 吗？」——你没验证就假设了
- 「这样能看出来吗？」——你本该先加取证
- 「别猜了」——你在没搞懂的情况下提修法
- 「再深想一下」——去质疑根本，而不是症状
- 「我们是不是卡住了？」（带情绪）——你的路子不对

**看到这些信号：停，回第 1 阶段。**

## 常见借口与反驳

| 借口 | 现实 |
|------|------|
| 「问题很简单，不用走流程」 | 简单问题也有根因，流程对简单 Bug 反而很快。 |
| 「紧急情况，没时间走流程」 | 系统化调试比反复瞎试更快。 |
| 「先试一下，回头再查」 | 第一次修复定了基调，一开始就做对。 |
| 「等确认修好了再补测试」 | 没测试的修复留不住，先写测试才证明得了。 |
| 「一次多修几处省时间」 | 分不清是哪个改动起的作用，还会引入新 Bug。 |
| 「参考实现太长，我照着改改」 | 一知半解必然出 Bug，完整读完。 |
| 「我看出问题在哪了，直接修」 | 看到症状 ≠ 理解根因。 |
| 「再试一次就好了」（已失败 2 次以上） | 失败 3 次以上是架构问题，别再修了，去质疑模式。 |

## 速查

| 阶段 | 关键动作 | 通过标准 |
|------|----------|----------|
| **1. 根因** | 读报错、复现、查改动、取证 | 搞清楚「是什么」和「为什么」 |
| **2. 模式** | 找可用样例、对照 | 列出差异 |
| **3. 假设** | 提出理论、最小验证 | 被确认或换新假设 |
| **4. 实施** | 写测试、修复、验证 | Bug 解决、测试通过 |

## 如果流程最终显示「没有根因」

若系统化调查确实表明问题属于环境、时序或外部因素：

1. 你已经走完了流程
2. 记录你调查过什么
3. 实现恰当的兜底（重试、超时、明确的错误信息）
4. 加上监控/日志，供将来排查

**但是：** 95% 的「找不到根因」其实是调查没做完。

## 配套手法

- **`{baseDir}/references/root-cause-tracing.md`** —— 沿调用链反向追溯，找到最初的触发点
- **`{baseDir}/references/defense-in-depth.md`** —— 找到根因后，在每一层加校验，让这个 Bug 结构上不可能再发生
- **`{baseDir}/references/condition-based-waiting.md`** —— 用条件轮询替换写死的超时，根治抖动测试

---
改编自 [obra/superpowers](https://github.com/obra/superpowers) 的 `systematic-debugging`（MIT）。改动见 ATTRIBUTION.md。