系统化调试

概述

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

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

违反本流程的字面规定就是违反调试的精神。

铁律

没有根本原因调查，就不进行修复

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

何时使用

用于任何技术问题：

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

特别在以下情况下使用：

时间紧迫（紧急情况容易让人猜测）
“只需快速修复一下”看似显而易见
你已经尝试了多次修复
之前的修复没有生效
你还没有完全理解问题

不要跳过的情况：

问题看似简单（简单错误也有根本原因）
你很匆忙（匆忙保证返工）
经理要求立即修复（系统化比乱试更快）

四个阶段

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

阶段1：根本原因调查

在尝试任何修复之前：

仔细阅读错误消息
- 不要跳过错误或警告
- 它们通常包含确切的解决方案
- 完整阅读堆栈跟踪
- 注意行号、文件路径、错误代码
稳定复现
- 你能可靠地触发它吗？
- 确切的步骤是什么？
- 每次都会发生吗？
- 如果不能复现 → 收集更多数据，不要猜测
检查最近的更改
- 哪些更改可能导致此问题？
- 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 了解完整的向后追踪技术。

快速版本：
- 错误值从哪里来？
- 什么用错误值调用了这个？
- 继续向上追踪直到找到源头
- 在源头修复，而不是在症状处

阶段2：模式分析

在修复之前找到模式：

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

阶段3：假设与测试

科学方法：

形成单一假设
- 清晰陈述：“我认为X是根本原因，因为Y”
- 写下来
- 具体，不要模糊
最小化测试
- 进行尽可能小的更改来测试假设
- 一次只改变一个变量
- 不要同时修复多个问题
继续前验证
- 有效吗？是 → 阶段4
- 无效？形成新的假设
- 不要在此基础上添加更多修复
当你不确定时
- 说“我不理解X”
- 不要假装知道
- 寻求帮助
- 进一步研究

阶段4：实施

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

创建失败的测试用例
- 最简单的复现方式
- 尽可能自动化测试
- 如果没有框架，用一次性测试脚本
- 修复前必须有
- 使用 superpowers:test-driven-development 技能编写正确的失败测试
实施单一修复
- 解决已识别的根本原因
- 一次只做一个更改
- 没有“顺便改进”
- 没有捆绑重构
验证修复
- 测试现在通过了吗？
- 其他测试没有破坏？
- 问题确实解决了吗？
如果修复无效
- 停止
- 计数：你尝试了多少次修复？
- 如果 < 3：返回阶段1，用新信息重新分析
- 如果 ≥ 3：停止并质疑架构（下面的步骤5）
- 不要在没有架构讨论的情况下尝试第4次修复
如果3次以上修复失败：质疑架构

表明架构问题的模式：
- 每次修复都在不同地方揭示新的共享状态/耦合/问题
- 修复需要“大规模重构”才能实施
- 每次修复都会在其他地方产生新症状
停止并质疑基础：
- 这个模式从根本上合理吗？
- 我们是否“仅仅因为惯性而坚持”？
- 我们应该重构架构还是继续修复症状？
在尝试更多修复之前与你的人类伙伴讨论

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

红旗——停止并遵循流程

如果你发现自己有这样的想法：

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

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

如果3次以上修复失败： 质疑架构（参见阶段4.5）

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

注意这些重定向：

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

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

常见的合理化借口

借口	现实
“问题简单，不需要流程”	简单问题也有根本原因。流程对简单错误也很快。
“紧急情况，没时间走流程”	系统化调试比猜测和乱试更快。
“先试试这个，然后再调查”	第一次修复就设定了模式。从一开始就做对。
“确认修复有效后再写测试”	未经测试的修复不牢靠。先测试证明它。
“一次多个修复节省时间”	无法隔离哪个有效。导致新错误。
“参考太长，我会调整模式”	部分理解保证有错误。完整阅读。
“我看到问题了，让我修复它”	看到症状 ≠ 理解根本原因。
“再试一次修复”（在2次以上失败后）	3次以上失败 = 架构问题。质疑模式，不要再次修复。

快速参考

阶段	关键活动	成功标准
1. 根本原因	阅读错误，复现，检查更改，收集证据	理解是什么和为什么
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% vs 40%
引入新错误：接近零 vs 常见

systematic-debugging

相关 Skills