系统化调试

概述

随机修复浪费时间，并引入新缺陷。快速补丁掩盖了根本问题。

核心原则：在尝试任何修复之前，必须先定位根本原因。仅修复表象即为失败。

违背本流程的字面要求，即等于违背调试的精神内核。

铁律

未经根本原因调查，不得实施任何修复  
未经上下文回顾，不得开展任何调查  

若未完成第 0 阶段，则不可进入第 1 阶段； 若未完成第 1 阶段，则不可提出任何修复方案。

适用场景

适用于所有技术问题：

• 测试失败
• 生产环境缺陷
• 非预期行为
• 性能问题
• 构建失败
• 集成问题

尤其应在以下情况中严格执行：

• 时间紧迫时（紧急状况易诱发盲目猜测）
• “只需一个快速修复”看似显而易见时
• 已尝试过多次修复时
• 此前修复未奏效时
• 尚未完全理解问题本质时

切勿跳过流程的情形：

• 问题看似简单（简单缺陷同样具有根本原因）
• 你正赶时间（仓促操作必然导致返工）
• 上级要求“立刻修复”（系统化方法比盲目试错更快）

五个阶段

你必须完整执行每个阶段，方可进入下一阶段。

第 0 阶段：上下文回顾（强制首步）

在执行任何其他操作之前：

1. 从错误信息中提取关键词

   • 错误类型是什么？（OOM、超时、连接失败、类型错误……）
   • 涉及哪个组件？（server、browser、API、database……）
   • 影响代码库的哪个区域？

2. 检索既有知识

   • 查阅项目文档、MEMORY 文件或历史对话记录
   • 在代码库中搜索类似错误模式：grep -r "ErrorType" .
   • 检查近期相关变更：git log --oneline -20

3. 复盘检索结果

   • 找到相关经验？→ 直接应用，跳转至第 4 阶段
   • 找到部分匹配项？→ 作为第 1 阶段的起点
   • 未发现任何线索？→ 进入第 1 阶段，务必后续记录解决方案

4. 输出格式

   Context Recall:
   - Query: "xxx"
   - Found: [相关知识的描述]
   - Action: [应用已有经验 / 继续调查 / 无匹配]
   

违规行为：未生成上下文回顾输出即进入第 1 阶段 = 流程失败。

第 1 阶段：根本原因调查

在尝试任何修复之前：

1. 仔细阅读错误信息

   • 不跳过任何错误或警告
   • 它们往往已包含确切解决方案
   • 完整阅读堆栈跟踪
   • 记录行号、文件路径、错误码

2. 稳定复现问题

   • 能否可靠触发该问题？
   • 精确步骤是什么？
   • 是否每次必现？
   • 若无法稳定复现 → 收集更多数据，禁止猜测

3. 核查近期变更

   • 哪些变更可能导致此问题？
   • Git diff、近期提交记录
   • 新增依赖、配置变更
   • 环境差异

4. 在多组件系统中收集证据

   当系统含多个组件时（如 CI → build → signing，或 API → service → database）：

   在提出修复前，须添加诊断性埋点：

   对于每个组件边界：
     - 记录进入该组件的数据
     - 记录离开该组件的数据
     - 验证环境/配置是否正确传递
     - 检查各层级的状态
   
   运行一次以获取证据，明确故障发生位置  
   随后分析证据，定位失效组件  
   最后深入调查该特定组件  
   

5. 追踪数据流向

   • 异常值源自何处？
   • 谁向当前函数传入了异常值？
   • 持续向上追溯直至源头
   • 在源头修复，而非在表象处修补

第 2 阶段：模式分析

修复前，先识别模式：

1. 寻找正常工作的示例

   • 在相同代码库中定位功能正常的相似代码
   • 与当前故障逻辑相似、但能正常工作的案例是什么？

2. 对照参考实现进行比对

   • 若正在实现某设计模式，请完整通读其参考实现
   • 切勿略读——逐行审阅
   • 彻底理解该模式后，再着手应用

3. 识别差异点

   • 正常与异常实例之间有何不同？
   • 逐条列出所有差异，无论多细微
   • 切勿假设“这不可能有影响”

4. 理清依赖关系

   • 该模块还依赖哪些其他组件？
   • 需要哪些设置、配置或环境？
   • 它隐含了哪些前提假设？

第 3 阶段：假设与验证

遵循科学方法：

1. 提出单一假设

   • 清晰陈述：“我认为 X 是根本原因，因为 Y”
   • 书面记录该假设
   • 表述需具体，避免模糊

2. 最小化验证

   • 为验证假设，仅做最小必要改动
   • 每次只改变一个变量
   • 禁止一次性修复多个问题

3. 验证通过后再推进

   • 是否生效？是 → 进入第 4 阶段
   • 未生效？→ 提出全新假设
   • 禁止叠加更多修复

4. 当你尚不了解时

   • 坦诚表达：“我不理解 X”
   • 切勿假装知晓
   • 主动寻求帮助
   • 进一步调研

第 4 阶段：实施修复

修复根本原因，而非表象：

1. 编写失败测试用例

   • 最简可行复现方式
   • 尽可能自动化（单元/集成测试）
   • 若无测试框架，提供一次性脚本
   • 修复前必须完成

2. 执行单一修复

   • 仅针对已确认的根本原因
   • 每次仅做一项变更
   • 禁止“顺手优化”类修改
   • 禁止捆绑式重构

3. 验证修复效果

   • 测试是否通过？
   • 其他测试是否仍全部通过？
   • 问题是否真正解决？

4. 若修复未生效

   • 立即停止
   • 统计：已尝试多少次修复？
   • 若少于 3 次：返回第 1 阶段，结合新信息重新分析
   • 若已达或超过 3 次：立即停止并质疑架构（见下方第 5 步）
   • 未经架构讨论，严禁尝试第 4 次修复

5. 3 次以上修复均失败：质疑架构

   此类现象暗示存在架构级问题：

   • 每次修复均暴露出不同位置的新共享状态/耦合/缺陷
   • 修复需依赖“大规模重构”才能落地
   • 每次修复均在别处引发新症状

   立即暂停，审视基础设计：

   • 该模式本身是否合理？
   • 我们是否仅因惯性而坚持沿用？
   • 应重构架构，还是继续修补表象？

   在尝试更多修复前，务必与用户讨论。

危险信号 — 立即停止并回归流程

若你发现自己产生如下想法：

• “先快速修复，之后再深入调查”
• “只改一下 X，试试看是否有效”
• “同时应用多项修改，再运行测试”
• “跳过测试，我手动验证即可”
• “大概率是 X 问题，我这就修复”
• “我虽未完全理解，但这个方案可能有效”
• “虽然模式规定如此，但我打算换种方式适配”
• “主要问题如下：[直接罗列修复项，未做调查]”
• 未完成数据流追踪就提出解决方案
• “再试一次修复”（已尝试 2 次及以上）
• 每次修复均在不同位置暴露新问题

以上任一情形出现，均须：立即停止，退回第 1 阶段。

若已失败 3 次及以上：启动架构审查（参见第 4.5 步）

常见借口辨析

速查表

真实场景效果

基于实际调试会话统计：

• 系统化方法：15–30 分钟完成修复
• 随机修复法：2–3 小时无效折腾
• 首次修复成功率：95% vs 40%
• 引入新缺陷数：趋近于零 vs 频发