根因调试

定义

根因调试是一种强调“先找根因，再谈修复”的调试方法。它反对常见的猜测式调试：看到报错后立刻让 AI 或工程师尝试改这里、改那里，失败了再换一个猜测继续试。

铁律：NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

这条规则的意思不是“尽量先分析”，而是没有完成根因调查，就不允许进入修复动作。在本文语境中，根因调试对应 Superpowers 的 systematic-debugging skill，是一种用文本纪律强制执行的工程调试流程。

在本文档中的语境

在本文讨论的 Superpowers 工作流里，根因调试被描述为价值最被低估的调试 skill。它的核心价值不在于提供某个神奇调试技巧，而在于阻止 Claude 或工程师进入默认的“猜”模式。

原文给出的对比很直接：普通系统调试平均耗时约 2 到 3 小时，而使用 systematic-debugging 时，常见可缩短到 15 到 30 分钟。文中认为差距的主要原因不是模型突然更聪明了，而是流程强制要求先收集证据、确认根因，再提出修复。

根因调试因此不是“调试建议”，而是 AI 工程纪律 的一部分：它约束的是行为顺序、证据标准与停止条件。

四阶段机制

根因调试由四个阶段组成，而且必须顺序执行：前一阶段未完成，不能进入下一阶段。

第一阶段：根因调查

这一阶段的目标不是立即解释问题，而是先把事实收集完整。文中列出的动作包括：

• 完整读错误信息，不是只扫一眼关键词，而是把报错全文读完。
• 稳定复现问题，确保有清晰、可重复的触发步骤。
• 检查最近的 git 变更，确认问题是否和近期修改直接相关。
• 对于多组件系统，要在每个边界打诊断日志，先跑一次收集证据，再分析信号在哪一段中断。

这一阶段的边界很明确：先采证，后解释。如果连复现都不稳定、错误都没读完整、链路证据还没采齐，就不该开始修。

第二阶段：模式分析

在拿到证据后，第二阶段不是立刻改代码，而是寻找“正确样本”和“差异模式”。文中的要求包括：

• 在同一个 codebase 里找类似且能正常工作的代码路径。
• 把正常代码和异常代码逐项对比差异。
• 每一个差异都要列出来，不管看起来多小，都不能先假设“这项无关”。
• 理解相关依赖、前提假设和上下游条件。

这里的关键思想是：很多 bug 不是单点语法错误，而是某个前提条件、初始化顺序、边界契约或依赖假设被破坏。模式分析要求先找出“它为什么在别处能工作、在这里却失效”。

第三阶段：单假设验证

这是 根因调试 与随意试错最大的分界点。第三阶段要求一次只验证一个明确假设。

文中的标准动作是：

• 先写下一个具体假设，例如“我认为 X 是根因，因为 Y”。
• 进行最小变更验证，让实验只检验当前这个假设。
• 如果验证失败，换一个新假设重新验证。
• 不要叠加改动。

“不叠加改动”是这一阶段最重要的纪律之一。因为一旦为了提高命中率同时改两三处，即使问题暂时消失，也无法知道真正的根因是什么；如果问题没消失，排查空间还会进一步扩大。

因此，单假设验证的真正目标不只是找到可用修复，更是避免把调试过程污染成无法解释的混合试验。

第四阶段：实现修复

只有当前三个阶段已经完成，才进入真正的修复。文中的要求包括：

• 先写一个能够复现该问题的测试。
• 只改一处，避免把“修复问题”和“顺手重构”混在一起。
• 如果三次修复都没解决问题，必须停下来，重新讨论是否是架构层面的问题。

这一阶段说明：根因调试并不反对修复，反对的是在根因不明时盲修。一旦进入修复阶段，动作仍要尽量小、可验证、可回退。

三次失败后暂停重审

根因调试里最实用、也最反直觉的约束之一，是“三次失败规则”。

规则不是说第三次失败后永远不能再改，而是说：如果已经尝试了三次修复仍未解决，就不能直接继续第四次猜测式修改，必须先停下来，退后一步重审。

重审的重点通常是：

• 当前理解的“根因”是否只是症状描述；
• 问题是否其实来自架构、边界契约或模式本身；
• 之前的验证是否被叠加改动污染；
• 是否遗漏了某个关键证据链。

文中明确指出，这和很多工程师的直觉相反。多数人第三次失败后会更焦虑，更想快速试第四次、第五次；但额外的猜测修复只会引入更多不确定性，同时继续浪费时间。

因此，“三次失败后暂停重审”本质上是一个强制止损机制。它防止团队在错误路径上投入越来越多改动和上下文成本。

为什么它比“先试一下”更快

文中专门反驳了几种常见借口，并给出了相应判断：

• “这个 issue 很简单，不用走流程”——简单 bug 也有根因，流程对简单问题往往更快。
• “紧急情况，没时间调查”——系统性调试通常比猜测更快，“紧急”不是跳过调查的理由。
• “先试一下再说”——一旦第一步就是猜，后面通常会一直猜下去。
• “我已经大概知道在哪”——知道症状位置，不等于知道根因。

这套说法背后的逻辑是：猜测式调试看似启动快，但很容易把 5 分钟的问题拖成数小时，因为每次失败尝试都会增加新的变量；而 根因调试虽然前面多了调查和对比，但能显著减少返工。

细节与边界

不是禁止经验判断，而是禁止未经验证的直接修复

根因调试并不要求工程师完全没有直觉。经验仍然可以帮助快速形成假设，但这个假设必须进入“单假设验证”流程，而不能直接变成修复提交。

不是永远只能改三次

“三次失败规则”并不是绝对禁止后续尝试。文中给出的边界是：第三次失败后，必须先讨论是不是架构问题；如果讨论后确认不是，只是需要换一个新方向，当然可以继续。但继续发生在重审之后，而不是不经停顿地冲到第四次。

对简单问题同样适用

文中特别强调，一个问题越看起来简单，越容易隐藏未被说出的假设，所以越不应该省掉流程。哪怕只是很小的改动，也应该遵守先调查、再验证、后修复的顺序。

更适合多组件和边界复杂的问题

虽然所有 bug 都能从中受益，但文中尤其强调多组件系统：因为这类问题最容易在接口边界、日志断点、依赖条件上出错。此时“在每个边界打诊断日志，先采证再分析”比直接改某个局部函数更重要。

与相关工作流的关系

根因调试是 Superpowers 工作流摘要 中处理异常和故障的一环。它通常在实现过程中插入，而不是代替设计、计划和执行。

• 与 AI 工程纪律 的关系：它体现的是“禁止跳步骤”的纪律化调试。
• 与 任务颗粒化计划 的关系：一旦问题需要修复，修复动作也应尽量保持可验证、可分解，而不是一团模糊的大改。
• 与 Superpowers 的关系：它是该体系中的调试类 skill 之一。