系统化调试
概述
随意修复既浪费时间又会引入新 bug。草率的补丁只会掩盖深层问题。
核心原则： 在尝试修复之前，务必先找到根本原因。只修症状就是失败。
敷衍走流程等于违背调试的精神。
铁律
不做根因调查，不许提修复方案如果你还没完成第一阶段，就不能提出修复方案。
何时使用
用于任何技术问题：
- 测试失败
- 生产环境 bug
- 异常行为
- 性能问题
- 构建失败
- 集成问题
尤其在以下情况必须使用：
- 时间紧迫（紧急情况最容易让人猜测式修复）
- 觉得"一个小修改"就能搞定
- 已经尝试了多种修复
- 上一次修复没有生效
- 你没有完全理解问题
以下情况也不要跳过：
- 问题看起来很简单（简单的 bug 也有根本原因）
- 你很赶时间（越急越容易返工）
- 领导要求立刻修好（系统化调试比反复尝试更快）
四个阶段
你必须完成每个阶段后才能进入下一个。
第一阶段：根因调查
在尝试任何修复之前：
- 仔细阅读错误信息
- 不要跳过错误或警告 - 它们往往直接包含解决方案 - 完整阅读堆栈跟踪 - 记下行号、文件路径、错误码
- 稳定复现
- 你能可靠地触发它吗？ - 具体的复现步骤是什么？ - 每次都能复现吗？ - 如果无法复现 → 收集更多数据，不要猜测
- 检查近期变更
- 什么变更可能导致了这个问题？ - git diff、最近的提交 - 新依赖、配置变更 - 环境差异
- 在多组件系统中收集证据 当系统有多个组件时（CI → 构建 → 签名，API → 服务 → 数据库）： 在提出修复方案之前，先添加诊断埋点：
对每个组件边界： - 记录进入组件的数据 - 记录离开组件的数据 - 验证环境/配置的传递 - 检查每一层的状态 执行一次以收集证据，确定断裂点在哪里 然后分析证据，定位故障组件 然后针对该组件深入调查示例（多层系统）：# 第 1 层：工作流 echo "=== Secrets available in workflow: ===" echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}" # 第 2 层：构建脚本 echo "=== Env vars in build script: ===" env | grep IDENTITY || echo "IDENTITY not in environment" # 第 3 层：签名脚本 echo "=== Keychain state: ===" security list-keychains security find-identity -v # 第 4 层：实际签名 codesign --sign "$IDENTITY" --verbose=4 "$APP"由此可以看出： 哪一层出了问题（secrets → workflow ✓, workflow → build ✗） - 跟踪数据流 当错误发生在调用栈深处时： 参见本目录下的
root-cause-tracing.md，了解完整的反向追踪技术。 简要版本：
- 错误值从哪里产生的？ - 谁用错误值调用了这里？ - 持续向上追踪直到找到源头 - 在源头修复，而不是在症状处修复
第二阶段：模式分析
先找到模式，再修复：
- 找到可正常工作的示例
- 在同一代码库中找到类似的正常代码 - 有什么正常的代码与出问题的代码相似？
- 与参考实现对比
- 如果是实现某个模式，完整阅读参考实现 - 不要略读——逐行阅读 - 在应用之前彻底理解该模式
- 识别差异
- 正常代码和出问题的代码之间有什么不同？ - 列出每一个差异，无论多小 - 不要假设"那不可能有影响"
- 理解依赖关系
- 这个功能需要哪些其他组件？ - 需要哪些设置、配置、环境？ - 它有哪些隐含假设？
第三阶段：假设与验证
科学方法：
- 提出单一假设
- 清晰地陈述："我认为 X 是根本原因，因为 Y" - 写下来 - 要具体，不要含糊
- 最小化测试
- 做出最小的改动来验证假设 - 每次只改一个变量 - 不要同时修复多个问题
- 继续之前先验证
- 生效了？是 → 进入第四阶段 - 没生效？提出新假设 - 不要在上面叠加更多修复
- 当你不确定时
- 说"我不理解 X" - 不要假装自己知道 - 寻求帮助 - 做更多调研
第四阶段：实施
修复根本原因，而非症状：
- 创建失败的测试用例
- 最简化的复现 - 尽可能用自动化测试 - 没有测试框架就写一次性测试脚本 - 修复前必须先有测试 - 使用 superpowers:test-driven-development 技能来编写规范的失败测试
- 实施单一修复
- 修复已定位的根本原因 - 每次只改一处 - 不做"顺便改改"的优化 - 不捆绑重构
- 验证修复
- 测试现在通过了吗？ - 其他测试没有被破坏吧？ - 问题真的解决了吗？
- 如果修复不起作用
- 停下来 - 数一数：你已经尝试了几次修复？ - 少于 3 次：回到第一阶段，用新信息重新分析 - 3 次或以上：停下来质疑架构（见下方第 5 步） - 没有经过架构讨论，不要尝试第 4 次修复
- 如果 3 次以上修复都失败了：质疑架构 以下模式表明存在架构问题： 停下来质疑根本性问题： 在尝试更多修复之前，和你的搭档讨论 这不是假设失败——这是架构有误。
- 每次修复都暴露出新的共享状态/耦合/其他位置的问题 - 修复需要"大规模重构"才能实现 - 每次修复都在其他地方产生新的症状 - 这个模式从根本上合理吗？ - 我们是不是在"惯性驱动"下坚持了错误方案？ - 应该重构架构还是继续修补症状？
红线——停下来，按流程走
如果你发现自己在想：
- "先临时修一下，以后再排查"
- "试着改改 X 看看行不行"
- "一次性改多个地方，跑测试看看"
- "跳过测试，我手动验证"
- "大概是 X 的问题，让我修一下"
- "我不完全理解，但这应该能行"
- "模式说的是 X，但我换个方式用"
- "主要问题有这些：[未经调查就列出修复方案]"
- 没有追踪数据流就提出解决方案
- "再试一次修复"（已经尝试了 2 次以上）
- 每次修复都暴露出不同地方的新问题
以上这些都意味着：停下来。回到第一阶段。
如果 3 次以上修复都失败了： 质疑架构（见第四阶段第 5 步）
搭档发出的信号——说明你的方法不对
留意这些提醒：
- "难道不是这样吗？"——你在没有验证的情况下做了假设
- "它能告诉我们……吗？"——你应该先收集证据
- "别猜了"——你在没有理解的情况下提出修复
- "深入想想"——要质疑根本性问题，而不只是症状
- "我们卡住了？"（沮丧的语气）——你的方法没有奏效
当你看到这些信号时： 停下来。回到第一阶段。
常见借口
| 借口 | 现实 |
|---|---|
| "问题很简单，不需要走流程" | 简单问题也有根本原因。对于简单 bug，流程很快就能走完。 |
| "紧急情况，没时间走流程" | 系统化调试比反复猜测式修复更快。 |
| "先试一下，再排查" | 第一次修复就定下了基调。从一开始就做对。 |
| "确认修复有效后再写测试" | 没有测试的修复留不住。先写测试才能证明修复有效。 |
| "一次修多个问题省时间" | 无法隔离哪个生效了。还会引入新 bug。 |
| "参考实现太长了，我自己改改" | 一知半解必然出 bug。完整阅读。 |
| "我看出问题了，让我修一下" | 看到症状 ≠ 理解根因。 |
| "再试一次"（在 2 次以上失败后） | 3 次以上失败 = 架构问题。质疑模式，不要继续修。 |
速查表
| 阶段 | 关键活动 | 通过标准 |
|---|---|---|
| 1. 根因 | 阅读错误、复现、检查变更、收集证据 | 理解了什么出了问题以及为什么 |
| 2. 模式 | 找到正常示例、对比 | 识别出差异 |
| 3. 假设 | 提出理论、最小化验证 | 假设被验证或产生新假设 |
| 4. 实施 | 创建测试、修复、验证 | bug 已修复，测试通过 |
当流程显示"找不到根因"
如果系统化排查后发现问题确实是环境相关、时序相关或外部因素导致的：
- 你已经完成了流程
- 记录你排查了什么
- 实施适当的处理措施（重试、超时、错误提示）
- 添加监控/日志以便后续排查
但是： 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 经常发生