Systematic Debugging

系统化调试

概述

随手修补会浪费时间，还会引入新 bug。快速打补丁只会掩盖底层问题。

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

Violating the letter of this process is violating the spirit of debugging.

铁律

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

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

何时使用

适用于任何技术问题：

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

尤其在以下情况要用：

• 有时间压力时（紧急情况最容易让人想猜）
• “就改一个小修复” 看起来特别明显时
• 你已经试过多个修复
• 上一次修复没起作用
• 你还没有完全理解问题

不要跳过的情况：

• 问题看起来很简单时（简单 bug 也有根因）
• 你很赶时（着急只会带来返工）
• 经理要求立刻修好时（系统化方法比乱试更快）

四个阶段

你必须先完成当前阶段，才能进入下一阶段。

第 1 阶段：根因调查

在尝试任何修复之前：

1. 仔细阅读错误信息

   • 不要跳过错误或警告
   • 它们往往已经包含准确答案
   • 把堆栈信息完整读完
   • 记下行号、文件路径和错误码

2. 稳定复现

   • 能否稳定触发？
   • 具体步骤是什么？
   • 每次都会发生吗？
   • 如果不能稳定复现 -> 继续收集数据，不要猜

3. 检查最近变更

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

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

   当系统包含多个组件时（CI -> build -> signing，API -> service -> database）：

   在提出修复之前，先加诊断埋点：

   For EACH component boundary:
     - Log what data enters component
     - Log what data exits component
     - Verify environment/config propagation
     - Check state at each layer
   
   Run once to gather evidence showing WHERE it breaks
   THEN analyze evidence to identify failing component
   THEN investigate that specific component
   

   Example (multi-layer system):

   # 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. 追踪数据流

   当错误出现在很深的调用栈里时：

   See root-cause-tracing.md in this directory for the complete backward tracing technique.

   简版：

   • 错误值最初来自哪里？
   • 是谁用这个错误值调用了它？
   • 一直往上追，直到找到源头
   • 修源头，不修症状

第 2 阶段：模式分析

先找模式，再修复：

1. 找能工作的例子

   • 在同一代码库里找相似且正常工作的代码
   • 哪些地方和坏掉的代码相似，但能正常运行？

2. 对照参考实现

   • 如果是在套用某个模式，要把参考实现完整读完
   • 不要扫读，要逐行看
   • 应用之前先彻底理解这个模式

3. 识别差异

   • 正常和异常之间有什么不同？
   • 把每一个差异都列出来，哪怕很小
   • 不要想当然地认为“这个不重要”

4. 理解依赖

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

第 3 阶段：假设与测试

科学方法：

1. 提出单一假设

   • 清楚地说出来：“我认为 X 是根因，因为 Y”
   • 写下来
   • 要具体，不要模糊

2. 最小化测试

   • 用尽可能小的改动验证假设
   • 一次只改一个变量
   • 不要一次修好多个问题

3. 继续前先验证

   • 生效了吗？是 -> 进入第 4 阶段
   • 没生效？重新提出新的假设
   • 不要在上面继续叠加更多修复

4. 不知道时

   • 直接说 “我不理解 X”
   • 不要假装自己懂
   • 该求助就求助
   • 继续研究

第 4 阶段：实现

修根因，不修症状：

1. 先创建能稳定复现问题的验证手段

   • 用最简单的方式复现
   • 如果可以，写自动化测试
   • 如果没有框架，就写一次性测试脚本
   • 修复之前必须先有它

2. Implement Single Fix

   • Address the root cause identified
   • ONE change at a time
   • No "while I'm here" improvements
   • No bundled refactoring

3. Verify Fix

   • Test passes now?
   • No other tests broken?
   • Issue actually resolved?

4. If Fix Doesn't Work

   • STOP
   • Count: How many fixes have you tried?
   • If < 3: Return to Phase 1, re-analyze with new information
   • If ≥ 3: STOP and question the architecture (step 5 below)
   • DON'T attempt Fix #4 without architectural discussion

5. If 3+ Fixes Failed: Question Architecture

   Pattern indicating architectural problem:

   • Each fix reveals new shared state/coupling/problem in different place
   • Fixes require "massive refactoring" to implement
   • Each fix creates new symptoms elsewhere

   STOP and question fundamentals:

   • Is this pattern fundamentally sound?
   • Are we "sticking with it through sheer inertia"?
   • Should we refactor architecture vs. continue fixing symptoms?

   Discuss with your human partner before attempting more fixes

   This is NOT a failed hypothesis - this is a wrong architecture.

Red Flags - STOP and Follow Process

如果你发现自己在想下面这些话：

• “先随便修一下，回头再调查”
• “先改 X 看看能不能好”
• “多改几处，一起跑测试”
• “测试先不写，我手工验证就行”
• “大概是 X，我先修它”
• “我没完全理解，但这也许能行”
• “模式说要 X，但我换个方式适配一下”
• “主要问题是这些：[没调查就列一堆修复]”
• 在追踪数据流之前就开始提方案
• “再试一次修复”（已经试过 2 次以上时）
• 每次修复都会在别的地方冒出新问题

以上任何一种情况都意味着：立刻停止，回到第 1 阶段。

如果已经失败了 3 次以上： 就要质疑架构（见第 4.5 步）

你的协作对象发出的“你走偏了”信号

留意这些纠偏：

• “不是没发生吗？” - 你在没验证的情况下做了假设
• “它会不会显示出……？” - 你本该先加证据收集
• “别猜了” - 你在没理解前就开始提修复
• “把这个问题想深一点” - 该质疑的是基本原理，不只是症状
• “我们卡住了？”（带着挫败感）- 你的方法没有奏效

一旦听到这些信号： 立刻停止，回到第 1 阶段。

常见合理化

快速参考

当流程显示“没有根因”时

如果系统化调查后发现，这个问题确实是环境相关、时序相关，或者来自外部：

1. 说明你已经完成了流程
2. 记录你调查过什么
3. 加入合适的处理方式（重试、超时、错误提示）
4. 为后续调查加上监控/日志

但是： 95% 的“没有根因”案例，其实都是调查还不完整。

配套技巧

下面这些技巧是系统化调试的一部分，也都在这个目录里：

• root-cause-tracing.md - Trace bugs backward through call stack to find original trigger
• defense-in-depth.md - Add validation at multiple layers after finding root cause
• condition-based-waiting.md - Replace arbitrary timeouts with condition polling

相关 skills：

• superpowers:verification-before-completion - Verify fix worked before claiming success

实际影响

来自调试实战：

• 系统化方法：15-30 分钟修好
• 随机修法：2-3 小时反复折腾
• 首次修复成功率：95% 对 40%
• 引入新 bug 的数量：几乎为零，对比常见