systematic-debugging

name	systematic-debugging
description	系统化调试指南：寻找根因而非掩盖症状，拒绝盲目猜测，强制四阶段法

🔍 Systematic Debugging (系统化调试)

Overview (总则)

盲目修 Bug 只会浪费时间并引入新 Bug。快速补丁往往只是掩盖了底层问题。 核心原则：在尝试修复之前，必须找到根因。只修症状是失败的。

🚫 铁律

在完成第一阶段（根因调查）之前，严禁提交任何修复代码。

---

🛠️ 四阶段调试法

第一阶段：根因调查 (Root Cause Investigation)

在动手前：

1. 仔细阅读错误信息：不要跳过堆栈跟踪，记录行号、文件路径、错误码。
2. 稳定复现：确定复现的具体步骤。无法复现 = 缺乏数据，禁止猜测。
3. 检查近期变更：使用 git diff 确认最近改了什么。
4. 回溯追踪 (Root Cause Tracing)：如果错误发生在深层调用栈，必须向上追溯，直到找到原始触发点。
   • 参考：library/root-cause-tracing.md

第二阶段：模式分析 (Pattern Analysis)

1. 寻找正常样例：在代码库中找类似的正常代码，对比差异。
2. 完整阅读参考实现：不要扫视，要从头读完相关模块的逻辑。

第三阶段：假设与测试 (Hypothesis and Testing)

1. 形成单一假设：明确说出“我认为 X 是根因，因为 Y”。
2. 最小化测试：做最小的改动来验证假设。一次只变动一个变量。

第四阶段：实施与防御 (Implementation & Defense)

1. 编写必挂测试 (Red Test)：在修复前，先写一个能复现此 Bug 的自动化测试。
2. 防御性编程 (Defense-in-Depth)：在数据经过的每一个层级都加上校验，让该 Bug 在结构上变得不再可能。
   • 参考：library/defense-in-depth.md
3. 三改不中法则：如果你尝试了 3 次修复都失败了，停止修复。这意味着架构本身可能有基础性问题，请转向与人类讨论架构合理性。

---

🚩 红旗警示 (Red Flags) - 发现思维滑坡请立即停止

• “先快速修一下，以后再查根因。”
• “试着改改 X 看看行不行。”
• “加了好多地方，现在测试过了。”
• “跳过测试吧，我手动验证过了。”
• “大概是 X 吧，我先修了。”

---

📚 附属资产

• 回溯追踪指南
• 深度防御校验
• 条件轮询范式