systematic-debugging

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

系统化调试

概述

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

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

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

铁律

没有根因调查就不能提出修复方案

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

何时使用

用于任何技术问题：

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

特别适用于以下情况：

• 时间紧迫时（紧急情况让人想猜测）
• "只需一个快速修复"看似显而易见时
• 你已经尝试了多次修复时
• 之前的修复不起作用时
• 你没有完全理解问题时

不要跳过的理由：

• 问题看似简单（简单的 bug 也有根因）
• 你很赶时间（匆忙意味着返工）
• 经理要求立刻修复（系统化比乱撞更快）

四个阶段

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

第一阶段：根因调查

在尝试任何修复之前：

1. 仔细阅读错误信息

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

2. 稳定复现

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

3. 检查近期变更

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

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

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

   在提出修复方案之前，先添加诊断工具：

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

   示例（多层系统）：

   # 第一层：工作流
   echo "=== 工作流中可用的密钥： ==="
   echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
   
   # 第二层：构建脚本
   echo "=== 构建脚本中的环境变量： ==="
   env | grep IDENTITY || echo "IDENTITY 不在环境中"
   
   # 第三层：签名脚本
   echo "=== 钥匙串状态： ==="
   security list-keychains
   security find-identity -v
   
   # 第四层：实际签名
   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步）

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

注意这些重定向：

• "那个没有发生吗？" - 你没有验证就假设了
• "它会显示给我们……？" - 你应该已经添加了证据收集
• "别猜了" - 你在没有理解的情况下提出修复方案
• "深度思考这个" - 质疑根本问题，不只是症状
• "我们卡住了？"（沮丧地）- 你的方法不起作用

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

常见自我合理化

借口	现实
"问题很简单，不需要流程"	简单问题也有根因。流程对简单 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 - 用条件轮询替代任意超时

相关技能：

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

现实世界影响

来自调试会话：

• 系统化方法：15-30 分钟修复
• 随机修复方法：2-3 小时乱撞
• 首次修复成功率：95% vs 40%
• 引入的新 bug：接近零 vs 常见