systematic-debugging

系统化调试

概述

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

核心原则： 务必先找到根本原因，再尝试修复。只修复症状等于失败。

违背流程的字面要求，就是违背调试的精神。

铁律

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

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

适用场景

任何技术问题都适用：

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

以下情况尤其要使用：

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

不要在以下情况下跳过：

• 问题看起来很简单时（简单的 Bug 也有根本原因）
• 赶时间时（匆忙行事必然导致返工）
• 经理要求立即修复时（系统化排查比盲目尝试更快）

四个阶段

必须完成每个阶段后，才能进入下一阶段。

第 1 阶段：调查根本原因

尝试任何修复之前：

1. 仔细阅读错误消息

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

2. 稳定复现问题

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

3. 检查近期变更

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

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.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 阶段。

常见的自我辩解

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

快速参考

阶段	关键活动	成功标准
1. 根因	阅读错误信息、复现问题、检查更改、收集证据	弄清楚是什么问题，以及为什么会发生
2. 模式	查找有效示例并进行比较	找出差异
3. 假设	提出理论并进行最小化测试	得到验证或形成新假设
4. 实施	创建测试、修复、验证	错误已解决，测试通过

当排查得出「没有根本原因」时

如果系统性调查发现问题确实是由环境、时序或外部因素导致的：

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

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

辅助技巧

这些技巧是系统性调试的一部分，可在此目录中找到：

• root-cause-tracing.md - 沿调用栈反向追踪 Bug，找到最初的触发因素
• defense-in-depth.md - 找到根本原因后，在多个层面添加验证
• condition-based-waiting.md - 用条件轮询替代任意超时

相关技能：

• test-driven-development - 用于创建失败的测试用例（第 4 阶段，第 1 步）
• verifying-before-completion - 在宣称成功前验证修复是否有效

实际影响

根据调试会话的记录：

• 系统性方法：15-30 分钟修复问题
• 随机修复方法：花费 2-3 小时反复折腾
• 首次修复成功率：95% 对比 40%
• 引入的新 Bug：几乎为零，而随机修复则很常见