Spec-First

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结构化总结与交接

适用场景 ​

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

基本调用 ​

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

与 work 的区别 ​

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

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