系统性调试

概述

随机修复浪费时间并引入新错误。快速修补掩盖了根本问题。

核心原则： 在尝试修复之前，始终要找到根本原因。针对症状进行修复即是失败。

违反此过程的字面意思即是违背调试的精神。

铁律

没有经过根本原因调查，不得进行任何修复

如果您尚未完成第一阶段，则不能提出修复方案。

何时使用

用于任何技术问题：

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

尤其要在以下情况使用：

• 时间紧迫时（紧急情况容易让人想猜着试试）
• “只是一个快速修复”看起来显而易见时
• 已经尝试了多次修复时
• 之前的修复没有奏效时
• 没有完全理解问题时

不要在以下情况跳过：

• 问题看起来很简单（简单的问题也有根本原因）
• 你很赶时间（匆忙保证返工）
• 经理要求立即修复（系统化比盲目尝试更快）

四个阶段

您必须在进入下一阶段之前完成每个阶段。

第一阶段：根本原因调查

在尝试任何修复之前：

1. 仔细阅读错误消息
   • 不要跳过错误或警告
   • 它们通常包含确切的解决方案
   • 完整阅读堆栈跟踪
   • 注意行号、文件路径、错误代码
2. 可靠地重现问题
   • 你能稳定地触发它吗？
   • 确切的步骤是什么？
   • 每次都发生吗？
   • 如果无法重现 → 收集更多数据，不要猜测
3. 检查最近的更改
   • 哪些更改可能导致此问题？
   • Git diff，最近的提交
   • 新的依赖项，配置更改
   • 环境差异
4. 在多组件系统中收集证据

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

   在提出修复方案之前，添加诊断性检测：

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

   示例（多层系统）：

   # 层 1：工作流
   echo "=== 工作流中可用的密钥：==="
   echo "IDENTITY: ${IDENTITY:+已设置}${IDENTITY:-未设置}"
   
   # 层 2：构建脚本
   echo "=== 构建脚本中的环境变量：==="
   env | grep IDENTITY || echo "IDENTITY 不在环境中"
   
   # 层 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 步）

你的人类搭档给你的你做错了的信号

注意这些重定向：

• “那个没有发生？” – 你在没有验证的情况下做了假设
• “它会向我们展示……？” – 你应该已经添加了证据收集
• “别猜了” – 你在没有理解的情况下提出修复方案
• “深入思考一下这个问题” – 质疑基础，而不仅仅是症状
• “我们卡住了？”（沮丧地） – 你的方法不奏效

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

常见的合理化借口

快速参考

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

如果系统性调查显示问题确实是环境性的、依赖于时间的或外部的：

1. 你已经完成了流程
2. 记录你所调查的内容
3. 实施适当的处理机制（重试、超时、错误消息）
4. 添加监控/日志以备将来调查

但是： 95% 的“没有根本原因”案例都是调查不彻底。

支持性技术

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

• root-cause-tracing.md – 通过调用栈向后追踪错误，找到原始触发点
• defense-in-depth.md – 找到根本原因后，在多个层添加验证
• condition-based-waiting.md – 用条件轮询替换任意超时

相关技能：

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

现实世界的影响

来自调试过程的经验数据：

• 系统化方法：15-30 分钟修复
• 随机修复方法：2-3 小时的盲目尝试
• 首次修复成功率：95% 对比 40%
• 引入新错误：接近于零对比常见