# Systematic Debugging

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

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

---


# 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. **添加日志**：在关键点输出状态
   ```python
   # 示例：添加诊断日志
   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. **修复后立即测试**
   ```bash
   # 运行相关测试
   npm test -- --grep "相关测试名称"
   
   # 手动复现测试
   [复现步骤]
   ```

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

3. **边界条件测试**
   ```
   - [ ] 正常值
   - [ ] 边界值（0、最大值、空）
   - [ ] 异常值（负数、超长字符串）
   ```

4. **添加监控/测试**
   ```python
   # 添加单元测试防止回归
   def test_edge_case():
       assert fix_function(0) == expected
       assert fix_function(null) == expected
   ```

## 输出模板

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

```markdown
## 调试报告

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

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

### 修复方案
```
[具体代码改动]
```

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

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

## 核心原则

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

## 常见Bug类型速查

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