systematic-debugging Skill 多维度简评

综合评分：9.2 / 10 ⭐⭐⭐⭐⭐ 类别：调试 / 根因分析 仓库：obra/superpowers 维护者：Jesse Vincent / Prime Radiant

一、核心定位与价值

systematic-debugging 是 Superpowers 14 个 Skills 中最反直觉、收益最高的。它解决一个根本问题：AI 写代码 80% 的”修复”是瞎猜——看到错误就开始改，改了 3 个地方都没用，然后放弃。

核心原则：“NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST”（没有根因调查，不修复） 一次只做一个改动（ONE CHANGE） 先建失败测试再修复（Failing Test First）

关键洞见：首次修复成功率从 40% 提升到 95%，调试时间从 2-3 小时缩短到 15-30 分钟。

适用场景

• 任何 bug / 测试失败 / 意外行为
• 性能突然下降
• 间歇性问题（flaky test）
• 集成后系统不稳定
• 生产事故

不适用场景

• 已知原因的简单错误（拼写错误、配置错误）
• 用户体验问题（非 bug）
• 性能调优（用 profiling 工具）

二、4 阶段流程

2.1 Phase 1：症状分析（Symptom Analysis）

目标：收集所有相关信息

[1] 错误的完整信息
  - 错误信息（含 stack trace）
  - 错误码
  - 出现的时间 / 频率
  - 触发条件（用户操作 / 时间 / 数据）

[2] 环境信息
  - OS / 浏览器 / 版本
  - 依赖版本
  - 环境变量
  - 网络状态

[3] 复现步骤
  - 最小复现路径
  - 复现率（必现 / 偶现）

[4] 影响范围
  - 受影响用户 / 功能
  - 是否数据丢失
  - 是否可降级

示例：

## Bug 报告：登录后页面空白

### 错误信息
TypeError: Cannot read property 'user' of undefined
  at Dashboard.render (Dashboard.tsx:42:18)
  at Dashboard.componentDidMount

### 复现步骤
1. 打开 https://app.example.com
2. 输入 user@example.com / password
3. 点击"登录"
4. 跳转到 /dashboard → 白屏

### 复现率
100%（必现）

### 环境
Chrome 120 / Windows 11
React 18.2 / Next.js 14.0

### 影响
所有新登录用户都受影响

2.2 Phase 2：生成假设（Hypothesis Generation）

目标：列出所有可能的根本原因

假设 1（H1）：登录 API 返回的 user 字段是 null
假设 2（H2）：前端没正确解析 JWT
假设 3（H3）：后端 session 没设置
假设 4（H4）：路由守卫提前跳转
假设 5（H5）：CORS 阻止了 cookie 设置
假设 6（H6）：localStorage 被清空

技巧：

• 不要只列 1-2 个假设，至少 5 个
• 从最可能到最不可能排序
• 包含”显眼的”和”深藏的”

2.3 Phase 3：验证假设（Hypothesis Verification）

对每个假设，设计实验逐个排除

### H1: 登录 API 返回的 user 字段是 null
- 实验：在 Network 标签查看 /api/login 响应
- 期望：响应是 {"user": {...}, "token": "..."}
- 实际：响应是 {"user": null, "token": "..."}
- 结论：✅ H1 确认

### 进一步追问：为什么 user 是 null？
- 检查后端日志：TypeError in user service line 42
- 原因：数据库查询没找到该邮箱的用户
- 但前端发送的是合法邮箱...

### H2: 前端发送的请求被修改
- 实验：查看前端发送的 body
- 期望：{"email": "user@example.com", "password": "..."}
- 实际：{"email": "USER@EXAMPLE.COM", "password": "..."}
- 结论：❌ H2 错误，邮箱是合法的（小写化处理）

### 回到 H1：为什么数据库查不到 USER@EXAMPLE.COM？
- 检查数据库：所有用户都是小写存储
- 但查询条件是大写 "USER@EXAMPLE.COM" 不匹配
- 根因：用户输入 "user@example.com"（小写），但前端某个库自动转大写

2.4 Phase 4：实施修复（Fix）

前提：根因已明确

• ✅ 创建一个失败的测试用例
• ✅ 写最小化代码让测试通过
• ✅ 运行完整测试套件
• ✅ 检查是否引入新 bug

一次只改 ONE THING——不要”顺便改进”其他东西。

// 修复：在 API 调用前归一化邮箱
const normalizedEmail = email.toLowerCase().trim()
const response = await api.login(normalizedEmail, password)

三、真实案例研究

案例 1：登录白屏（前面示例完整版）

症状：登录后 dashboard 空白 表面原因：Dashboard 拿不到 user 真正根因：邮箱未归一化（大写查询不匹配数据库） 修复：1 行代码 email.toLowerCase().trim()

如果没 systematic-debugging：

