---

name: phase-gated-debugging description: "用于调试任何 Bug。强制执行5阶段协议，在确认根因之前禁止修改代码。防止过早尝试修复。" risk: safe source: community date_added: "2026-03-28"

阶段门控调试法

概述

AI 编程代理看到错误就立即修改代码。它们猜测修复方案，猜错后陷入恶性循环。本技能强制执行严格的5阶段协议，在确定根因之前禁止编辑源代码。

基于 claude-debug（带有 PreToolUse 钩子强制执行的完整插件）。

适用场景

在以下情况使用本技能：

• Bug 反复被"修复"但底层问题始终未解决
• 需要让代理放慢速度，在修改代码前强制进行规范化调试
• 故障是间歇性的、回归性的、性能相关的，或难以隔离的
• 需要在应用修复前设置明确的用户确认检查点

协议流程

阶段1：复现

运行失败的命令/测试。捕获确切错误。运行2-3次确认一致性。

• 不要阅读源代码
• 不要提出假设
• 不要编辑任何文件

阶段2：隔离

阅读代码。添加标记为 // DEBUG 的诊断日志。带诊断重新运行。二分法缩小范围。

• 只允许添加 // DEBUG 标记的日志
• 即使看到 Bug 也不要修复

阶段3：根因分析

分析隔离位置的根本原因。使用"5个为什么"技术。移除调试日志。

陈述："这是我的根因分析：[解释]。你同意吗，还是需要我进一步调查？"

等待用户确认。未经确认不得继续。

阶段4：修复

移除所有 // DEBUG 行。针对已确认的根因应用最小化修改。

• 只编辑与根因相关的文件
• 不要重构无关代码

阶段5：验证

运行原始失败测试——必须通过。运行相关测试。对于间歇性 Bug，运行5次以上。 如果验证失败：根因判断有误，返回阶段2。

Bug 类型策略

| 类型 | 技术 | |------|------| | 崩溃/Panic | 从堆栈跟踪反向追溯——追踪错误值到其来源 | | 输出错误 | 二分法——在中间点打日志，每次迭代将搜索空间减半 | | 间歇性 | 对比通过与失败的运行日志——找到顺序分歧点 | | 回归 | git bisect——找到引入问题的提交 | | 性能 | 在阶段边界计时——找到瓶颈 |

核心规则

1. 在阶段1-3中绝不编辑源代码（阶段2中的 // DEBUG 除外）
2. 未经用户确认绝不跳过阶段3
3. 调查前必须先复现
4. 修复后必须验证

局限性

• 仅在任务明确符合上述范围时使用本技能。
• 不要将输出视为特定环境验证、测试或专家审查的替代品。
• 如果缺少必要的输入、权限、安全边界或成功标准，请停下来寻求澄清。