# Systematic Debugging

> 系统化调试方法论，找到根本原因再修复

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

---


# 系统化调试

基于 [obra/superpowers](https://github.com/obra/superpowers) 的调试方法论。

## 核心原则

> **永远先找到根本原因，再尝试修复。症状修复是失败的。**

## 触发条件

当用户遇到 Bug、错误、或需要排查问题时激活。

## 调试流程

### 阶段1：问题定义
```
1. 明确预期行为是什么
2. 明确实际行为是什么
3. 确定问题的可复现步骤
4. 记录环境信息（版本、配置等）
```

### 阶段2：信息收集
```
1. 收集错误日志和堆栈信息
2. 确定问题首次出现的时间
3. 识别最近的代码变更
4. 检查相关配置和依赖
```

### 阶段3：假设形成
```
1. 基于信息提出可能的原因
2. 按可能性排序
3. 设计验证方案
```

### 阶段4：假设验证
```
1. 一次只验证一个假设
2. 使用最小化测试用例
3. 记录验证结果
4. 排除或确认假设
```

### 阶段5：根因确认
```
1. 确认找到的是根本原因，不是症状
2. 验证修复方案能解决问题
3. 确保不引入新问题
```

### 阶段6：修复与验证
```
1. 实施最小化修复
2. 编写回归测试
3. 验证修复效果
4. 文档记录
```

## 输出格式

```markdown
# 🐛 调试报告

## 问题描述
- **预期行为**：[描述]
- **实际行为**：[描述]
- **复现步骤**：
  1. [步骤1]
  2. [步骤2]
  3. [步骤3]

## 环境信息
- **系统**：[OS版本]
- **运行时**：[Node/Python/Java版本]
- **依赖版本**：[关键依赖]

## 错误信息
```
[错误日志/堆栈信息]
```

## 调查过程

### 假设1：[假设描述]
- **验证方法**：[如何验证]
- **结果**：✅ 确认 / ❌ 排除
- **证据**：[支持结论的证据]

### 假设2：[假设描述]
- **验证方法**：[如何验证]
- **结果**：✅ 确认 / ❌ 排除
- **证据**：[支持结论的证据]

## 根本原因
[详细说明根本原因]

## 修复方案
```[语言]
// 修复代码
```

## 验证结果
- [ ] 问题已修复
- [ ] 回归测试通过
- [ ] 无新问题引入

## 预防措施
[如何避免类似问题再次发生]
```

## 常见调试技巧

### 二分法定位
```
1. 确定问题存在的范围
2. 将范围一分为二
3. 确定问题在哪一半
4. 重复直到定位到具体位置
```

### 最小化复现
```
1. 从完整场景开始
2. 逐步移除无关代码/配置
3. 直到找到最小复现用例
4. 最小用例更容易分析
```

### 橡皮鸭调试
```
1. 向"橡皮鸭"解释代码逻辑
2. 逐行解释代码在做什么
3. 解释过程中往往能发现问题
```

### 日志追踪
```
1. 在关键节点添加日志
2. 记录输入、输出、状态
3. 通过日志追踪执行流程
4. 定位异常发生位置
```

## 常见陷阱

### ❌ 避免
- 不理解问题就开始修复
- 同时修改多处代码
- 假设问题原因而不验证
- 只修复症状不找根因
- 修复后不验证

### ✅ 建议
- 先复现，再分析
- 一次只改一处
- 用证据支持结论
- 找到根本原因
- 编写回归测试