systematic-debugging

系统化调试

核心原则

未先调查根本原因，绝不修复。

切勿应用只针对症状、掩盖根本问题的补丁。尝试修复前，先弄清楚问题失败的原因。

四阶段框架

阶段 1：调查根本原因

在修改任何代码之前：

1. 仔细阅读错误消息——每个字都很重要
2. 稳定复现问题——无法复现，就无法验证修复
3. 检查近期变更——问题开始出现之前发生了什么变化？
4. 收集诊断证据——日志、堆栈跟踪、状态转储
5. 追踪数据流——沿调用链查找错误值的来源

根本原因追踪技巧：

1. Observe the symptom - Where does the error manifest?
2. Find immediate cause - Which code directly produces the error?
3. Ask "What called this?" - Map the call chain upward
4. Keep tracing up - Follow invalid data backward through the stack
5. Find original trigger - Where did the problem actually start?

关键原则： 切勿只在错误出现的位置修复问题——始终追踪到最初的触发点。

阶段 2：模式分析

1. 找到可正常工作的示例——查找类似且运行正常的代码
2. 全面比较实现方式——不要只浏览一遍
3. 找出差异——正常代码与出错代码之间有什么不同？
4. 了解依赖关系——这段代码依赖什么？

阶段 3：提出假设并测试

运用科学方法：

1. 提出一个明确的假设——“错误是由 X 导致的”
2. 设计最小化测试——一次只更改一个变量
3. 预测结果——如果假设正确，应该会发生什么？
4. 运行测试——执行并观察
5. 验证结果——实际表现是否符合预测？
6. 迭代或继续——假设不正确时加以完善，正确时实施修复

阶段 4：实施

1. 创建失败的测试用例——捕获错误行为
2. 实施单一修复——解决根本原因，而非表面症状
3. 验证测试通过——确认修复有效
4. 运行完整测试套件——确保没有引入回归问题
5. 如果修复失败，立即停止——重新评估假设

关键规则： 如果连续三次或更多次修复都失败，立即停止。这表明存在需要讨论的架构问题，不应继续打补丁。

危险信号——违反流程

如果发现自己有以下想法，请立即停下：

• “先快速修一下，之后再调查”
• “再试一次修复”（已经失败多次之后）
• “这应该能行”（却不清楚为什么）
• “我试试看……”（却没有假设）
• “在我的机器上能用”（却不调查差异）

更深层问题的预警信号

连续修复不断暴露出其他区域的新问题，表明存在架构问题：

• 停止打补丁
• 记录发现的问题
• 继续之前先与团队讨论
• 考虑是否需要重新思考设计

常见调试场景

测试失败

1. Read the FULL error message and stack trace
2. Identify which assertion failed and why
3. Check test setup - is the test environment correct?
4. Check test data - are mocks/fixtures correct?
5. Trace to the source of unexpected value

运行时错误

1. Capture the full stack trace
2. Identify the line that throws
3. Check what values are undefined/null
4. Trace backward to find where bad value originated
5. Add validation at the source

“之前还能用”

1. Use git bisect to find the breaking commit
2. Compare the change with previous working version
3. Identify what assumption changed
4. Fix at the source of the assumption violation

间歇性故障

1. Look for race conditions
2. Check for shared mutable state
3. Examine async operation ordering
4. Look for timing dependencies
5. Add deterministic waits or proper synchronization

调试检查清单

在声称错误已修复之前：

• 已识别并记录根本原因
• 已提出并测试假设
• 修复针对根本原因，而非表面症状
• 已创建能复现错误的失败测试
• 修复后测试现已通过
• 完整测试套件通过
• 未用“快速修复”的说法自我开脱
• 修复精简且有针对性

成效指标

与临时应对方式约 40% 的首次修复成功率相比，系统化调试的首次修复成功率约为 95%。

做法正确的表现：

• 修复不会引发新错误
• 你能解释错误发生的原因
• 类似错误不会再次出现
• 修复后代码有所改善，而不只是“能运行”

与其他技能的结合

• testing-patterns：修复前创建能复现错误的测试