| name | systematic-debugging |
| description | 系统化调试指南：寻找根因而非掩盖症状，拒绝盲目猜测，强制四阶段法 |
🔍 Systematic Debugging (系统化调试)
Overview (总则)
盲目修 Bug 只会浪费时间并引入新 Bug。快速补丁往往只是掩盖了底层问题。
核心原则：在尝试修复之前，必须找到根因。只修症状是失败的。
🚫 铁律
在完成第一阶段（根因调查）之前，严禁提交任何修复代码。
🛠️ 四阶段调试法
第一阶段：根因调查 (Root Cause Investigation)
在动手前：
- 仔细阅读错误信息：不要跳过堆栈跟踪，记录行号、文件路径、错误码。
- 稳定复现：确定复现的具体步骤。无法复现 = 缺乏数据，禁止猜测。
- 检查近期变更：使用
git diff 确认最近改了什么。
- 回溯追踪 (Root Cause Tracing)：如果错误发生在深层调用栈，必须向上追溯，直到找到原始触发点。
- 参考：
library/root-cause-tracing.md
第二阶段：模式分析 (Pattern Analysis)
- 寻找正常样例：在代码库中找类似的正常代码，对比差异。
- 完整阅读参考实现：不要扫视，要从头读完相关模块的逻辑。
第三阶段：假设与测试 (Hypothesis and Testing)
- 形成单一假设：明确说出“我认为 X 是根因，因为 Y”。
- 最小化测试：做最小的改动来验证假设。一次只变动一个变量。
第四阶段：实施与防御 (Implementation & Defense)
- 编写必挂测试 (Red Test)：在修复前，先写一个能复现此 Bug 的自动化测试。
- 防御性编程 (Defense-in-Depth)：在数据经过的每一个层级都加上校验，让该 Bug 在结构上变得不再可能。
- 参考：
library/defense-in-depth.md
- 三改不中法则：如果你尝试了 3 次修复都失败了，停止修复。这意味着架构本身可能有基础性问题，请转向与人类讨论架构合理性。
🚩 红旗警示 (Red Flags) - 发现思维滑坡请立即停止
- “先快速修一下，以后再查根因。”
- “试着改改 X 看看行不行。”
- “加了好多地方，现在测试过了。”
- “跳过测试吧，我手动验证过了。”
- “大概是 X 吧，我先修了。”
📚 附属资产
