systematic-debugging

name	systematic-debugging
description	遇到任何 bug、测试失败或异常行为时，在提出修复方案前使用。要求先定位根因，再实施修复。

系统化调试

铁律

在完成根因调查前，不得提出修复方案。

适用范围

• 测试失败、线上 bug、行为异常、性能回退、构建失败、集成问题。
• 越是紧急越要使用，避免盲修反复返工。

四阶段流程（必须按序）

阶段 1：根因调查

1. 逐行读错误与栈信息。
2. 复现并确认稳定触发条件。
3. 检查最近变更（代码/配置/依赖/环境）。
4. 多组件系统先加边界诊断日志，定位“哪一层断了”。
5. 逆向追踪坏数据来源，修源头不修症状。

阶段 2：模式对比

1. 在同仓库找可工作的相似实现。
2. 与参考实现逐项比对，避免“只看大概”。
3. 列出所有差异并验证影响。
4. 明确依赖前提与隐含假设。

阶段 3：假设验证

1. 形成单一可证伪假设。
2. 做最小改动实验，一次只动一个变量。
3. 根据结果更新假设；失败就重建假设，不叠补丁。
4. 不懂就明确说不懂，继续取证或求助。

阶段 4：实施修复

1. 先写可失败的最小复现测试。
2. 只修一个根因。
3. 运行完整相关验证。
4. 确认无回归后再结束。

禁忌

• 症状导向修复。
• 多点同时改导致无法归因。
• 仅靠“看起来对”就宣布完成。