系统化调试 (Systematic Debugging)
包含根因分析的四阶段调试方法论。在调查Bug、修复测试失败或排除异常行为时使用。在找到根因之前绝不动手修复。
核心原则
在未完成根因调查之前，绝不动手修复。
永远不要应用只针对症状的补丁，因为那会掩盖潜在问题。在尝试修复之前，必须理解失败的原因（为什么？）。
四阶段框架
- 第一阶段：根因调查 (Root Cause Investigation)
在改动任何代码之前：彻底阅读错误信息 - 每一个字都至关重要。稳定重现问题 - 如果无法重现，就无法验证修复。检查最近的变更 - 在问题开始出现之前，有哪些改动？收集诊断证据 - 日志、堆栈追踪、状态转储（State Dumps）。追踪数据流 - 顺着调用链找到异常值源于何处。根因追踪规范：观察症状 - 错误在哪里显现？寻找直接原因 - 哪行代码直接产生了错误？询问“谁调用了它？” - 向上映射调用链。持续向上追踪 - 在堆栈中向后追踪无效数据。寻找原始触发点 - 问题究竟是从哪里开始的？关键原则： 永远不要只在错误出现的地方修复问题——务必追踪到原始触发点。
- 第二阶段：模式分析 (Pattern Analysis)
寻找正常运行的案例 - 找到实现逻辑相似但运行正确的代码。完整对比实现 - 表面和内在都要，不要走马观花。识别差异点 - 运行正常与运行失败的代码之间有什么不同？理解依赖关系 - 这段代码依赖于哪些外部因素？
- 第三阶段：假设与测试 (Hypothesis and Testing)
应用科学方法：制定一个明确的假设 - “错误发生是因为 X ”。设计最小化测试 - 一次只改变一个变量。预测结果 - 如果假设正确，应该发生什么？执行测试 - 运行并观察。验证结果 - 行为是否符合预测？迭代或继续 - 如果错误，修正假设；如果正确，开始实施。
- 第四阶段：实施修复 (Implementation)
创建失败的测试用例 - 捕获 Bug 的行为。实施单一修复 - 针对根因，而非症状。验证测试通过 - 确认修复有效。运行全量测试套件 - 确保没有引入回归错误。如果修复失败，立即停止 - 重新评估假设。
关键规则： 如果连续三次尝试修复均告失败，停止。这预示着存在架构性问题，需要讨论而非更多补丁。
红灯警告 - 违规行为
如果你发现自己产生以下想法，请立即停止：
“先快速修复，以后再查。”
“再试一种修复方法。”（在多次失败后）
“这应该能行。”（在不理解原理的情况下）
“让我尝试一下……”（在没有假设的情况下）
“在我的机器上是好的。”（在未调查差异原因的情况下）
深度问题的预兆
连续的修复在不同区域引发了新问题，这表明存在架构缺陷：
停止打补丁。
记录已发现的情况。
在继续之前与团队讨论。
考虑是否需要重新思考设计。
常见调试场景
测试失败
阅读完整的错误信息和堆栈追踪。
识别哪个断言失败了以及原因。
检查测试设置 - 测试环境是否正确？
检查测试数据 - Mocks/Fixtures 是否正确？
追踪到预期外数值的来源。
运行时错误 (Runtime Errors)
获取完整的堆栈追踪。
准确定位抛出异常的代码行。
检查哪些值是 undefined 或 null。
向后追踪以找到坏值产生的源头。
在源头添加校验逻辑。
“以前是好的”
找到引入错误的提交，即最后一次修改了什么。
将变更与之前的正常版本进行对比。
识别哪些假设发生了变化。
在违反假设的源头进行修复。
间歇性失败
寻找竞争条件（Race Conditions）。
检查共享的可变状态。
检查异步操作的顺序。
寻找时序依赖。
添加确定性的等待或正确的同步机制。
调试检查表
在声称 Bug 已修复之前：
已识别并记录根因
已制定并测试假设
修复针对的是根因，而非症状
已创建能重现 Bug 的失败测试用例
应用修复后，测试现在通过
全量测试套件通过
未使用“快速修复”等借口
修复方案精简且专注
成功指标
系统化调试的首跳修复率约为 95%，而随意调试的方法仅为 40%。
做对的迹象：
修复没有产生新 Bug。
你能解释 Bug 发生的原因。
同类 Bug 不再重复出现。
代码在修复后变得更健壮，而不仅仅是“能运行”。
与其他技能结合
测试模式（testing-patterns）：在修复之前，先创建能够重现该 Bug 的测试。
技能地址：https://github.com/ymk0577/skills/blob/main/skills/systematic-debugging/SKILL.md
如有更新，以技能地址为准。