systematic-debugging

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

系统化调试

概述

随机修复浪费时间还会引入新bug。快速补丁会掩盖根本问题。

核心原则： 在尝试修复前必须找到根本原因。仅修复症状等同于失败。

违反本流程的字面要求就是违背调试的核心精神。

铁律

未先开展根本原因调查，绝不提出修复方案

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

何时使用

适用于所有技术问题：

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

尤其在以下场景必须使用：

• 时间紧迫（紧急情况容易让人想靠猜测解决问题）
• "快速修复一下"看起来很明显
• 你已经尝试过多种修复方案
• 之前的修复没有生效
• 你没有完全理解问题

以下场景也不要跳过：

• 问题看起来很简单（简单的bug也有根本原因）
• 你赶时间（匆忙只会导致返工）
• 经理要求立刻修复（系统化方法比反复试错更快）

四个阶段

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

第一阶段：根本原因调查

在尝试任何修复前：

1. 仔细阅读错误信息

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

2. 稳定复现问题

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

3. 检查最近的变更

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

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

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

   在提出修复方案前，添加诊断埋点：

   对每个组件边界：
     - 记录进入组件的数据
     - 记录离开组件的数据
     - 验证环境/配置传递
     - 检查每一层的状态
   
   运行一次收集证据，明确哪里出了问题
   然后分析证据确定故障组件
   再针对该特定组件展开调查
   

   示例（多层系统）：

   # 第一层：工作流
   echo "=== 工作流中可用的密钥: ==="
   echo "IDENTITY: ${IDENTITY:+已设置}${IDENTITY:-未设置}"
   
   # 第二层：构建脚本
   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点）

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

注意这些提示：

• "不是这样吗？" - 你没验证就做了假设
• "这能告诉我们...吗？" - 你应该先收集证据
• "别猜了" - 你没理解问题就提出修复方案
• "深度思考下" - 重新审视基础，不要只看症状
• "我们卡住了？"（ frustrated） - 你的方法不管用

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

常见借口

借口	现实
"问题很简单，不需要走流程"	简单问题也有根本原因。流程处理简单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：几乎为0 vs 很常见