systematic-debugging

name	systematic-debugging
description	4 阶段系统化调试方法，包含根因分析与基于证据的验证。用于调试复杂问题。
allowed-tools	Read, Glob, Grep

系统化调试

来源：obra/superpowers

概览

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

4 阶段调试流程

阶段 1：复现

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

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

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

阶段 2：隔离

缩小问题来源范围。

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

阶段 3：理解

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

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

阶段 4：修复与验证

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

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

调试检查清单

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

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

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

常用调试命令

# 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] 止步症状 - 没有挖到根因