• 试 1：把 null 改成 {} → 失败
• 试 2：加 loading 状态 → 失败
• 试 3：换 JWT 库 → 失败
• 试 4：重启服务 → 失败
• 浪费：3 小时

案例 2：偶发 504 Gateway Timeout

症状：生产环境每 1000 次请求有 1 次 504 传统做法：

• 调高 timeout（治标）
• 重启服务（治标）
• 增加实例（浪费钱）

systematic-debugging：

• Phase 1: 504 出现前 1 秒，请求里有什么？→ 大文件上传
• Phase 2: 假设 H1: 上传超时 / H2: 数据库慢 / H3: 网络
• Phase 3: 跑慢查询日志 → 没慢查询
  • 看 nginx access log → 上传文件 1.5GB
  • 默认 body size 限制 1MB → 触发了
• Phase 4: 加 client_max_body_size 10m

根因：客户端上传文件超过 nginx 默认限制 修复：1 行 nginx 配置

案例 3：Flaky Test 间歇失败

症状：CI 上 100 次跑有 5 次失败 传统做法：

• 加 retry（治标）
• 忽略这个测试（逃避）
• 重跑（浪费时间）

systematic-debugging：

• Phase 1: 失败时间戳：3:42 AM, 7:15 AM, 11:30 AM, 4:00 PM
• Phase 2: 假设：时间相关？并发相关？资源相关？
• Phase 3: 失败时 5 分钟前都有 deploy / 大流量 / 内存 spike
  • 看 test output → 失败前都有 “GC pause 2.3s”
  • 是 GC 引起
• Phase 4: 给测试加 warmup + timeout 30s

根因：JVM 偶发 GC 暂停 修复：测试 JVM 参数 + 业务无关测试用 mock

案例 4：上线后 P99 延迟 10 倍

症状：v2 上线后 P99 从 100ms 升到 1s 传统做法：

• 回滚（逃避）
• 扩容（浪费钱）

systematic-debugging：

• Phase 1: 看监控，CPU 100%，DB 慢查询多
• Phase 2: 假设：H1 新 SQL / H2 缺少索引 / H3 同步阻塞
• Phase 3: 慢查询日志发现 N+1 查询
  • v2 加了新功能，每次 fetch user 单独查 posts
  • 没加 JOIN
• Phase 4: 用 Prisma include 一次性查

根因：N+1 查询 修复：一行 Prisma include

四、与其他 Skill 配合

完整工作流

[1] Bug 出现
   ↓
[2] systematic-debugging (4 阶段)
   ↓
[3] test-driven-development (RED → GREEN → REFACTOR)
   ↓
[4] verification-before-completion (跑测试)
   ↓
[5] requesting-code-review (重要 bug)
   ↓
[6] finishing-a-development-branch (合并)

五、5 大反模式（禁止）

5.1 边试边修（Shotgun Debugging）

表现：随便改 5 个地方看哪个有效。 禁止：浪费时间，可能掩盖真正问题。 正确做法：先 systematic-debugging。

5.2 表面修复（Surface Fix）

表现：症状消失就宣称修复。 禁止：根因没解决，下周又出现。 正确做法：追到根本原因。

5.3 顺带改进（Drive-by Improvement）

表现：修 bug 时顺便重命名变量、加日志、换库。 禁止：让 PR 难 review。 正确做法：ONE CHANGE 一个 PR 一个事。

5.4 改测试匹配代码（Move the Goalposts）

表现：测试失败就改测试。 禁止：测试是真理，改测试 = 撒谎。 正确做法：改代码让测试通过。

5.5 跳过根因直接修

表现：“看着像是 X 问题，先试一下”。 禁止：高概率失败，浪费时间。 正确做法：至少 5 Whys 一次。

六、5 Whys 分析法

经典工具——丰田生产方式。

问题：网站首页打不开
Why 1：服务器没响应
Why 2：CPU 100%
Why 3：某个查询占满 CPU
Why 4：这个查询是全表扫描
Why 5：表里数据是 1 亿行，没有索引

根因：缺索引 修复：CREATE INDEX idx ON t (col)（30 秒） 预防：所有大表加索引审计流程

七、压力测试中的根因分析

7.1 内存泄漏

[症状] 跑 24h 后 OOM
[根因定位]
1. 监控 → heap 持续上升
2. heap dump → 发现 Cache 对象占 80%
3. 代码 search → Cache.put 后没 remove
[修复] 加 TTL + 定期清理

7.2 CPU 100%

[症状] 凌晨 3 点告警
[根因定位]
1. pprof → 99% 在某个函数
2. 函数内容：sync.Map.Range 内有 time.Sleep
3. 死循环 + Map 不断增长
[修复] 改用 channel-based queue

7.3 数据库连接池耗尽

[症状] 应用报 "connection timeout"
[根因定位]
1. db stats → 100 连接全在用
2. db.query log → 一个长查询占 80 连接
3. EXPLAIN → 这个查询扫了 1 亿行
[修复] 加索引 + 改 LIMIT 分批

