用途:面向 AI 编程代理的调试纪律技能。代理常见问题是看到报错就立刻改代码、反复猜测导致问题扩大,本技能通过严格的五阶段协议,在根因被识别并经用户确认之前禁止编辑源码。基于 claude-debug(含 PreToolUse 钩子强制执行的完整插件)。
适用场景:某个缺陷被反复“修复”但底层问题依旧;需要让代理放慢节奏、先做有纪律的调试再改代码;故障为间歇性、回归性、性能相关或难以隔离;希望在应用修复前设置明确的用户确认检查点。
五阶段协议:1)复现:运行失败命令或测试,记录确切错误,重复 2-3 次确认一致性;不读源码、不做假设、不改文件。2)隔离:阅读代码,添加标记为 // DEBUG 的诊断日志,带诊断重跑,用二分法缩小范围;仅允许 // DEBUG 日志,即使看到缺陷也不修。3)根因:在隔离位置用“5 Whys”分析原因,移除调试日志,陈述根因分析并询问用户是否同意或需继续调查,必须等待确认。4)修复:清除全部 // DEBUG 行,仅做针对已确认根因的最小改动,只编辑与根因相关的文件,不重构无关代码。5)验证:运行原先失败的测试必须通过,运行相关测试;间歇性缺陷需运行 5 次以上;若验证失败说明根因判断有误,返回第 2 阶段。
按缺陷类型的策略:崩溃或 panic 沿堆栈反向追踪坏值来源;输出错误用二分法记录中点、每轮折半搜索空间;间歇性问题对比通过与失败运行日志找顺序分歧;回归用 git bisect 定位问题提交;性能问题在阶段边界计时找瓶颈。
关键规则:第 1-3 阶段绝不编辑源码(第 2 阶段仅 // DEBUG);未经用户确认绝不越过第 3 阶段;调查前必须先复现;修复后必须验证。
限制:仅在任务明确匹配上述范围时使用;输出不能替代针对具体环境的验证、测试或专家评审;若缺少必要输入、权限、安全边界或成功标准,应停止并请求澄清。安装命令与具体接入方式暂未提供。