systematic-debugging

name	systematic-debugging
description	遇到任何 bug、测试失败或意外行为时，在提出修复方案之前使用

系统化调试

概述

随机修复浪费时间并产生新 bug。快速补丁掩盖了底层问题。

核心原则： 在尝试修复之前，务必先找到根本原因。仅修复症状即为失败。

违反此流程的文字精神，即是违反调试的灵魂。

铁律

未完成根本原因调查之前，不得进行任何修复

如果你尚未完成阶段 1，就不能提出修复方案。

何时使用

适用于任何技术问题：

• 测试失败
• 生产环境 bug
• 意外行为
• 性能问题
• 构建失败
• 集成问题

以下情况尤其需要使用：

• 时间紧迫时（紧急情况下更容易想靠猜测）
• "快速修一下就行"看起来很明显时
• 已经尝试过多次修复时
• 之前的修复没有效果时
• 对问题不完全理解时

以下情况不要跳过：

• 问题看起来很简单（简单 bug 也有根本原因）
• 时间很赶（仓促行事必然导致返工）
• 主管要求立刻修好（系统化方法比反复折腾更快）

四个阶段

每个阶段完成之后才能进入下一阶段。

阶段 1：根本原因调查

在尝试任何修复之前：

1. 仔细阅读错误消息

   • 不要跳过错误或警告
   • 它们通常包含确切的解决方案
   • 完整阅读堆栈跟踪
   • 注意行号、文件路径、错误码

2. 稳定复现

   • 能否可靠触发？
   • 确切步骤是什么？
   • 每次都发生吗？
   • 如果无法复现 → 收集更多数据，不要猜测

3. 检查近期变更

   • 哪些变动可能导致这个问题？
   • Git diff、最近的提交
   • 新的依赖、配置变更
   • 环境差异

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

   当系统有多个组件时（CI → 构建 → 签名，API → 服务 → 数据库）：

   在提出修复方案之前，添加诊断工具：

   对每个组件边界：
     - 记录进入组件的数据
     - 记录离开组件的数据
     - 验证环境/配置的传递
     - 检查每一层的状态
   
   运行一次以收集证据，显示问题发生在哪里
   然后分析证据以确定出错的组件
   然后深入调查该特定组件
   

   示例（多层系统）：

   # 第 1 层：工作流
   echo "=== 工作流中可用的密钥：==="
   echo "IDENTITY: ${IDENTITY:+已设置}${IDENTITY:-未设置}"
   
   # 第 2 层：构建脚本
   echo "=== 构建脚本中的环境变量：==="
   env | grep IDENTITY || echo "IDENTITY 不在环境中"
   
   # 第 3 层：签名脚本
   echo "=== 钥匙串状态：==="
   security list-keychains
   security find-identity -v
   
   # 第 4 层：实际签名
   codesign --sign "$IDENTITY" --verbose=4 "$APP"
   

   这揭示了： 哪一层失败（密钥 → 工作流 ✓，工作流 → 构建 ✗）

5. 追踪数据流

   当错误发生在调用栈深处时：

   完整的前向追踪技术请参阅本目录中的 root-cause-tracing.md。

   快速版本：

   • 坏值从哪里产生？
   • 是什么用坏值调用了这里？
   • 持续向上追踪直到找到源头
   • 在源头修复，而非在症状处修复

阶段 2：模式分析

修复之前先找到模式：

1. 寻找正常工作的示例

   • 在同一代码库中定位类似的可工作代码
   • 哪些与出问题代码类似的东西是正常工作的？

2. 对照参考资料进行比较

   • 如果要实现某个模式，完整阅读参考实现
   • 不要略读——逐行阅读
   • 在应用之前完全理解该模式

3. 识别差异

   • 正常工作和出问题的代码之间有什么区别？
   • 列出每一个差异，无论多小
   • 不要假设"这个不可能有影响"

4. 理解依赖关系

   • 需要哪些其他组件？
   • 什么设置、配置、环境？
   • 它做了哪些假设？

阶段 3：假设与测试

科学方法：

1. 形成单个假设

   • 清楚陈述："我认为 X 是根本原因，因为 Y"
   • 写下来
   • 具体明确，不要模糊

2. 最小化测试

   • 做出尽可能最小的变更来测试假设
   • 一次只改变一个变量
   • 不要同时修复多个问题

3. 验证后再继续

   • 成功了吗？是 → 阶段 4
   • 没有成功？形成新的假设
   • 不要在原有基础上叠加更多修复

4. 当你不确定时

   • 说"我不理解 X"
   • 不要假装知道
   • 寻求帮助
   • 继续研究

