debugging

调试

综合调试框架，结合系统化调查、根因追踪、纵深验证和验证流程。

核心原则

先调查根因，再进行任何修复

随意修复会浪费时间并引入新 Bug。找出根因，从源头修复，在每一层进行验证，并在宣称成功前完成核验。

适用场景

始终用于： 测试失败、Bug、意外行为、性能问题、构建失败、集成问题，以及在宣称工作完成之前

尤其适用于： 时间紧迫、看似显而易见的“快速修复”、尝试过多种修复方案、尚未完全理解问题，或即将宣称成功

四种技术

1. 系统化调试（references/systematic-debugging.md）

包含四个阶段的框架，确保进行适当调查：

• 阶段 1：根因调查（阅读错误信息、重现问题、检查变更、收集证据）
• 阶段 2：模式分析（寻找有效示例、进行比较、找出差异）
• 阶段 3：假设与测试（提出理论、进行最小化测试、核验）
• 阶段 4：实施（创建测试、一次性修复、核验）

关键规则： 完成每个阶段后再进入下一阶段。未完成阶段 1，不得进行修复。

加载时机： 调查并修复任何 Bug 或问题时

2. 根因追踪（references/root-cause-tracing.md）

沿调用栈反向追踪 Bug，找到最初的触发点。

技术： 当错误在执行深处出现时，逐层反向追踪，直到找到无效数据的来源。从源头修复，而不是处理症状。

包括： 用于二分定位测试污染的 scripts/find-polluter.sh

加载时机： 错误出现在调用栈深处，或不清楚无效数据的来源时

3. 纵深防御（references/defense-in-depth.md）

在数据经过的每一层进行验证，让 Bug 无从发生。

四个层面： 入口验证 → 业务逻辑 → 环境防护 → 调试检测

加载时机： 找到根因后，需要添加全面验证时

4. 核验（references/verification.md）

运行核验命令，并在宣称成功前确认输出。

铁律： 没有最新的核验证据，就不得宣称已完成

运行命令。阅读输出。然后再说明结果。

加载时机： 即将宣称工作已完成、问题已修复或测试已通过时

快速参考

Bug → systematic-debugging.md (Phase 1-4)
  Error deep in stack? → root-cause-tracing.md (trace backward)
  Found root cause? → defense-in-depth.md (add layers)
  About to claim success? → verification.md (verify first)

危险信号

如果出现以下想法，请停下来并遵循流程：

• “先快速修复，之后再调查”
• “只要试着改一下 X，看看是否有效”
• “问题大概出在 X，我来修一下”
• “现在应该可以了” / “看起来修好了”
• “测试通过了，搞定”

这些都意味着： 返回系统化流程。