claude-debugging-skilllisted

# 调试推理架构 这份规则描述的是在面对 bug、错误信息、异常行为时的完整推理过程。调试是所有编程工作中最考验系统性思维的环节。缺乏方法论的调试是反复猜测和随机修改，有方法论的调试是假设驱动的系统性排查。两者在效率上的差距在复杂问题上会放大到数倍乃至数十倍。这份文档的价值在于把有经验的工程师在调试时隐性运用的方法论显式化。 --- ## 一、调试的基本认知框架 ### 1.1 症状与根因的区别 每个 bug 都有症状（可以观察到的表现）和根因（真正导致问题的原因）。修复症状而不修复根因，问题会以另一种形式再次出现。调试的目标是找到根因，而不仅仅是消除症状。 症状和根因之间可能隔着一条很长的因果链。错误出现在 A 模块，但根因在 B 模块，因为 B 向 A 传递了错误的数据，而 B 之所以产生错误数据是因为 C 模块的配置不正确。只修改 A 不会真正解决问题。 ```mermaid flowchart LR A[症状\n可观察到的错误表现] --> B[直接原因\n直接导致症状的代码] B --> C[间接原因\n导致直接原因的上游问题] C --> D[根因\n问题链的起点] D -- 修复这里才能真正解决问题 --> E[彻底修复] A -- 只修复这里会再次出现 --> F[临时缓解] ``` ### 1.2 假设驱动的调试方法 有效的调试不是随机修改代码直到问题消失，而是基于已有信息形成关于根因的假设，然后设计最小的验证实验来验证或否定这个假设，根据结果更新假设，直到找到根因。 这个方法的核心是：每次调试行动都有明确的目的（验证某个特定的假设），而不是漫无目的地尝试。如果行动没有验证任何假设，它就没有推进调试进展。 ### 1.3 二分法缩小范围 当问题的位置不明确时，使用二分法快速缩小范围：找到问题存在的最大范围，在中间设置一个检查点，根据检查点的结果判断问题在前半段还是后半段，然后在确定有问题的那一半中继续二分，直到定位到具体的问题位置。 --- ## 二、错误信息的解析方法 ### 2.1 完整读取错误信息 最常见的调试效率问题是没有完整读取错误信息就开始猜测原因。错误信息通常包含三个部分：错误类型（告诉你发生了什么类型的问题）、错误消息（告诉你具体发生了什么）、调用栈（告诉你���题发生在哪里、通过什么调用路径到达的）。 这三个部分都需要仔细阅读。错误消息中经常包含直接指向根因的线索，但在调试者焦虑的状态下容易被忽略。 ### 2.2 调用栈的读取方向 调用栈从下到上是调用的时间顺序（最底层是最先执行的）。调试时关注两个位置：调用栈的最顶层（问题直接发生的位置）和调用栈中自己的代码与第三方库代码的边界（通常这个边界附近是最值得检查的地方，因为自己的代码向第三方库传递了错误的输入，或者对第三方库的返回值处理有问题）。 ### 2.3 错误消息的分类处理 不同类型的错误消息需要不同的处理思路： 类型错误和空指针：通常意味着某个值在某个时刻是 null 或者不是期望的类型，需要追踪这个值是从哪里来的，是在哪个步骤变成了错误的类型或空值。 权限和认证错误：需要检查当前操作所需的权限是否已经正确获取，以及权限令牌是否已经过期或格式不正确。 网络和超时错误：需要区分是服务不可用还是客户端配置有问题，需要检查网络连通性、端点地址、超时设置。 数据库错误：通常包含 SQL 信息，需要检查查询语句的语法、约束条件冲突、连接配置。 ```mermaid flo