superpowers-systematic-debugging

# Superpowers 系统性调试 ## 核心准则 **随机修 bug 浪费时间内制造新 bug。快速补丁掩盖根本问题。** **核心原则：永远先找根本原因再尝试修复。症状修复 = 失败。** **违反调试流程的字面意思 = 违反调试流程的精神。** ## 铁律 ``` 未经根本原因调查，不许修复 ``` 如果没完成第 1 阶段，就不能提出修复方案。 ## 何时使用 用于任何技术问题： - 测试失败 - 生产 bug - 意外行为 - 性能问题 - 构建失败 - 集成问题 **特别要用于：** - 时间压力大时（紧急情况容易猜） - "就一个快速修复"看起来很明显时 - 已经尝试了多个修复时 - 上次修复没用时 - 没有完全理解问题时 ## 四阶段流程 ### 阶段 1：根本原因调查 **在尝试任何修复之前：** 1. **仔细阅读错误信息** - 不要跳过错误或警告 - 通常包含准确解决方案 - 读完堆栈跟踪 - 记下行号、文件路径、错误码 2. **稳定复现** - 能可靠地触发吗？ - 具体步骤是什么？ - 每次都发生吗？ - 如果不能复现 → 收集更多数据，不要猜 3. **检查最近变更** - 什么变更可能导致这个？ - Git diff、最近提交 - 新依赖、配置变更 - 环境差异 4. **追踪数据流** **当错误在调用栈深处：** - 坏值从哪里产生？ - 什么调用时传入了坏值？ - 一直追踪到找到源头 - 在源头修复，不是在症状处 ### 阶段 2：模式分析 **修复前找到模式：** 1. **找类似工作的例子** - 在同一代码库找类似正常工作的代码 - 什么能正常工作而什么坏了？ 2. **对比参考** - 如果在实现某个模式，彻底读完参考实现 - 不要略读——每一行都要读 - 应用前完全理解模式 3. **识别差异** - 工作的和坏的区别是什么？ - 列出每个差异，不管多小 - 不要假设"那个不重要" 4. **理解依赖** - 这个还需要什么其他组件？ - 什么设置、配置、环境？ - 它做什么假设？ ### 阶段 3：假设与测试 **科学方法：** 1. **形成一个假设** - 清晰陈述："我认为 X 是根本原因，因为 Y" - 写下来 - 要具体，不要模糊 2. **最小化测试** - 做最小可能的变更来测试假设 - 一次只改一个变量 - 不要一次修多个东西 3. **验证后再继续** - 有效？→ 阶段 4 - 无效？→ 形成新假设 - 不要在顶上加更多修复 4. **当不知道时** - 说"我不理解 X" - 不要假装知道 - 寻求帮助 - 做更多研究 ### 阶段 4：实现 **修复根本原因，不修复症状：** 1. **创建失败的测试用例** - 最简单的复现方式 - 能自动化就自动化 - 修复前必须有 - 用 `superpowers-tdd` 技能写正确的失败测试 2. **实现单一修复** - 解决识别的根本原因 - 一次改一个 - 不要"既然在这里"就改进 - 不要捆绑重构 3. **验证修复** - 测试现在通过了吗？ - 其他测试坏了吗？ - 问题真的解决了吗？ 4. **如果修复没用** - 停止 - 数：已经尝试了多少次修复？ - 如果 < 3：回到阶段 1，用新信息重新分析 - **如果 ≥ 3：停止并质疑架构（见下）** - 没有架构讨论不要再尝试修复 #4 5. **如果 3+ 修复都失败：质疑架构** **表明架构问题的模式：** - 每个修复在不同地方揭示新的共享状态/耦合/问题 - 修复需要"大规模重构"才能实现 - 每个修复在其他地方产生新症状 **停止并质疑基本原理：** - 这个模式根本上是合理的吗？ - 我们是在"靠惯性坚持"吗？ - 应该是重构架构还是继续修症状？ **在尝试更多修复之前与主人讨论** ## 红旗 如果发现自己想： - "先快速修复，以后再调查" - "就试试改 X 看看行不行" - "加多个变更，一起跑测试" - "跳过测试，我手动验证" - "大概是 X，让我修那个" - "我没有完全理解但这可能行" - **"再试一次修复"（已经尝试了 2+ 次）** - **每个修复在不同地方揭示新问题** **所有这些意味着：停止。回到阶段 1。** **如果 3+ 修复失败：** 质疑架构。 ## 主人发出的信号（你在做错） - "那没有发生吗？" - 你假定了没有验证 - "这会告诉我们……？" - 应该加了证据收集 - "别猜了" - 你在没理解的情况下提修复 - "再想清楚" - 质疑基本原理，不只是症状 **看到这些时：** 停止。回到阶段 1。 ## 快速参考 | 阶段 | 关键活动 | 成功标准 | |------|---------|---------| | **1. 根本原因** | 读错误，复现，检查变更，收集证据 | 理解了什么和为什么 | | **2. 模式** | 找工作例子，对比 | 识别差异 | | **3. 假设** | 形成理论，最小测试 | 确认或新假设 | | **4. 实现** | 创建测试，修复，验证 | Bug 解决，测试通过 | ## 当过程显示"没有根本原因"时 如果系统性调查发现问题是真正环境相关、时序相关或外部的： 1. 已完成调查流程 2. 记录调查了什么 3. 实现适当处理（重试、超时、错误信息） 4. 为未来调查添加监控/日志 **但是：** 95% 的"没有根本原因"是调查不完整。