systematic-debugging

name	systematic-debugging
description	当遇到任何 bug、测试失败或意外行为时使用，在提出修复方案之前

Systematic Debugging / 系统化调试

概览

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

核心原则： 在尝试任何修复之前，必须找到根因。只修症状就是失败。

违反此流程的字面意义，就是违反调试的精神。

铁律

没有先进行根因调查，就不做任何修复

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

何时使用

用于任何技术问题：

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

尤其在这些情况下使用：

• 在时间压力下（紧急情况让猜测显得诱人）
• "就一个小修复"看起来很明显
• 你已经尝试了多次修复
• 上一次修复没生效
• 你并没有完全理解这个问题

不要在这些情况下跳过：

• 问题看起来简单（简单的 bug 也有根因）
• 你很赶时间（赶工必然导致返工）
• 经理要求现在就修好（系统化比瞎折腾更快）

四个阶段

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

阶段 1：根因调查

在尝试任何修复之前：

1. 仔细阅读错误信息

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

2. 稳定复现

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

3. 检查最近变更

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

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

   当系统有多个组件时（CI → build → signing，API → service → database）：

   在提出修复之前，添加诊断插桩：

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

   示例（多层系统）：

   # 第 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 ✗）

5. 追踪数据流

   当错误深在调用栈中时：

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

   快速版本：

   • 错误值源自哪里？
   • 是什么用错误值调用了它？
   • 持续向上追踪直到找到源头
   • 在源头修复，而不是在症状处

阶段 2：模式分析

在修复之前先找到模式：

1. 找到可用的示例

   • 在同一个代码库中定位相似的可用代码
   • 有什么与坏掉的相似的东西是可用的？

2. 与参考对比

   • 如果在实现某个模式，完整地阅读参考实现
   • 不要略读——逐行阅读
   • 在应用之前充分理解该模式

3. 识别差异

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

4. 理解依赖

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

阶段 3：假设与测试

科学方法：

1. 形成单一假设

   • 清晰地陈述："我认为 X 是根因，因为 Y"
   • 写下来
   • 要具体，不要含糊

2. 最小化测试

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

3. 在继续之前验证

   • 生效了？是 → 阶段 4
   • 没生效？形成新的假设
   • 不要在上面叠加更多修复

4. 当你不知道时

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

阶段 4：实现

修复根因，而不是症状：

1. 创建失败的测试用例

   • 最简单的可能复现
   • 尽可能用自动化测试
   • 没有框架时用一次性测试脚本
   • 修复前必须有
   • 使用 superpowers:test-driven-development skill 来编写规范的失败测试

2. 实现单一修复

   • 针对已识别的根因
   • 一次一个改动
   • 没有"顺手"的改进
   • 不打包重构

3. 验证修复

   • 测试现在通过了？
   • 没有破坏其他测试？
   • 问题确实解决了？

4. 如果修复没生效

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

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

   指示架构问题的模式：

   • 每次修复都揭示新的共享状态/耦合/在不同地方的问题
   • 修复需要"大规模重构"才能实现
   • 每次修复都在别处制造新的症状

   停下并质疑根本：

   • 这个模式从根本上合理吗？
   • 我们是不是"纯粹出于惯性在硬撑"？
   • 我们应该重构架构，还是继续修症状？

   在尝试更多修复之前与你的 human partner 讨论

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

危险信号（Red Flags）- 停下并遵循流程

如果你发现自己在想：

• "先临时修一下，以后再调查"
• "就试着改一下 X 看看能不能用"
• "加多个改动，跑测试"
• "跳过测试，我手动验证"
• "大概是 X，让我修一下"
• "我没有完全理解，但这可能有效"
• "模式说 X，但我用另一种方式适配"
• "主要问题是这些：[没调查就列出修复方案]"
• 在追踪数据流之前就提出解决方案
• "再试一次修复"（当已经尝试 2 次以上时）
• 每次修复都在不同地方揭示新问题

以上全部意味着：停下。回到阶段 1。

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

你的 human partner 示意你做错了

注意这些纠正：

• "那没发生吗？" - 你假设了却没有验证
• "它会向我们展示……吗？" - 你本应该添加证据收集
• "别猜了" - 你在不理解的情况下提出修复
• "深度思考一下" - 质疑根本，而不只是症状
• "我们卡住了？"（沮丧地）- 你的方法不奏效

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

常见合理化借口

借口	现实
"问题很简单，不需要流程"	简单问题也有根因。流程对简单 bug 很快。
"紧急情况，没时间走流程"	系统化调试比猜-检查-瞎折腾更快。
"先试这个，再调查"	第一次修复设定了模式。从一开始就做对。
"我先确认修复有效，再写测试"	未测试的修复留不住。测试先行才能证明它。
"一次多个修复节省时间"	无法隔离哪个生效。制造新的 bug。
"参考太长了，我适配一下模式"	部分理解必然导致 bug。完整地阅读它。
"我看到问题了，让我修一下"	看到症状 ≠ 理解根因。
"再试一次修复"（失败 2 次以上后）	3 次以上失败 = 架构问题。质疑模式，不要再修。

快速参考

阶段	关键活动	成功标准
1. 根因	阅读错误、复现、检查变更、收集证据	理解是什么和为什么
2. 模式	找到可用示例、对比	识别差异
3. 假设	形成理论、最小化测试	假设确认或新假设
4. 实现	创建测试、修复、验证	Bug 解决、测试通过

当流程揭示"没有根因"时

如果系统化调查揭示问题确实是环境性的、时序相关的或外部的：

1. 你已完成流程
2. 记录你调查了什么
3. 实现适当的处理（重试、超时、错误信息）
4. 添加监控/日志以供未来调查

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

辅助技术

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

• root-cause-tracing.md - 通过调用栈反向追踪 bug，找到原始触发点
• defense-in-depth.md - 在找到根因后在多个层添加校验
• condition-based-waiting.md - 用条件轮询替代随意超时

相关 skills：

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

真实世界的影响

来自调试会话：

• 系统化方法：15-30 分钟修复
• 随机修复方法：2-3 小时瞎折腾
• 一次修复成功率：95% vs 40%
• 引入的新 bug：几乎为零 vs 常见