Systematic debugging

系统性调试

概述

随机修复浪费时间并制造新 bug。快速补丁掩盖了潜在问题。

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

违反这条规则的文字就是违反调试的精神。

铁律

未经根本原因调查，不得修复

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

何时使用

适用于任何技术问题：

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

特别要在以下情况使用：

• 处于时间压力下（紧急情况使人容易猜测）
• "就一个快速修复"看起来很明显
• 你已经尝试了多个修复
• 之前的修复不起作用
• 你不完全理解问题

不要跳过当：

• 问题看起来简单（简单的 bug 也有根本原因）
• 你很着急（仓促保证返工）
• 经理要求立即修复（系统性调试比盲目修复更快）

四个阶段

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

第一阶段：根本原因调查

在任何修复之前：

1. 仔细阅读错误消息

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

2. 稳定复现

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

3. 检查最近的更改

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

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

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

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

   对于每个组件边界：
     - 记录进入组件的数据
     - 记录离开组件的数据
     - 验证环境/配置传播
     - 检查每层的状态
   
   运行一次以收集证据，显示它在哪里断裂
   然后分析证据以识别故障组件
   然后调查那个特定组件
   

   示例（多层系统）：

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

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

5. 追踪数据流

   当错误在调用栈深处时：

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

   快速版本：

   • 坏值从哪里来的？
   • 什么用坏值调用了这个？
   • 一直向上追踪直到找到源头
   • 在源头修复，而非症状

第二阶段：模式分析

修复前先找模式：

1. 找到工作的示例

   • 在同一代码库中找到类似的运行代码
   • 什么与坏掉的类似但能工作？

2. 与参考对比

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

3. 识别差异

   • 工作的和坏掉之间有什么不同？
   • 列出每个差异，无论多小
   • 不要假设"那不重要"

4. 理解依赖

   • 这还需要什么其他组件？
   • 什么设置、配置、环境？
   • 它做什么假设？

第三阶段：假设和测试

科学方法：

1. 形成单一假设

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

2. 最小化测试

   • 做最小的可能更改来测试假设
   • 一次一个变量
   • 不要一次修复多件事

3. 继续前验证

   • 有效了吗？是 → 第四阶段
   • 没效果？形成新假设
   • 不要在之上添加更多修复

4. 当你不知道时

   • 说"我不理解 X"
   • 不要假装知道
   • 寻求帮助
   • 做更多研究

第四阶段：实施

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

1. 创建失败的测试用例

   • 最简单的可能复现
   • 如果可能，使用自动化测试
   • 如果没有框架，使用一次性测试脚本
   • 修复前必须存在
   • 使用 superpowers:test-driven-development 技能来编写正确的失败测试

2. 实施单一修复

   • 解决已识别的根本原因
   • 一次一个更改
   • 不要"既然在这里就"改进
   • 不捆绑重构

3. 验证修复

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

4. 如果修复不起作用

   • 停止
   • 计数：你尝试了多少次修复？
   • 如果 < 3：回到第一阶段，用新信息重新分析
   • 如果 ≥ 3：停止并质疑架构（见下面步骤 5）
   • 没有架构讨论不要尝试第 4 次修复

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

   表明架构问题的模式：

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

   停止并质疑基本原则：

   • 这个模式从根本上合理吗？
   • 我们是在"纯粹靠惯性坚持"吗？
   • 我们应该重构架构还是继续修复症状？

   在尝试更多修复之前与你的伙伴讨论

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

红旗 - 停止并遵循流程

如果你发现自己有以下想法：

• "现在快速修复，稍后调查"
• "就试试改 X 看是否有效"
• "添加多个更改，运行测试"
• "跳过测试，我会手动验证"
• "可能是 X，让我修复那个"
• "我不完全理解但这可能有效"
• "模式说 X 但我会以不同方式调整"
• "主要问题如下：[在未调查的情况下列出修复]"
• 在追踪数据流之前提出解决方案
• "再试一次修复"（在已经尝试 2+ 次后）
• 每次修复在不同地方揭示新问题

所有这些意味着：停止。回到第一阶段。

如果 3+ 次修复失败： 质疑架构（见第四阶段 5）

你的伙伴的信号：你在做错

注意这些重新定向：

• "那没有发生吗？" —— 你未验证就假设了
• "这会给我们看……？" —— 你应该添加证据收集
• "停止猜测" —— 你在未理解的情况下提出修复
• "Ultrathink this" —— 质疑基本原则，而不只是症状
• "我们卡住了？"（沮丧）—— 你的方法不起作用

当你看到这些时： 停止。回到第一阶段。

常见合理化

借口	现实
"问题很简单，不需要流程"	简单问题也有根本原因。流程对简单 bug 也很快。
"紧急，没时间走流程"	系统性调试比猜测-检查式折腾更快。
"先试试这个，然后再调查"	第一次修复就设定了模式。从一开始就用正确的方法。
"确认修复有效后再写测试"	未测试的修复不持久。先测试才能证明它有效。
"一次多修复节省时间"	无法隔离什么起作用了。会导致新 bug。
"参考资料太长了，我会调整模式"	部分理解保证有 bug。完整阅读它。
"我看到问题了，让我修复它"	看到症状 ≠ 理解根本原因。
"再试一次修复"（2+ 次后）	3+ 次失败 = 架构问题。质疑模式，不要再次修复。

快速参考

阶段	关键活动	成功标准
1. 根本原因	读错误、复现、检查更改、收集证据	理解 WHAT 和 WHY
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 —— 用于创建失败测试用例（第四阶段，步骤 1）
• superpowers:verification-before-completion —— 在声称成功之前验证修复有效

实际影响

来自调试会话：

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