systematic-debugging

系统化调试

概述

随机的修复既浪费时间，又会制造新的 bug。快速打补丁只会掩盖底层问题。

核心原则： 在尝试修复之前，始终先找到根本原因。只修复症状就是失败。

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

铁律

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

如果你还没有完成第 1 阶段，就不能提出修复方案。

何时使用

适用于任何技术问题：

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

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

• 处于时间压力下（紧急情况会让猜测变得诱人）
• “只需一个快速修复”看起来很明显
• 你已经尝试过多次修复
• 之前的修复没有奏效
• 你并不完全理解这个问题

在以下情况下不要跳过：

• 问题看起来很简单（简单的 bug 也有根本原因）
• 你很着急（仓促必然导致返工）
• 经理要求现在就修好（系统化比反复折腾更快）

四个阶段

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

阶段 1：根本原因调查

在尝试任何修复之前：

1. 仔细阅读错误信息

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

2. 稳定复现

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

3. 检查最近的变更

   • 什么变更可能导致了这个现象？
   • Git diff、最近的提交
   • 新依赖、配置变更
   • 环境差异

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

   当系统有多个组件时（CI → build → signing，API → service → database）：

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

   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"
   

   这揭示了： 哪一层失败了（secrets → workflow ✓，workflow → build ✗）

5. 追踪数据流

   当错误位于调用栈深处时：

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

   快速版本：

   • 错误值源自哪里？
   • 是什么用错误值调用了它？
   • 持续向上追踪，直到找到源头
   • 在源头修复，而不是在症状处修复

阶段 2：模式分析

在修复之前先找到模式：

1. 寻找可用的示例

   • 在同一代码库中找到类似的可运行代码
   • 哪些可运行的东西与出问题的东西相似？

2. 与参考实现对比

   • 如果要实现某种模式，请完整阅读参考实现
   • 不要略读 - 逐行阅读
   • 在应用之前充分理解该模式

3. 找出差异

   • 可运行的和出问题的之间有什么不同？
   • 列出每一处差异，无论多小
   • 不要假设“那不可能有影响”

4. 理解依赖关系

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

阶段 3：假设与验证

科学方法：

1. 提出单一假设

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

2. 最小化验证

   • 做出尽可能小的变更来验证假设
   • 一次只改变一个变量
   • 不要同时修复多个东西

3. 在继续之前进行验证

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

4. 当你不知道时

   • 说“我不理解 X”
   • 不要假装知道
   • 寻求帮助
   • 进一步研究

阶段 4：实施

修复根本原因，而非表面症状：

1. 创建失败的测试用例

   • 构造尽可能简单的复现
   • 尽可能编写自动化测试
   • 如果没有测试框架，则编写一次性测试脚本
   • 修复前 MUST 先完成
   • 使用 superpowers-ruby:test-driven-development 技能编写规范的失败测试

2. 实施单一修复

   • 解决已确定的根本原因
   • 一次只做一项更改
   • 不要顺手改进其他内容
   • 不要捆绑重构

3. 验证修复

   • 现在测试通过了吗？
   • 是否有其他测试失败？
   • 问题确实解决了吗？

4. 如果修复不起作用

   • STOP
   • 统计：你尝试了多少次修复？
   • 如果 < 3：返回阶段 1，结合新信息重新分析
   • 如果 ≥ 3：STOP 并质疑架构（见下方第 5 步）
   • 未经架构讨论，不要尝试修复 #4

5. 如果 3 次或更多修复均失败：质疑架构

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

   • 每次修复都会在其他位置揭示新的共享状态、耦合或问题
   • 修复需要“大规模重构”才能实施
   • 每次修复都会在其他地方引发新的症状

   STOP 并质疑基本设计：

   • 这种模式在根本上是否合理？
   • 我们是否只是在“纯粹凭惯性坚持”？
   • 应该重构架构，还是继续修复症状？

   尝试更多修复前，先与人类伙伴讨论

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

危险信号——STOP 并遵循流程

如果你发现自己在想：

• “先快速修复，之后再调查”
• “只要试着改一下 X，看看有没有用”
• “做几处更改，然后运行测试”
• “跳过测试，我手动验证就行”
• “问题可能是 X，我来修一下”
• “我还没完全理解，但这样可能行”
• “模式提示应该做 X，但我会换一种方式”
• “主要问题如下：[未经调查就罗列修复方案]”
• 尚未追踪数据流就提出解决方案
• “再尝试修复一次”（已经尝试过 2 次或更多时）
• 每次修复都会在其他位置揭示新问题

以上任何一种情况都意味着：STOP。返回阶段 1。

**如果 3 次或更多修复均失败：**质疑架构（见阶段 4.5）

你的人工伙伴指出你做法有误的信号

留意这些纠正意见：

• “这种情况没有发生吗？”——你未经验证就作了假设
• “这样能让我们看到……吗？”——你本该补充收集证据的手段
• “别猜了”——你还没弄清楚就提出修复方案
• “深入思考这个问题”——质疑基本设计，而不只是症状
• “我们卡住了吗？”（带有沮丧情绪）——你的方法不起作用

**遇到这些情况时：**STOP。返回阶段 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-ruby:test-driven-development — 用于创建失败测试用例（第 4 阶段，第 1 步）
• superpowers-ruby:verification-before-completion — 在宣称成功之前，验证修复是否有效

实际效果

调试会话中的数据：

• 系统性方法：15–30 分钟即可修复
• 随机修复方法：反复折腾 2–3 小时
• 首次修复成功率：95%，而随机修复方法为 40%
• 引入的新 Bug：几乎为零，而随机修复方法中很常见