systematic-debugging

系统化调试

概述

随机修复会浪费时间并引入新 Bug。快速打补丁会掩盖根本问题。

核心原则： 尝试修复之前，务必先找到根本原因。只修复症状注定会失败。

违背流程的字面要求，就是违背调试的本意。

铁律

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

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

适用场景

遇到任何技术问题时都要使用：

• 测试失败
• 生产环境中的 Bug
• 行为异常
• 性能问题
• 构建失败
• 集成问题

尤其要在以下情况下使用：

• 时间紧迫时（紧急情况容易让人想要猜测）
• “只要快速修一下”看起来显而易见时
• 你已经尝试过多种修复方法时
• 之前的修复没有奏效时
• 你并未完全理解问题时

不要在以下情况下跳过：

• 问题看起来很简单（简单的 Bug 也有根本原因）
• 你很赶时间（匆忙行事必然导致返工）
• 经理要求现在就修好（系统化处理比反复折腾更快）

四个阶段

你必须完成当前阶段后才能进入下一阶段。

阶段 1：调查根本原因

尝试任何修复之前：

1. 仔细阅读错误消息

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

2. 稳定地复现问题

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

3. 检查近期变更

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

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

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

   提出修复方案之前，先添加诊断性埋点：

   For EACH component boundary:
     - Log what data enters component
     - Log what data exits component
     - Verify environment/config propagation
     - Check state at each layer
   
   Run once to gather evidence showing WHERE it breaks
   THEN analyze evidence to identify failing component
   THEN investigate that specific component
   

   示例（多层系统）：

   # Layer 1: Workflow
   echo "=== Secrets available in workflow: ==="
   echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
   
   # Layer 2: Build script
   echo "=== Env vars in build script: ==="
   env | grep IDENTITY || echo "IDENTITY not in environment"
   
   # Layer 3: Signing script
   echo "=== Keychain state: ==="
   security list-keychains
   security find-identity -v
   
   # Layer 4: Actual signing
   codesign --sign "$IDENTITY" --verbose=4 "$APP"
   

   这能揭示： 哪一层发生故障（密钥 → 工作流 ✓，工作流 → 构建 ✗）

5. 追踪数据流

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

   必需的子技能： 使用 root-cause-tracing 进行反向追踪

   简要步骤：

   • 错误值从何处产生？
   • 哪个调用方传入了错误值？
   • 持续向上追踪，直到找到源头
   • 在源头修复，而非只处理症状

阶段 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）

你的合作伙伴指出你做错了的信号

留意以下提醒：

• “这不是正在发生吗？”——你在没有核实的情况下就作出了假设
• “这样能让我们看到……吗？”——你本该收集证据
• “别猜了”——你在尚未弄明白问题时就提出修复方案
• “深入思考一下”——质疑基本设计，而不只是症状
• “我们卡住了吗？”（带着沮丧）——你的方法行不通

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

常见的自我辩解

借口	事实
“问题很简单，不需要流程”	简单问题也有根本原因。流程处理简单错误很快。
“情况紧急，没时间走流程”	系统化调试比猜测和反复尝试更快。
“先试试这个，再调查”	第一次修复会定下处理模式。从一开始就做好。
“等确认修复有效后再写测试”	未经测试的修复难以持久。先写测试才能证明它有效。
“一次做多个修复更省时间”	无法确定哪个修复起了作用，还会引入新错误。
“参考内容太长，我会自行调整模式”	理解不完整必然导致错误。请完整阅读。
“我知道问题在哪，我来修”	看到症状 ≠ 理解根本原因。
“再试一次修复”（失败 2 次或更多后）	失败 3 次或更多意味着架构有问题。应质疑模式，不要再次修复。

快速参考

阶段	关键活动	成功标准
1. 根因	阅读错误、复现问题、检查变更、收集证据	理解是什么以及为什么
2. 模式	查找可正常运行的示例、进行比较	找出差异
3. 假设	提出理论、进行最小化测试	得到验证或形成新假设
4. 实施	创建测试、修复问题、验证结果	Bug 已解决，测试通过

当流程揭示“没有根因”时

如果系统化调查表明，问题确实由环境因素、时序依赖或外部因素导致：

1. 你已完成调查流程
2. 记录你调查的内容
3. 实施适当的处理（重试、超时、错误消息）
4. 添加监控/日志记录，以便今后调查

**但是：**95% 的“没有根因”案例都是调查不充分。

与其他技能的集成

此技能要求使用：

• root-cause-tracing——当错误位于调用栈深处时必须使用（参见阶段 1，步骤 5）

互补技能：

• defense-in-depth——找到根因后，在多个层级添加验证
• condition-based-waiting——替换阶段 2 中发现的任意超时
• verification-before-completion——在宣称成功前验证修复是否有效

实际影响

根据调试会话的数据：

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