深调试是一个面向 AI 代理在代码执行过程中参考的调试协议，用于那些无法通过快速修复解决的顽固缺陷。其文档定位为“AI-consumed reference”，即供 Claude 在执行时阅读使用，人类可读的说明另见架构与入门文档。
用途与升级路径
该协议是调试升级路径的第二级：先从 bugfix-quick（15 分钟内、原因明确）开始，快速路径失败后再进入 deep-debugging，改用科学方法排查。它组合使用 tree-of-thoughts 技能构建假设树，使用 chain-of-verification 技能验证结论。
何时使用
文档给出信号对照：若堆栈跟踪指向明确代码行、可 100% 复现、或属于已知边界情况，应使用 bugfix-quick；若问题间歇性/不稳定、存在多个可能原因、“在我机器上正常”、涉及时序或竞态条件、或仅在生产环境出现且无法本地复现，则应使用 deep-debugging。
六步协议
第一步是可靠复现。目标是构造最小复现用例（剥离所有非必要代码）、记录触发条件（环境、时序、操作顺序）；若为间歇性问题，则重复 N 次并计算失败率。若无法复现则应停止，不要猜测，改为在生产环境增加日志、指标、追踪等可观测性手段，等待下次出现时捕获。
第二步是构建假设树（借助 tree-of-thoughts）。不要跳到第一个怀疑对象，而应枚举所有可能分支。文档以“登录在生产环境间歇性失败”为例，列出会话存储、负载均衡/基础设施、认证服务三大分支及其子项。每个分支按 0 到 10 分评估三项：与观察到的症状的吻合度、与最近变更（自上次已知良好版本以来的差异）的吻合度、与失败模式（时序、频率、环境）的吻合度；低于 5 分的分支剪枝，保留者继续展开。
第三步是尽可能二分。若缺陷是近期引入的，使用 git bisect start、git bisect bad HEAD、git bisect good <已知良好提交>、git bisect run ./scripts/reproduce-bug.sh 自动缩小范围，可在 O(log n) 步内定位到单个提交。若不在 git 历史中，则对代码库二分：注释掉可疑模块的一半，看缺陷是否仍存在，逐步缩小到一个文件或函数。
第四步是逐个检验假设。针对得分最高的假设，先做预测（例如“若 A1 为真，则失败时刻指标 X 应显示连接池饱和”），再运行实验或查看指标进行观察，若吻合则进入第五步，不吻合则剪枝并转向下一个假设。反模式是一次改动多处，那样无法判断哪个修复起了作用。
第五步是验证根因（借助 chain-of-verification）。在宣称修复前，先起草根因解释与修复方案，再生成 3 到 5 个验证问题，例如“修复是否将失败率从 X% 降到 0%？”“移除修复后缺陷是否会重现？”“相似代码路径是否存在同样问题（更广泛影响）？”每个问题都要通过测试、指标、代码搜索等工具回答，而非凭记忆；最后根据实际结果修订解释。
第六步是编写回归测试。没有回归测试的缺陷修复等于缺陷会再次出现。测试应满足：在未修复代码上失败、在修复代码上通过、用注释记录确切场景（时序、竞态、输入形态等）。
反模式
文档列出五类反模式：把不稳定测试归咎于“重试即可”（80% 的不稳定测试是暴露时序问题的真实缺陷）；散弹式修复（同时改五处碰运气）；只根据堆栈跟踪推理（堆栈只显示崩溃位置，不显示原因）；跳过复现（无法复现就无法验证修复）；不留回归测试。
输出格式
协议要求按固定结构输出：缺陷简述、症状（用户观察到的现象）、复现（最小用例、试验次数、失败率）、根因（经证实的解释）、证据（已回答的验证问题）、修复（改动内容及提交引用）、回归测试（测试文件与名称）、相似影响（已检查的其他位置——免疫或同样脆弱）。
关联规则与技能
文档关联 bugfix-quick（快速路径失败后升级至此）、tree-of-thoughts（假设分支）、chain-of-verification（验证根因结论），以及三条核心规则：no-assumption（不要猜测原因）、verification（发布前先证明）、simplicity-over-complexity（根因明确后修复应尽量最小，克制“顺便重构”的冲动）。