systematic-debugging

name	systematic-debugging
description	系统化调试方法论，采用4阶段根本原因分析流程处理复杂Bug和间歇性故障。当用户报告代码bug、程序报错、问题排查、系统异常等情况时使用。

Systematic Debugging - 系统化调试方法论

来源: obra/superpowers (142K⭐) - AI辅助开发方法论框架

参考: TDD + YAGNI + DRY 方法论，systematic-debugging 4阶段流程

核心价值

"复杂性降低是主要目标" —— 大多数Bug源于复杂的解决方案，而非简单的错误。系统化调试帮助我们先理解问题，再修复问题，避免治标不治本。

调试四阶段流程

阶段1️⃣：假设形成 (Form Hypothesis)

目标：理解问题，提出可能的根本原因假设

操作：

1. 收集所有相关错误信息

   • 错误消息/堆栈跟踪
   • 发生的频率（首次/间歇性/持续）
   • 复现步骤
   • 环境信息（系统、版本、配置）

2. 回答关键问题：

   • "这个问题之前发生过吗？"
   • "最近有什么变化？（代码、配置、环境）"
   • "同样的输入总是产生同样的错误吗？"

3. 列出可能的假设（至少3个）

   假设A: [具体原因] - 支持证据：[X] 不支持证据：[Y]
   假设B: [具体原因] - 支持证据：[X] 不支持证据：[Y]
   假设C: [具体原因] - 支持证据：[X] 不支持证据：[Y]
   

原则：假设要具体，"可能是网络问题"不是假设，"API超时因为缺少重试机制"是假设

阶段2️⃣：证据收集 (Gather Evidence)

目标：验证或推翻假设，找到确凿证据

操作：

1. 隔离测试：最小化复现场景

   # 创建一个最小测试用例
   - 移除不相关代码
   - 固定输入值
   - 单一变量原则
   

2. 添加日志：在关键点输出状态

   # 示例：添加诊断日志
   print(f"[DEBUG] Step {step}: input={x}, state={state}")
   

3. 二分查找：快速定位问题区域

   • 注释掉一半代码，检查是否还出错
   • 逐步缩小范围

4. 对比实验：改变单一变量

   • 回滚最近更改
   • 尝试在不同环境运行
   • 使用已知正确的版本对比

输出：

证据分析：
✅ 假设A：被[证据]证实
❌ 假设B：被[证据]推翻
⏳ 假设C：需要[进一步测试]

阶段3️⃣：根本原因分析 (Root Cause Analysis)

目标：找到真正的根本原因

方法：

1. 5个为什么：连续追问"为什么"直到本质

   问题：接口返回500错误
   为什么？-> 数据库连接失败
   为什么？-> 连接池耗尽
   为什么？-> 慢查询占用连接
   为什么？-> 缺少索引
   为什么？-> 上线前未做性能测试
   根本原因：缺少性能测试流程
   

2. 鱼骨图分析：

   问题
   ├── 人
   │   ├── 培训不足？
   │   └── 操作失误？
   ├── 机器
   │   ├── 硬件故障？
   │   └── 配置错误？
   ├── 方法
   │   ├── 逻辑错误？
   │   └── 边界条件？
   └── ...
   

3. 检查常见陷阱：

   • 空指针/未初始化
   • 并发竞态条件
   • 资源泄漏（内存、连接）
   • 时区/编码问题
   • 缓存一致性问题
   • 边界条件（0、null、空字符串）

阶段4️⃣：修复验证 (Verify Fix)

目标：确保修复有效且不引入新问题

操作：

1. 修复后立即测试

   # 运行相关测试
   npm test -- --grep "相关测试名称"
   
   # 手动复现测试
   [复现步骤]
   

2. 回归测试

   测试范围：
   - [ ] 直接相关的功能
   - [ ] 同一模块的其他功能
   - [ ] 上下游依赖的功能
   

3. 边界条件测试

   - [ ] 正常值
   - [ ] 边界值（0、最大值、空）
   - [ ] 异常值（负数、超长字符串）
   

4. 添加监控/测试

   # 添加单元测试防止回归
   def test_edge_case():
       assert fix_function(0) == expected
       assert fix_function(null) == expected
   

输出模板

调试完成后，提供结构化报告：

## 调试报告

### 问题描述
[简洁描述]

### 根本原因
[5个为什么分析结果]

### 修复方案

[具体代码改动]

### 验证结果
| 测试项 | 结果 |
|-------|------|
| 复现测试 | ✅ 通过 |
| 单元测试 | ✅ 通过 |
| 回归测试 | ✅ 通过 |

### 预防措施
- [ ] 添加了单元测试
- [ ] 添加了集成测试
- [ ] 更新了文档
- [ ] 记录了checklist

核心原则

原则	说明
证据优先于声明	"我认为是..."不是证据，测试结果才是
先理解后修复	花时间理解问题，避免盲目试错
最小化改动	只改必要的部分
测试即文档	测试用例说明了期望行为
记录即学习	记录调试过程，下次更快解决

常见Bug类型速查

类型	典型症状	检查点
空指针	NPE/NullReference	初始化、null检查
数组越界	IndexOutOfBounds	边界检查、length验证
并发问题	间歇性失败	锁、原子操作、线程安全
内存泄漏	OOM/性能下降	资源释放、WeakRef
缓存问题	数据不一致	失效策略、版本号
网络问题	超时/连接失败	重试、超时设置
配置问题	行为异常	环境变量、配置文件
依赖问题	ClassNotFound	版本兼容、依赖树