Debug 指南 ​

入口：spec-debug · spec-debug · 契约见 spec-debug

spec-debug 用于系统性定位 bug 根因，并在需要时推进修复。

参数：[issue reference, error, test path, or broken behavior]

核心原则 ​

spec-debug 的重点不是“试几个修复看看”，而是先解释完整因果链：

  1. 先调查，再修复
  2. 对不确定链路提出可验证预测
  3. 一次只验证一个假设
  4. 卡住时先解释为什么卡住，而不是继续盲试

执行阶段 ​

阶段目标
Triage解析输入、收集 issue 或错误上下文
Investigate复现问题并跟踪代码路径
Root Cause建立并验证因果链
Fix只有在需要时才进入修复
Close结构化总结与交接

输入与输出 ​

类型内容
输入issue 链接、错误日志、stack trace、失败测试、复现步骤或异常行为描述
输出根因解释、最小修复 diff、复现/验证证据、仍未覆盖的风险

一个合格的 debug run 必须能说明：问题如何复现、为什么发生、为什么当前修复能阻断同一因果链。

适用场景 ​

  • 测试失败但原因不清楚
  • 用户给出 stack trace 或异常日志
  • GitHub / Linear / Jira issue 需要先做复现和根因分析
  • 之前已经尝试修复但没有稳定解决

基本调用 ​

text
spec-debug "登录接口在并发下偶发 500"
spec-debug "tests/integration/auth.test.js"

与 work 的区别 ​

  • debug：先找根因，再决定是否修
  • work：已有明确计划，按计划执行实现

如果问题还没有形成清楚的实现计划，优先用 debug。

不适合使用 ​

  • 只是要实现一个明确 feature，且没有失败现象。
  • 只是想让 AI 猜测可能原因，不准备复现或验证。
  • 问题其实是产品范围变化，需要先回到 brainstorm 或 plan。

下一步 ​