八、Q&A

Q: 跟传统 debugger 区别？ A: 传统 debugger 看执行流；systematic-debugging 看因果链。

Q: 浪费时间吗？ A: 首次修复时间 +15 分钟，但总调试时间 -83%。

Q: 适用所有 bug 吗？ A: 适用 ≥ 90%。简单 typo 不用。

Q: 团队怎么学？ A: 一次 retrospective 分享一个案例。

Q: 中文支持？ A: 完全支持。Skill 逻辑与语言无关。

Q: 跟 pair programming 关系？ A: 是 pair debugging 的方法论基础。

Q: 跟生产事故复盘关系？ A: 完美对齐。复盘就是 systematic-debugging + 5 Whys + action items。

九、Prompt 模板

模板 1：完整 bug 报告

[触发条件] 何时触发这个 bug
[复现步骤]
1. ...
2. ...
[错误信息] 完整 stack trace
[期望行为] 应该是什么
[实际行为] 实际是什么
[环境] 浏览器 / OS / 版本
[已尝试] 我自己试过什么
[业务影响] 多少用户 / 多少损失

模板 2：要求 systematic-debugging

用 systematic-debugging 流程排查这个 bug：
1. 先 Phase 1 收集所有症状
2. Phase 2 列出 5+ 个假设
3. Phase 3 设计实验逐个验证
4. Phase 4 找到根本原因再修复
5. 先写失败测试再改代码
6. 一次只改 ONE CHANGE

模板 3：生产事故复盘

用 systematic-debugging + 5 Whys 复盘这次生产事故：
- 时间 / 影响 / 根因
- 我们做对了什么
- 我们可以改进什么
- Action items（每条有 owner + 截止日期）

十、真实踩坑案例

案例 1：看着像是数据库问题其实是前端问题

症状：报表加载慢，怀疑 SQL。 根因：前端 N 次 API 调用，每次 50ms。 修复：批量 API。 教训：先 systematic-debugging，别凭直觉。

案例 2：fix 了一个 bug 引入 3 个新 bug

症状：登录 bug 修好，但其他功能挂了。 根因：改了公共函数，没跑全测试。 修复：每个 PR 跑全量测试。 教训：ONE CHANGE 原则。

案例 3：以为缓存问题，其实是配置问题

症状：缓存命中率 0%。 根因：Redis 连接串配错，连到测试环境。 修复：修正 .env。 教训：Hypothesis Verification 看真实数据。

案例 4：用户没复现就宣称”应该好了”

症状：bug 报告说支付失败，工程师改了 1 小时说”应该好了”。 根因：没跑测试，没让用户复现。 修复：verification-before-completion 强制验证。 教训：evidence before assertions。

案例 5：5 小时内改 50 个地方

症状：性能差。 根因：工程师东改一处西改一处。 修复：rollback + 重新 systematic-debugging。 教训：ONE CHANGE + 测量 + 验证。

案例 6：测试改了让代码”过”

症状：CI 绿了但用户报 bug。 根因：改了测试的 assertion 让 assert 永远 true。 修复：恢复 assertion，修复代码。 教训：测试是真理，绝不改测试匹配坏代码。

案例 7：fix 在错的环境

症状：本地好，生产坏。 根因：本地用 SQLite，生产用 Postgres，SQL 不兼容。 修复：用 Knex / Prisma 跨数据库 ORM。 教训：先验证生产环境配置。

案例 8：监控没开，看不到根因

症状：用户报慢，但监控没数据。 根因：生产没开 tracing。 修复：接 OpenTelemetry。 教训：systematic-debugging 第 1 步是数据，没有数据寸步难行。

十一、安装

# Claude Code
/plugin marketplace add obra/superpowers
/plugin install superpowers@claude-plugins-official

# 通用
npx skills add obra/superpowers --skill systematic-debugging

# Codex / Cursor / Copilot CLI 也支持

十二、总结

核心价值：

• 4 阶段结构化调试流程
• 5 Whys 根因分析
• “NO FIXES WITHOUT ROOT CAUSE” 铁律
• ONE CHANGE 原则
• 失败测试先于修复

适用人群：

• 所有写代码的工程师
• SRE / DevOps（生产事故）
• QA 工程师
• Tech Lead（带团队调试）

投入产出比：⭐⭐⭐⭐⭐（5/5）—— 所有项目必装。

何时不要用：

• 已知 typo
• 简单配置错误（“忘了保存”）
• 用户体验问题（不是 bug）

配套文档：using-superpowers 元技能 | TDD | verification-before-completion

参考资料

1. obra/superpowers GitHub 仓库
2. Toyota 5 Whys 分析法官方指南
3. Google SRE Book — 事故复盘方法论
4. CSDN: Superpowers Skills 完整探索