系统化调试

随机改代码浪费时间，还会制造新 Bug；表面修补掩盖根因。

核心： 先查清根因，再谈修复。只治症状 = 失败。
违反流程的字面细节 = 违反调试的精神。

铁律

没有完成第一阶段根因调查，不得提出修复方案。

何时使用

任何技术问题：测试失败、线上 Bug、异常行为、性能、构建失败、集成问题。

尤其： 赶时间、「先 quick fix」、已试多修仍坏、上修无效、自己也不完全懂时——更不能跳过。

不要因「看起来简单」或「经理催」就跳过；紧急时系统化往往比乱试更快。

四阶段（须顺序完成）

第一阶段：根因调查（在动代码前）

1. 逐字读错误与栈：文件、行号、错误码。
2. 稳定复现：步骤、是否必现；无法复现先加观测而非猜。
3. 看近期变更：diff、依赖、配置、环境差异。
4. 多组件系统：在每个边界加 诊断日志（进/出数据、配置是否传到下一层），先跑一轮拿证据，再锁定坏在哪一层。
5. 深层栈错误：沿数据流 向上追溯 坏值来源，在 源头 修（见同目录 root-cause-tracing.md）。

第二阶段：模式分析

找 类似但正常 的代码；若参考某模式则 通读参考实现；列出与坏代码的 每一处差异；理清依赖与假设。

第三阶段：假设与验证

单一假设：「我认为根因是 X，因为 Y」。最小改动 验证；有效 → 第四阶段；无效 → 新假设，不要叠多个修复。不懂就明说并求助。

第四阶段：实现修复

1. 先有加红的失败用例（越简越好），可用 test-driven-development 技能写正规测试。
2. 一次只做一个针对根因的修改，禁止顺手重构。
3. 验证：该测绿、其它测不红、问题真消失。
4. 若仍失败：停下；未满 3 次可回第一阶段带新信息重来；≥3 次仍不对：怀疑 架构/模式 是否根本错误，与协作者讨论后再动。

危险想法（出现就回到第一阶段）

「先 quick fix 再查」「先试改 X」「一次改多处」「跳过测试手动验」「大概是 X」「不完全懂但可能有效」「跟参考不一样但我这样也行」「还没追踪数据流就列修复清单」「已经失败两次还想再赌一次」「每修一处别处又坏」等。

满 3 次失败仍像打地鼠 → 当架构问题谈。

协作者给你的信号

「是不是根本没发生？」「能不能让我们看到…？」「别猜」「往深想」「是不是卡死了？」→ 说明你 假设过多或缺证据，回到第一阶段。

速查

| 阶段 | 做什么 | 标准 | |------|--------|------| | 1 根因 | 读错、复现、变更、证据、追溯 | 能说清 是什么、为什么 | | 2 模式 | 找好的对比、读参考 | 列出差异 | | 3 假设 | 单假设、小步验证 | 证实或换新假设 | | 4 实现 | 失败测试、单修复、验证 | Bug 消失且测试绿 |

「没有根因」

真环境/偶发/外部因素时：记录已排除项，加超时/重试/清晰错误与监控。但 绝大多数「没根因」是 查得不够。

相关文件与技能

• root-cause-tracing.md、defense-in-depth.md、condition-based-waiting.md
• test-driven-development（第四阶段写失败用例）
• verification-before-completion（修完要有证据）