常见问题

安装与初始化

spec-first doctor 报错"command not found"

# 确认 npm 全局路径在 PATH 中
npm config get prefix
# 输出类似 /usr/local，确认 /usr/local/bin 在 PATH 中

# 重新安装
npm install -g spec-first

# 如果用的是 nvm
nvm install --lts

spec-first init 失败

常见原因：

1. 目标目录不是 git 仓库 — spec-first init 需要在 git 仓库中运行
2. 目录已有内容 — 使用 --force 覆盖：spec-first init --claude --force
3. 权限不足 — 检查目录写权限
4. 未指定平台 — 必须指定 --claude 或 --codex

# 确认是 git 仓库
git status

# 强制重新初始化（选择你的 AI 工具）
spec-first init --claude --force
# 或
spec-first init --codex --force

/spec:* 命令在 AI 工具中不显示

1. 确认 spec-first init --claude（或 --codex）已在项目目录中运行
2. 确认对应的 commands 目录存在且包含 .md 文件：
   • Claude Code: .claude/commands/spec/
   • OpenAI Codex: .codex/commands/spec/
3. 重启 AI 工具

# 检查命令是否已部署（Claude Code）
ls .claude/commands/spec/
# 或（OpenAI Codex）
ls .codex/commands/spec/
# 应该看到: brainstorm.md  plan.md  work.md  review.md  compound.md

---

工作流使用

五阶段是否必须按顺序执行？

不是。 可以从任何阶段开始：

• 需求明确 → 直接 /spec:plan
• 计划已就绪 → 直接 /spec:work
• 代码已完成 → 直接 /spec:review
• 只想记录经验 → 直接 /spec:compound

Ideate 是必经阶段吗？

不是。 Ideate 是可选前置阶段，仅在"不确定要做什么"时使用。如果你已有明确的需求，直接从 Brainstorm 开始。

Review 阶段需要多长时间？

取决于变更大小：

• 小变更（< 100 行）：1-3 分钟
• 中等变更（100-500 行）：3-5 分钟
• 大型变更（> 500 行）：5-10 分钟

使用 mode:report-only 可以快速获取报告。

Compound 阶段是否每次都必须执行？

不是必须的，但强烈建议。 Compound 沉淀的知识会被后续的 Review 阶段自动发现和引用，形成知识复利。跳过 Compound 意味着团队无法从每次问题解决中受益。

---

概念疑问

47 个代理和 26 个评审代理是什么关系？

47 是代理总数，分布在 6 个目录中：

目录	数量	说明
review/	26	代码评审代理
document-review/	7	文档评审代理
research/	6	代码与技术搜索代理
design/	3	设计同步代理
workflow/	4	工作流辅助代理
docs/	1	文档写作代理
总计	47

Review 阶段只使用 review/ 目录下的 26 个代理（加上条件触发）。

CLI 和 Commands 是什么关系？

它们指的是同一件事。CLI（命令行工具）是 spec-first npm 包提供的可执行程序，而 Commands 是通过 spec-first init 部署到项目后，在 AI 工具中通过 /spec:* 调用的入口。CLI 通过 init 命令将 Commands 部署到项目的 .claude/ 或 .codex/ 目录中。

.claude-plugin/plugin.json 和 .claude/spec-first/state.json 的关系？

• plugin.json 是发布清单，定义 CLI 包中包含哪些资产
• state.json 是项目本地清单，记录当前项目已部署的资产版本
• spec-first init --claude 读取 plugin.json 将资产同步到项目，并在 state.json 中记录状态

---

进阶用法

LFG 和手动工作流有什么区别？

维度	手动工作流	LFG
控制点	每个阶段人工确认	全自动
适用场景	复杂需求、需讨论	明确需求、快速交付
审查模式	Interactive	Autofix

如何更新已部署的 spec-first 资产？

# 更新 CLI
npm update -g spec-first

# 重新部署到项目
spec-first init --claude --force

如何移除 spec-first 资产？

# 移除受管资产（保留自定义内容）
spec-first clean --claude

---

没有找到你的问题？

• GitHub Issues — 提交 Bug 或功能建议
• Skills 生态 — 查看所有可用技能
• Agents 体系 — 查看所有代理