阶段 4：实施

修复根本原因，而不是症状：

1. 创建失败的测试用例

   • 最简复现
   • 尽可能使用自动化测试
   • 如果没有测试框架则使用一次性测试脚本
   • 修复之前必须有测试
   • 使用 test-driven-development 技能编写合适的失败测试

2. 实施单一修复

   • 解决已确定的根本原因
   • 一次只做一个变更
   • 不要"顺便"做其他改进
   • 不要捆绑重构

3. 验证修复

   • 测试现在通过了吗？
   • 其他测试没有被破坏吗？
   • 问题确实解决了吗？

4. 如果修复不生效

   • 停止
   • 计数：你已经尝试了多少次修复？
   • 如果 < 3：返回阶段 1，利用新信息重新分析
   • 如果 ≥ 3：停止并质疑架构（见下方第 5 步）
   • 不要在未进行架构讨论的情况下尝试第 4 次修复

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

   表明存在架构问题的模式：

   • 每次修复都会在其他地方暴露新的共享状态/耦合/问题
   • 修复需要"大规模重构"才能实施
   • 每次修复都会在其他地方产生新的症状

   停止并质疑基础：

   • 这个模式在根本上合理吗？
   • 我们是否"仅靠惯性在坚持它"？
   • 是否应该重构架构，而不是继续修复症状？

   与用户讨论后再尝试更多修复

   这不是假设失败——这是架构错误。

红旗信号——停止并按流程行事

如果你发现自己在想：

• "先快速修一下，后面再调查"
• "试试改 X 看看能不能行"
• "加多个改动，跑一下测试"
• "跳过测试，我手动验证"
• "大概是 X，我来修一下"
• "我不完全理解，但这可能管用"
• "模式说是 X，但我换个方式适配"
• "主要问题有：[未做调查就列出修复方案]"
• 在追踪数据流之前就提出解决方案
• "再试一次修复"（已经尝试了 2 次以上）
• 每次修复都在不同的地方暴露新问题

以上所有情况都意味着：停止。返回阶段 1。

如果 3 次以上修复失败： 质疑架构（见阶段 4.5）

用户发出的你做法有误的信号

注意以下纠正信号：

• "那不是正在发生吗？"——你在没有验证的情况下做了假设
• "它能告诉我们……吗？"——你本应添加证据收集
• "不要再猜了"——你在不理解的情况下提出修复方案
• "深入思考这个问题"——质疑基础，而不仅仅是症状
• "我们卡住了吗？"（沮丧）——你的方法不起作用

当看到这些信号时： 停止。返回阶段 1。

常见的自我辩解

借口	现实
"问题很简单，不需要流程"	简单问题也有根本原因。流程对简单 bug 来说也很快。
"紧急情况，没时间走流程"	系统化调试比猜测-检查式的反复折腾更快。
"先试试这个，然后再调查"	第一次修复定下基调。从一开始就做对。
"确认修复生效后再写测试"	未经测试的修复不会稳固。先写测试来证明。
"一次修多个省时间"	无法隔离什么起了作用。还会产生新 bug。
"参考太长了，我适配一下模式就行"	部分理解必然导致 bug。完整阅读。
"我看到问题了，我来修"	看到症状不等于理解根本原因。
"再试一次修复"（2 次以上失败后）	3 次以上失败 = 架构问题。质疑模式，不要再修了。

快速参考

阶段	关键活动	成功标准
1. 根本原因	阅读错误、复现、检查变更、收集证据	理解是什么和为什么
2. 模式	寻找正常工作的示例、对比	识别差异
3. 假设	形成理论、最小化测试	确认或形成新假设
4. 实施	创建测试、修复、验证	bug 解决、测试通过

当流程揭示"没有根本原因"时

如果系统化调查显示问题确实是环境性的、时间相关的或外部性的：

1. 你已经完成了流程
2. 记录你调查了什么
3. 实施适当的处理（重试、超时、错误消息）
4. 添加监控/日志以便未来调查

但是： 95% 的"没有根本原因"案例都是不完整的调查。

辅助技术

这些技术是系统化调试的组成部分，可在本目录中找到：

• root-cause-tracing.md - 通过调用栈反向追踪 bug 以找到原始触发点
• defense-in-depth.md - 在找到根本原因后在多个层级添加验证
• condition-based-waiting.md - 用条件轮询替代任意超时

实际影响

来自调试实践的数据：

• 系统化方法：15-30 分钟修复
• 随机修复方法：2-3 小时的反复折腾
• 首次修复成功率：95% vs 40%
• 引入新 bug：几乎为零 vs 常见