systematic-debugging

系统化调试

概述

随机的修复既浪费时间，又会制造新的 bug。快速打补丁只会掩盖底层问题。

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

违反这一流程的字面要求，就是违反调试的精神。

铁律

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
   

   示例（多层系统）：

   # 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，了解完整的反向追踪技术。

   快速版本：

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

阶段 2：模式分析

在修复之前先找到模式：

1. 寻找可用的示例

   • 在同一代码库中找到类似的可运行代码
   • 哪些可运行的东西与出问题的东西相似？

2. 与参考实现对比

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

3. 找出差异

   • 可运行的和出问题的之间有什么不同？
   • 列出每一处差异，无论多小
   • 不要假设“那不可能有影响”

4. 理解依赖关系

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

阶段 3：假设与验证

科学方法：

1. 提出单一假设

   • 清楚陈述：“我认为 X 是根本原因，因为 Y”
   • 写下来
   • 要具体，不要含糊

2. 最小化验证

   • 做出尽可能小的变更来验证假设
   • 一次只改变一个变量
   • 不要同时修复多个东西

3. 在继续之前进行验证

   • 奏效了吗？是 → 阶段 4
   • 没奏效？提出新的假设
   • 不要在原有基础上叠加更多修复

4. 当你不知道时

   • 说“我不理解 X”
   • 不要假装知道
   • 寻求帮助
   • 进一步研究

阶段 4：实现

修复根本原因，而非表面症状：

1. 创建失败的测试用例

   • 尽可能简单地复现问题
   • 尽可能编写自动化测试
   • 如果没有测试框架，则编写一次性测试脚本
   • 修复前必须先创建测试
   • 使用 superpowers:test-driven-development 技能编写规范的失败测试

2. 实施单一修复

   • 解决已确定的根本原因
   • 一次只做一项更改
   • 不要顺手改进其他内容
   • 不要捆绑重构

3. 验证修复

   • 测试现在是否通过？
   • 是否有其他测试失败？
   • 问题是否确实解决？

4. 如果修复无效

   • 停止
   • 统计：你已经尝试了多少次修复？
   • 如果少于 3 次：返回阶段 1，结合新信息重新分析
   • 如果 ≥ 3 次：停止并质疑架构（见下方第 5 步）
   • 未经架构讨论，不要尝试第 4 次修复

5. 如果 3 次或更多修复均失败：质疑架构

   表明存在架构问题的模式：

   • 每次修复都会在不同位置暴露新的共享状态、耦合或问题
   • 修复需要“大规模重构”才能实施
   • 每次修复都会在其他地方引发新症状

   停止并质疑根本问题：

   • 这种模式从根本上是否合理？
   • 我们是否只是在“惯性驱使下勉强坚持”？
   • 应该重构架构，还是继续修复症状？

   尝试更多修复之前，先与你的人工搭档讨论

   这不是假设验证失败，而是架构有误。

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

如果你发现自己在想：

• “先快速修一下，之后再调查”
• “改一下 X 试试，看能不能解决”
• “一次加好几项更改，然后运行测试”
• “跳过测试，我手动验证就行”
• “问题可能出在 X，我来修一下”
• “我还没完全理解，但这样也许能行”
• “模式建议用 X，但我会换种方式处理”
• “主要问题如下：[未调查就列出修复方案]”
• 尚未追踪数据流就提出解决方案
• “再试一次修复”（已经尝试过 2 次或更多时）
• 每次修复都会在不同位置暴露新问题

出现以上任何情况，都意味着：停止。返回阶段 1。

**如果 3 次或更多修复均失败：**质疑架构（参见阶段 4.5）

你的人工搭档指出你做错了时的信号

留意这些纠正：

• “这不是正在发生的情况吗？”——你未经验证就做出了假设
• “这样能让我们看到……吗？”——你本应补充证据收集
• “别猜了”——你还没弄清楚问题，就在提出修复方案
• “深入思考”——应质疑根本问题，而不只是处理症状
• “我们卡住了吗？”（沮丧地说）——你的方法不起作用

**看到这些信号时：**停止。返回阶段 1。

常见自我辩解

