系统化调试

先问「为什么坏了」，而不是「怎么修」

调试时最常见的陷阱是：看到报错就改代码，改完发现另一个地方又炸了，于是再改一处，如此循环。这种「打地鼠」式的修法不仅浪费时间，还会引入新的 bug——因为你改的时候根本没搞清楚最初的问题出在哪。

Systematic Debugging 针对的就是这件事。它的核心原则只有一条：在动手修复之前，必须先找到根因。症状级的修复被视为失败，无论你改完之后测试是否变绿。

四阶段流程，强制顺序执行

这个技能把调试拆成四个阶段，每个阶段做完才能进入下一个。

Phase 1: 根因调查

• 完整阅读错误信息和堆栈，记下 行号、文件路径、错误码
• 找到稳定复现的步骤，不确定时不猜，先收集更多数据
• 检查最近的 git diff、新依赖、配置变更和环境差异
• 多组件系统里加诊断埋点，确认是哪一层出了问题
• 沿调用栈反向追踪数据流，找到坏值的真正来源

Phase 2: 模式分析

• 找到同一代码库里能正常工作的相似代码
• 完整阅读参考实现，逐行对比，列出所有差异
• 理清依赖项：需要什么配置、什么环境、什么假设

Phase 3: 假设与测试

• 明确写下一个假设：「我认为 X 是根因，因为 Y」
• 做最小的改动来验证，一次只改一个变量
• 验证后要么进入下一阶段，要么形成新假设，不要叠加修复

Phase 4: 实现

• 先写一个能复现问题的失败测试
• 只针对根因做单一修改，不加「顺手优化」
• 验证修复有效且没有破坏其他测试
• 如果已尝试 3 次以上仍未解决，停下来质疑架构本身

什么时候必须停下手

技能里列了一组「红旗」信号：当你想说「先快速修一下，回头再查」「多改几处一起跑测试」「大概能猜到原因，直接改吧」——这些念头出现时，意味着你在跳过流程。正确做法是回到 Phase 1，重新取证。

另外，如果你发现自己每次修复都在不同地方暴露出新的耦合问题，这不是又一个 hypothesis 没猜对，而是架构本身可能选错了方向。这时候应该和团队讨论是否值得重构，而不是继续打补丁。

适用于测试失败、生产 bug、意外行为、性能问题、构建失败、集成故障等任何技术问题，尤其在时间压力大、已有多次失败修复尝试时更要强制走完整流程。