# systematic-debugging

> 四阶段调试法与根因分析；在调查缺陷、修复测试失败或排查异常行为时使用。强调“未找到根因前不得修复”。

- Author: ZoneCNH
- Repository: OpsFlux/claude-code-showcase
- Version: 20260108185000
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-07
- Source: https://github.com/OpsFlux/claude-code-showcase
- Web: https://mule.run/skillshub/@@OpsFlux/claude-code-showcase~systematic-debugging:20260108185000

---

---
name: systematic-debugging
description: 四阶段调试法与根因分析；在调查缺陷、修复测试失败或排查异常行为时使用。强调“未找到根因前不得修复”。
---

# Systematic Debugging

## 核心原则

**在查明根因之前不允许修复。**

不要用治标不治本的补丁掩盖问题。必须先弄清楚为什么失败，再动手修复。

## 四阶段框架

### 阶段 1：根因调查

动代码之前：

1. **仔细阅读错误信息**——每个词都重要
2. **稳定复现问题**——无法复现就无法验证修复
3. **检查最近改动**——失败前有什么变化？
4. **收集证据**——日志、堆栈、状态导出
5. **追踪数据流**——沿调用链找到异常值来源

**根因追踪技巧：**
```
1. 观察症状——错误出现在哪里？
2. 找直接原因——是哪段代码抛了错误？
3. 问“是谁调用它？”——沿调用链向上
4. 持续回溯——逆向追踪异常数据
5. 找到最初触发点——问题真正开始的位置
```

**要点**：不要只在错误表面修复，必须追溯到源头。

### 阶段 2：模式分析

1. **寻找正常工作的示例**
2. **完整对比实现**——不能走马观花
3. **识别差异**——正常与异常的差别是什么
4. **理解依赖**——此处依赖谁？

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

套用科学方法：

1. **提出单一假设**——“因为 X 所以报错”
2. **设计最小测试**——一次只改一个变量
3. **预期结果**——假设成立时应该怎样
4. **执行实验**——观察真实表现
5. **验证结果**——是否符合预期
6. **继续或迭代**——错误则修正假设，正确则实施

### 阶段 4：实施

1. **先写失败的测试**——捕捉缺陷行为
2. **实施单一修复**——直击根因
3. **确认测试通过**——验证修复
4. **跑全量测试**——确保无回归
5. **若修复失败，立即停下**——重新评估假设

**关键规则**：若连续三次修复失败，必须 STOP。这通常意味着架构性问题，需要讨论，而不是继续打补丁。

## 红线：流程违规

出现以下念头要立刻停下：

- “先快速修一下，之后再查”
- “再试最后一次修复”
- “理论上应该可行”却说不清为什么
- “先试试看”但没有任何假设
- “我这里没问题”却不调查差异

## 更深层问题的信号

如果“每修一个地方，另一个地方又出问题”，往往说明架构层面有缺陷：

- 停止继续补丁
- 记录目前发现
- 与团队讨论
- 评估是否需要重新设计

## 常见调试场景

### 测试失败
```
1. 阅读完整错误和堆栈
2. 确认哪个断言失败以及原因
3. 检查测试环境配置
4. 检查测试数据/Mock 是否正确
5. 追踪异常值的来源
```

### 运行时错误
```
1. 捕获完整堆栈
2. 找到抛错的行
3. 看哪些值 undefined/null
4. 反向追踪坏值来源
5. 在源头添加校验
```

### “之前好好的”
```
1. 用 git bisect 找出破坏性的提交
2. 对比与上一版的差异
3. 确认哪条假设被改变
4. 在假设被破坏的地方修复
```

### 间歇性失败
```
1. 排查竞争条件
2. 检查共享可变状态
3. 查看异步顺序
4. 注意时间依赖
5. 添加确定性的等待或同步机制
```

## 调试检查清单

在宣称 bug 已修复之前：

- [ ] 已找到并记录根因
- [ ] 提出了假设并完成测试
- [ ] 修复直指根因而非症状
- [ ] 已有失败测试反映该 bug
- [ ] 修复后测试通过
- [ ] 全量测试通过
- [ ] 没有使用“权宜之计”的借口
- [ ] 修改范围最小且聚焦

## 成功指标

系统化调试首修成功率约 95%，而临场修复只有 ~40%。

做到位的信号：
- 修复不会引入新缺陷
- 能清晰解释 bug 产生原因
- 相似问题不会复发
- 修复后代码质量更高

## 与其他技能协作

- **testing-patterns**：先写能复现 bug 的测试，再开始修复