借口	事实
“问题很简单，不需要流程”	简单问题也有根本原因。流程能让简单问题更快解决。
“情况紧急，没时间走流程”	系统化调试比猜测和反复试错更快。
“先试试这个，再调查”	第一次修复会定下处理模式。从一开始就做好。
“确认修复有效后再写测试”	未经测试的修复无法保证可靠。先写测试才能证明修复有效。
“一次修好几处能节省时间”	无法确定哪项更改起了作用，还可能引入新缺陷。
“参考内容太长，我会灵活套用”	理解不完整必然导致缺陷。请完整阅读。
“我看出问题了，让我来修”	看到症状 ≠ 理解根本原因。
“再试一次修复”（失败 2 次或更多后）	失败 3 次或更多意味着存在架构问题。应质疑处理模式，不要继续修复。

常见陷阱

这些是在调试实践中观察到的反模式。发现后应立即识别并调整方向。相关指导另见：危险信号和常见自我辩解。

1. 未复现问题就着手解决（过早修复）

反模式：

Error log shows "timeout" → assume network issue → add retry logic
(But you never actually reproduced the timeout)

问题：

• 修复针对的是尚未验证的症状
• 真正的问题仍未解决，只是被“修复”掩盖了
• 症状再次出现时，你会浪费时间调试自己的补丁

如何避免：

• 第 1 阶段要求： 能否通过已知步骤稳定触发该错误？
• 记录确切的复现步骤：“将 X 设置为 Y 后运行 npm test” → 错误发生
• 如果无法复现，就无法验证修复是否有效
• 必须确保可复现——继续收集数据，直到能够触发问题

恢复：

• 停下来，回到第 1 阶段。
• 找到确切的复现步骤。
• 然后再进入第 2 阶段。

---

2. 一次改动多项内容（无法隔离根本原因）

反模式：

Change 3 things:
  - Update dependency version
  - Refactor retry logic
  - Add fallback handler
Run tests → passes

问题：

• 哪项改动修复了问题？无法确定。
• 如果某项改动引入了细微错误，你可能几个月都发现不了
• 以后这段代码路径再出现错误时，排查会更加困难

如何避免：

• 第 3 阶段要求：“尽量少测。只做尽可能小的改动。”
• 一次只改一个变量
• 每次改动后都进行测试
• 如果无法确定是哪项改动修复了问题，就说明你对修复的了解还不完整

恢复：

• 撤销所有改动，重新开始。
• 只改一项，然后测试。
• 记录：“仅此改动就修复了问题，因为 [原因]”
• 对下一个假设重复上述步骤。

---

3. 假定错误由近期改动引起（忽略环境或数据）

反模式：

