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.md，了解完整的反向追踪技术。

   简要步骤：

   • 错误值从何处产生？
   • 是什么以错误值调用了它？
   • 持续向上追踪，直到找到源头
   • 在源头修复，而不是只修复症状

阶段 2：模式分析

先找到模式，再进行修复：

1. 寻找可用示例

   • 在同一代码库中找到类似且能正常工作的代码
   • 与出问题的代码类似的部分中，哪些是正常工作的？

2. 对照参考实现

   • 如果要实现某种模式，请完整阅读参考实现
   • 不要略读——逐行阅读
   • 完全理解该模式后再应用

3. 找出差异

   • 正常工作的代码与出问题的代码之间有什么不同？
   • 列出所有差异，无论多么细微
   • 不要想当然地认为“那不重要”

4. 理解依赖关系

   • 它需要哪些其他组件？
   • 需要哪些设置、配置和环境？
   • 它基于哪些假设？

阶段 3：提出假设并测试

采用科学方法：

1. 提出单一假设

   • 清楚地陈述：“我认为 X 是根本原因，因为 Y”
   • 把它写下来
   • 具体明确，不要含糊其辞

2. 进行最小化测试

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

3. 继续之前先验证

   • 是否奏效？是 → 阶段 4
   • 没有奏效？提出一个新假设
   • 不要在此基础上叠加更多修复

4. 不知道时

   • 直接说“我不理解 X”
   • 不要假装自己知道
   • 寻求帮助
   • 继续调查

第 4 阶段：实施

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

1. 创建失败的测试用例

   • 尽可能最简单的复现
   • 如果可能，编写自动化测试
   • 如果没有测试框架，编写一次性测试脚本
   • 修复之前必须先有测试
   • 使用 superpowers: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 - 用条件轮询替代任意超时

相关技能：

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

现实世界影响

来自调试会话：

• 系统性方法：15-30 分钟修复
• 随机修复方法：2-3 小时的反复折腾
• 首次修复率：95% 对比 40%
• 引入的新 bug：接近零 对比 常见