Chikage0o0/systematic-debugging

Systematic Debugging（系统化调试）

概述

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

核心原则： 必须先找到根因，才能尝试修复。修复症状是失败的。

违反此流程的文字，就是违反调试的精神。

铁律

未调查根因，不得修复

如果你尚未完成第一阶段，则不能提出修复方案。

何时使用

适用于任何技术问题：

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

尤其应在以下情况使用：

• 时间紧迫时（紧急情况下容易让人想猜答案）
• "就一个快速修复"看似显而易见
• 你已经尝试过多种修复
• 之前的修复没有生效
• 你没有完全理解问题

不要跳过的情况：

• 问题看起来简单（简单的 bug 也有根因）
• 你在赶时间（匆忙保证返工）
• 经理要求现在就修好（系统化比胡乱尝试更快）

四个阶段

你必须在进入下一阶段前完成当前阶段。

第一阶段：根因调查

在尝试任何修复之前：

1. 仔细阅读错误信息

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

2. 一致地复现

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

3. 检查近期变更

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

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

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

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

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

   示例（多层系统）：

   # Layer 1: Workflow
   echo "=== Secrets available in workflow: ==="
   echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
   
   # Layer 2: Build script
   echo "=== Env vars in build script: ==="
   env | grep IDENTITY || echo "IDENTITY not in environment"
   
   # Layer 3: Signing script
   echo "=== Keychain state: ==="
   security list-keychains
   security find-identity -v
   
   # Layer 4: Actual signing
   codesign --sign "$IDENTITY" --verbose=4 "$APP"
   

   这揭示了： 哪一层失败（secrets → workflow ✓, workflow → build ✗）

5. 追踪数据流

   当错误位于调用栈深处时：

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

   快速版本：

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

第二阶段：模式分析

在修复之前找到模式：

1. 寻找正常工作的示例

   • 在同一代码库中找到类似的正常工作代码
   • 什么在工作，且与什么出问题的类似？

2. 与参考资料对比

   • 如果正在实现模式，请完整阅读参考实现
   • 不要略读——阅读每一行
   • 在应用之前完全理解模式

3. 识别差异

   • 正常工作的与有问题的之间有什么不同？
   • 列出每一个差异，无论多小
   • 不要假设"那不可能有关系"

4. 理解依赖关系

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

第三阶段：假设与测试

科学方法：

1. 形成单一假设

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

2. 最小化测试

   • 做尽可能小的变更来测试假设
   • 一次只改变一个变量
   • 不要同时修复多个问题

3. 在继续之前验证

   • 它起作用了吗？是 → 第四阶段
   • 没起作用？形成新假设
   • 不要在上面叠加更多修复

4. 当你不知道时

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

第四阶段：实施修复

修复根因，而非症状：

1. 创建失败的测试用例

   • 最简单的复现方式
   • 如果可能，使用自动化测试
   • 如果没有框架，使用一次性测试脚本
   • 修复前必须有
   • 使用 test-driven-development 技能编写适当的失败测试

2. 实施单一修复

   • 解决已识别的根因
   • 一次只做一个变更
   • 不要"顺手"做改进
   • 不要捆绑重构

3. 验证修复

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

4. 如果修复不起作用

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

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

   指示架构问题的模式：

   • 每次修复都暴露出新的共享状态/耦合/不同位置的问题
   • 修复需要"大规模重构"来实现
   • 每次修复都在别处制造新症状

   停止并质疑基本问题：

   • 这个模式从根本上说是否健全？
   • 我们是否"纯粹因为惯性而坚持它"？
   • 我们应该重构架构还是继续修复症状？

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

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

危险信号——停止并遵循流程

如果你发现自己这样想：

• "先快速修复，以后再调查"
• "试试改 X，看看有没有用"
• "加多个改动，跑测试"
• "跳过测试，我来手动验证"
• "可能是 X，让我修一下"
• "我没完全理解，但这可能有用"
• "模式说 X，但我会按不同方式调整"
• "主要问题是这些：[在未调查的情况下列出修复]"
• 在追踪数据流之前提出解决方案
• "再试一次修复"（当已经尝试了 2+ 次）
• 每次修复都在不同位置暴露新问题

以上所有都意味着：停止。回到第一阶段。

如果 3+ 次修复失败： 质疑架构（见第四阶段第 5 步）

你的 human partner 发出的错误信号

注意这些引导：

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

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

常见合理化借口

| 借口 | 现实 | |------|------| | "问题很简单，不需要流程" | 简单问题也有根因。流程对简单 bug 来说也很快。 | | "紧急情况，没时间走流程" | 系统化调试比猜测试错快。 | | "先试试这个，然后再调查" | 第一次修复就定下了模式。从一开始就做对。 | | "我确认修复有效后再写测试" | 未测试的修复不持久。先测试才能证明。 | | "同时修复多个问题节省时间" | 无法隔离什么起了作用。会制造新 bug。 | | "参考资料太长，我会调整模式" | 部分理解保证出 bug。完整阅读。 | | "我看到问题了，让我修复它" | 看到症状 ≠ 理解根因。 | | "再试一次修复"（在 2+ 次失败后） | 3+ 次失败 = 架构问题。质疑模式，不要再次修复。 |

快速参考

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

当流程显示"无根因"

如果系统调查揭示问题确实是环境性的、时间依赖性的或外部性的：

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

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

支持技术

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

• root-cause-tracing.md —— 反向追踪调用栈以找到原始触发点
• defense-in-depth.md —— 找到根因后在多层添加验证
• condition-based-waiting.md —— 用条件轮询替换任意超时

相关技能：

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

实际影响

来自调试会话的数据：

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