# Systematic Debugging

> 4 阶段系统化调试方法，包含根因分析与基于证据的验证。用于调试复杂问题。

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

---


# 系统化调试

> 来源：obra/superpowers

## 概览

本技能提供结构化的调试方法，避免随机猜测，确保在修复前已充分理解问题。

## 4 阶段调试流程

### 阶段 1：复现

修复前，必须稳定复现问题。

```markdown
## 复现步骤
1. [精确复现步骤]
2. [下一步]
3. [预期结果 vs 实际结果]

## 复现率
- [ ] 必现 (100%)
- [ ] 经常 (50-90%)
- [ ] 偶发 (10-50%)
- [ ] 罕见 (<10%)
```

### 阶段 2：隔离

缩小问题来源范围。

```markdown
## 隔离问题提问
- 问题从什么时候开始出现？
- 最近改了什么？
- 所有环境都会出现吗？
- 能否用最小代码复现？
- 触发问题的最小改动是什么？
```

### 阶段 3：理解

找到根因，而不只停留在症状层。

```markdown
## 根因分析
### 5 个为什么
1. 为什么：[第一层观测]
2. 为什么：[更深层原因]
3. 为什么：[继续深入]
4. 为什么：[接近根因]
5. 为什么：[锁定根因]
```

### 阶段 4：修复与验证

修复后，验证问题已真正解决。

```markdown
## 修复验证
- [ ] Bug 不再复现
- [ ] 关联功能仍然正常
- [ ] 未引入新问题
- [ ] 已添加防回归测试
```

## 调试检查清单

```markdown
## 开始前
- [ ] 能稳定复现
- [ ] 有最小复现用例
- [ ] 明确预期行为

## 调查中
- [ ] 检查最近改动 (git log)
- [ ] 检查日志报错
- [ ] 必要时增加日志
- [ ] 使用调试器/断点

## 修复后
- [ ] 已记录根因
- [ ] 已验证修复
- [ ] 已添加回归测试
- [ ] 已排查相似代码
```

## 常用调试命令

```bash
# Recent changes
git log --oneline -20
git diff HEAD~5

# Search for pattern
grep -r "errorPattern" --include="*.ts"

# Check logs
pm2 logs app-name --err --lines 100
```

## 反模式

[FAIL]  **随机改动** - “也许改这里就好了”
[FAIL]  **忽视证据** - “这不可能是原因”
[FAIL]  **主观断言** - 没有证据就说“肯定是 X”
[FAIL]  **未先复现** - 盲修
[FAIL]  **止步症状** - 没有挖到根因