Feature shipped 3 days ago → bug happened today → bug must be in that feature
(But you didn't verify the feature code against current data/environment)

问题：

• 近期代码看起来可疑，但环境变化很难察觉
• 你可能花好几天调试实际上没有问题的代码
• 真正的原因可能是数据损坏、环境配置错误或依赖更新

如何避免：

• 第 1 阶段要求：“检查近期改动”包括：
  • 代码中的 Git 差异？是。
  • 依赖更新？是。
  • 环境变化？是。
  • 数据迁移？是。
  • 配置变更？是。
• 测试假设：撤销近期的代码改动，看看错误是否仍然存在
• 如果撤销近期改动后问题仍然发生，原因就在环境中
• 对于多组件系统，使用诊断埋点（参见第 1 阶段步骤 4）

恢复：

• 列出过去一周的所有改动：代码、依赖、配置、环境和数据
• 系统地排除环境或数据方面的原因
• 只有完成这一步后，才着重检查代码

---

4. 未记录复现步骤（无法验证修复）

反模式：

"Fixed the bug" (but didn't write down how to trigger it)
Weeks later: "Wait, does this still happen? I don't remember how to trigger it"

问题：

• 你无法验证修复是否真的有效
• 你无法告诉同事如何测试
• 你无法发现回归问题

如何避免：

• 第 1 阶段要求：“稳定复现”
  • 写下确切步骤
  • 格式：“复现步骤：[步骤 1]、[步骤 2]、[步骤 3]”
• 进入第 2 阶段前，将这些步骤作为注释添加到 PR/问题中
• 实施修复后，重新运行确切步骤进行验证
• 将复现步骤转化为测试用例（第 4 阶段，步骤 1）

恢复：

• 现在就记录复现步骤
• 重新运行确切步骤之前，不要声称修复已完成
• 如果已记录复现步骤，并且修复后再也无法触发错误，就能确认修复有效

---

5. 没有日志或可观测性就进行调试（盲目排查）

反模式：

Error happens in production
You: "Probably a race condition?"
You don't have logs showing what was happening at that moment
You guess at fixes for 3 hours

问题：

• 你在没有证据的情况下做决定
• 猜测修复方案会引入新的错误
• 由于从未弄清原因，相同的错误还会再次发生

如何避免：

• 第 1 阶段要求：“在多组件系统中收集证据”
• 开始调试前，先问：“我们有哪些日志？”
• 如果没有：添加临时日志，并在本地复现问题
• 没有证据说明实际发生了什么，就不要提出修复方案
• 对于生产环境问题：捕获故障发生时的日志和指标

具体策略：

# Reproduce with logging
DEBUG=* npm test           # Enable all logs
strace node app.js         # System call tracing
tcpdump -i any -w dump     # Network tracing

恢复：

• 暂停，针对关键决策点添加日志。
• 使用增强后的日志复现问题。
• 现在你有了形成假设所需的证据。
• 然后再提出修复方案。

---

6. 未先编写失败的测试用例（验证表演）

反模式：

Implement fix
Run manual test: "Looks good"
Commit and push
(No automated test proving bug existed)

问题：

• 你“修复”了某个问题，却从未证明它确实存在
• 后续回归测试发现，Bug 仍然存在
• 你无法区分“我修好了”和“我只是碰巧蒙对了”

如何避免：

• 阶段 4 要求：“创建失败的测试用例”
  • 测试在修复前必须失败
  • 测试在修复后必须通过
  • 测试证明 Bug 确实存在，且修复消除了 Bug
• 不要在没有失败测试的情况下实现修复
• 自动化测试（单元测试、集成测试、一次性脚本）优于手动验证

补救措施：

• 撤销修复
• 编写能够复现 Bug 的测试
• 确认测试失败
• 实现修复
• 确认测试通过

---

7. 未隔离出故障组件（归咎于一切）

反模式：

Database slow? Maybe it's the query. Maybe it's the network. Maybe it's CPU.
Let me add caching, fix indexes, reduce batch size, and upgrade servers.

问题：

• 你浪费资源去修复并未损坏的部分
• 你始终无法弄清真正的瓶颈所在
• 由于不确定该优化什么，后续的优化尝试也会失败

如何避免：

• 阶段 1 要求：“在多组件系统中收集证据”
  • 在每个组件边界记录输入和输出的数据
  • 确定哪个组件速度慢或发生故障
  • 将调查重点放在该组件上
  • 不要优化 5 个地方，要优化瓶颈

示例：

# API slow. Which part?
time curl /api/endpoint              # Total time
# Add logging to API entry point
# Add logging before DB query
# Add logging after DB returns
# Add logging before response

# Now you know: API fast (10ms), DB query slow (2s) → focus on DB

补救措施：

• 使用诊断工具找出实际发生故障的组件
• 在隔离出具体组件之前，不要提出修复方案

---

8. 假定修复已完成（遗漏边缘情况）

反模式：

Test case passes for happy path
Deploy without testing error cases
(Bug appears 2 weeks later under edge condition you didn't think to test)

问题：

• 修复解决了一种情况，却导致其他情况出错
• 80% 的 Bug 都藏在边缘情况下

如何避免：

• 阶段 4 要求：“验证修复”
  • 测试成功情况
  • 测试错误情况
  • 测试边界条件
  • 使用无效、空值或极端数据进行测试
  • 测试与其他组件的交互
• 部署前全面覆盖测试
• 为每个已修复的 Bug 编写回归测试

补救措施：

• 添加边缘情况测试
• 重新运行完整测试套件
• 所有情况都通过之前，不要宣布修复完成

---

这些陷阱是反复出现的模式，而非偶发的失误。发现自己陷入其中时，请停下来，重新遵循流程。

快速参考

阶段	关键活动	成功标准
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 - 用于创建失败的测试用例（阶段 4，第 1 步）
• superpowers:verification-before-completion - 在宣称成功前验证修复是否有效

实际效果

来自调试会话的数据：

• 系统性方法：15-30 分钟即可修复
• 随机修复方法：耗费 2-3 小时反复折腾
• 首次修复成功率：95%，而随机修复为 40%
• 引入新 Bug：几乎为零，而随机修复则很常见