系统化调试

概览

随机修复浪费时间并创造新的错误。快速补丁掩盖了根本问题。

核心原则： 在尝试修复之前总是先找到根本原因。症状修复是失败的。

违反这个过程的字面意义就是违反调试的精神。

铁律

没有根本原因调查就不要修复

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

何时使用

用于任何技术问题：

测试失败
生产中的缺陷
意外行为
性能问题
构建失败
集成问题

特别是当：

时间紧迫（紧急情况使猜测变得诱人）
"只是一个快速修复"似乎很明显
你已经尝试了多个修复
之前的修复没有奏效
你完全不理解问题

不要跳过当：

问题看起来很简单（简单的错误也有根本原因）
你在赶时间（匆忙保证返工）
经理现在就想要它被修复（系统化比挣扎更快）

四个阶段

你必须在进行下一个阶段之前完成每个阶段。

第一阶段：根本原因调查

在尝试任何修复之前：

仔细阅读错误消息
- 不要跳过错误或警告
- 它们通常包含确切的解决方案
- 完整阅读堆栈跟踪
- 注意行号、文件路径、错误代码
一致地重现
- 你能可靠地触发它吗？
- 确切的步骤是什么？
- 它每次都会发生吗？
- 如果不能重现 → 收集更多数据，不要猜测
检查最近的更改
- 什么变化可能导致这个？
- Git diff，最近的提交
- 新的依赖项，配置更改
- 环境差异

在多组件系统中收集证据 当系统有多个组件（CI → 构建 → 签名，API → 服务 → 数据库）： 在提出修复之前，添加诊断仪器：

对于每个组件边界：
  - 记录进入组件的数据
  - 记录退出组件的数据
  - 验证环境/配置传播
  - 检查每一层的状态

运行一次以收集证据显示它在哪里断裂
然后分析证据以识别失败的组件
然后调查该特定组件

示例（多层系统）：

# 第1层：工作流
echo "=== 工作流中可用的秘密：==="
echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"

# 第2层：构建脚本
echo "=== 构建脚本中的环境变量：==="
env | grep IDENTITY || echo "IDENTITY不在环境"

# 第3层：签名脚本
echo "=== 密钥链状态：==="
security list-keychains
security find-identity -v

# 第4层：实际签名
codesign --sign "$IDENTITY" --verbose=4 "$APP"

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

追踪数据流 当错误深入调用栈时：

查看此目录中的root-cause-tracing.md了解完整的反向追踪技术。 快速版本：
- 错误的值从哪里起源？
- 什么调用了这个带有错误值的？
- 继续向上追溯直到找到源头
- 在源头修复，而不是在症状上

第二阶段：模式分析

在修复之前找到模式：

找到工作示例
- 在同一代码库中找到类似的工作代码
- 什么工作的是类似于什么坏了的？
与参考比较
- 如果实现模式，完整阅读参考实现
- 不要略读 - 阅读每一行
- 在应用之前完全理解模式
识别差异
- 工作和破损之间有什么不同？
- 列出每一个差异，无论多小
- 不要假设"那不可能重要"
理解依赖关系
- 这个需要什么其他组件？
- 什么设置，配置，环境？
- 它做了什么假设？

第三阶段：假设和测试

科学方法：

形成一个假设
- 清晰地声明：“我认为X是根本原因，因为Y”
- 写下来
- 具体，不是模糊的
最小测试
- 做最小的可能改变来测试假设
- 一次一个变量
- 不要一次修复多个东西
在继续之前验证
- 它有效了吗？是 → 第四阶段
- 没有工作？形成新的假设
- 不要在顶部添加更多修复
当你不知道时
- 说"我不理解X"
- 不要假装知道
- 寻求帮助
- 进一步研究

第四阶段：实施

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

创建失败的测试用例
- 最简单的可能重现
- 如果可能的话自动化测试
- 如果没有框架，一次性测试脚本
- 在修复之前必须有
- 使用superpowers:test-driven-development技能编写适当的失败测试
实施单一修复
- 解决确定的根本原因
- 一次一个变化
- 没有"当我在这里"的改进
- 没有捆绑重构
验证修复
- 测试现在通过了吗？
- 没有其他测试被破坏？
- 问题真的解决了吗？
如果修复不起作用
- 停止
- 计数：你尝试了多少修复？
- 如果<3：带着新信息返回第一阶段重新分析
- 如果≥3：停止并质疑架构（见下面的第5步）
- 不要在没有架构讨论的情况下尝试修复#4
如果3+修复失败：质疑架构

模式表明架构问题：
- 每个修复都揭示了不同地方的新共享状态/耦合/问题
- 修复需要"大规模重构"来实现
- 每个修复在其他地方创造了新的症状
停止并质疑基础：
- 这个模式在根本上是合理的吗？
- 我们是"通过纯粹的惯性坚持它"吗？
- 我们应该重构架构还是继续修复症状？
在尝试更多修复之前与你的人类伙伴讨论

这不是一个失败的假设 - 这是一个错误的架构。

红旗 - 停止并遵循过程

如果你发现自己在想：

“现在快速修复，以后再调查”
“先尝试改变X，看看它是否有效”
“添加多个更改，运行测试”
“跳过测试，我将手动验证”
“它可能是X，让我修复它”
“我完全不理解，但这可能会有效”
“模式说X，但我将不同地适应它”
“这里是主要问题：[列出没有调查的修复]”
在追踪数据流之前提出解决方案
“再试一次修复”（当已经尝试了2+）
每个修复在不同地方揭示了新问题

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

**如果3+修复失败：**质疑架构（见第4.5阶段）

你的人类伙伴的信号你做错了

注意这些重定向：

“那不是没有发生吗？” - 你假设而没有验证
“它会向我们展示…？” - 你应该添加证据收集
“停止猜测” - 你在没有理解的情况下提出修复
“Ultrathink这个” - 质疑基础，而不仅仅是症状
“我们卡住了？”（沮丧）- 你的方法不起作用

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

常见理由

借口	现实
“问题很简单，不需要过程”	简单的问题也有根本原因。过程对于简单的错误来说更快。
“紧急情况，没有时间进行过程”	系统化调试比猜测和检查更快。
“先试试这个，然后再调查”	第一个修复设置了模式。从一开始就做对。
“确认修复有效后再写测试”	未经测试的修复不会持久。测试首先证明它。
“一次修复多个节省时间”	不能隔离什么有效。会引起新的错误。
“参考太长了，我会适应模式”	部分理解保证错误。完整阅读。
“我看到问题了，让我修复它”	看到症状≠理解根本原因。
“再试一次修复”（2+失败后）	3+失败=架构问题。质疑模式，不要再修复。

快速参考

阶段	关键活动	成功标准
1.根本原因	阅读错误，重现，检查更改，收集证据	理解WHAT和WHY
2.模式	找到工作示例，比较	识别差异
3.假设	形成理论，最小测试	确认或新假设
4.实施	创建测试，修复，验证	错误解决，测试通过

当过程揭示"没有根本原因"

如果系统化调查揭示问题确实是环境的，时序依赖的，或外部的：

你已经完成了这个过程
记录你调查的内容
实施适当的处理（重试，超时，错误消息）
为将来的调查添加监控/日志记录

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

支持技术

这些技术是系统化调试的一部分，并在此目录中提供：

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

相关技能：

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

现实世界的影响

从调试会话中：

系统化方法：15-30分钟修复
随机修复方法：2-3小时的挣扎
第一次修复率：95%对40%
新引入的错误：接近零对常见