排错与 FAQ

新手在落地这些理念时最常卡住的地方，集中在这里。给的是排查思路，不只是答案。

Q1：SDD 到底是 Spec-Driven 还是 Subagent-Driven？

看上下文判断，两者不同层级：

• 出现在"规格 / 需求 / 验收 / spec.md"语境 → Spec-Driven Development（规格驱动）；
• 出现在 superpowers 工作流第 4 步、"多个子代理并行分工"语境 → Subagent-Driven Development（子代理驱动）。

详见 范式全景图的术语提醒 与 协作与工作流。

Q2：装了 Spec Kit 但斜杠命令不出现

思路：命令依赖 AI 编码代理正确加载了 Spec Kit 的 slash command 定义。

1. 先确认 CLI 装好：终端敲 specify --help 能列子命令；
2. 确认项目已 specify init（初始化后才生成 .specify/ 与命令模板）；
3. uv tool install ... --from git+... 失败多半是访问 GitHub 受限，改 pip install specify-cli 或走代理。

见 SDD 安装章节的坑提示。

Q3：openspec init 提示 Node 版本过低

OpenSpec 需要 Node.js ≥ 20。检查并升级：

# 环境：PowerShell / 终端
node -v

版本低于 20 时，用 nvm / volta 等版本管理器切到 20+ 再重装。

Q4：AI 总是"忘记"我之前定的规范

病因八成是上下文，不是模型。 排查顺序：

1. 规范是否入库（写进 spec / AGENTS.md），还是只在上一轮聊天里？——新会话它根本看不到；
2. 是否被无关信息淹没（整仓塞入、历史过长），关键约束权重被稀释；
3. 是否做了会话切分，把该带的文件精准喂进去。

对应解法见 上下文工程。

Q5：测试变绿了，但功能明显是空的

这是测试造假：AI 为了让测试通过，删断言 / 放宽预期 / mock 掉真实逻辑。

排查：跑测试前先看 git diff，若只动了 test_*.py 没动实现，立刻警觉。

$ git diff --stat
 test_remember_me.py | 2 +-     ← 只改测试 = 警报

解法：约束"实现阶段不得修改测试断言"，并把它写进规则。详见 组合落地实战·坑 1。

Q6：Vibe Coding 做着做着整个项目就乱了

正常——这是 Vibe 在棕地/复杂项目里的固有结局（"95% 活不过两周"）。

信号：改 A 坏 B、需求说不清、每轮对话都在悄悄改目标。

解法：立刻从探索层升级到规格层，先补一份轻量 spec 把边界钉死。见 Vibe Coding 的问题。

Q7：一上 SDD 就写了十几页文档，团队嫌重

你把 SDD 做成了"瀑布 + 厚文档"，这是最典型的误区。

正解：好的规格是轻量、结构化、只沉淀最易返工的决定。能用 Requirements / Design / Tasks 三个小文件说清，就不要写长文。见 SDD 常见误区。

Q8：给了代理自动执行权限，不敢用怕它删库

风险真实存在，必须前置约束，而不是"用完再说"：

• 沙箱运行 + 命令白名单；
• 隔离凭据与生产环境；
• 破坏性动作（删 / 发布 / 改权限）保留人工审批闸门。

见 最佳实践·安全红线 与 Harness 安全提示。

Q9：这些理念我该全学还是选一个？

都不是"二选一"。 它们分处探索/规格/执行/环境四层，是组合拳。按 最佳实践·按复杂度选流程 的表，任务越复杂、越需要往上叠加。

调试通用思路

遇到"AI 变笨"，先别怀疑模型，按这条顺序查：

上下文对不对（带没带关键文件/约束）
   → 意图清不清楚（有没有 spec 钉住边界）
   → 有没有验证（测试/闸门能不能客观判定对错）
   → 才轮到"是不是模型能力上限"

下一步

• 一页速查全部要点：快速参考卡片。