常见问题

安装与初始化

spec-first doctor 提示 Node 版本不满足

当前产品源码要求：

• Node.js >= 20

如果你看到版本错误，请升级 Node 后重试：

node -v
spec-first doctor

---

spec-first init 失败，最常见原因是什么？

当前实现里最常见的失败原因有：

1. 当前目录不是 Git 仓库
2. 没有指定 --claude 或 --codex
3. 本地宿主运行时状态是 legacy managed state，需要重新 init
4. Claude 项目里的 .claude/settings.json 不是合法 JSON

建议先做这几个检查：

git status
spec-first doctor
spec-first init --claude

如果你使用 Codex：

spec-first init --codex

---

初始化后，为什么还要重启 Claude Code 或 Codex？

因为 init 会把运行时入口与受管资产写进项目，但宿主进程不会自动重新加载它们。

当前 CLI 源码和 README 都把“重启宿主”作为初始化后的必要步骤。

---

Codex 为什么没有 .codex/commands/spec/？

因为当前产品实现不是这么设计的。

Codex 侧的正式入口是：

• $spec-*
• 从 .agents/skills/ 发现

而不是把 /spec:* 命令放在 .codex/commands/spec/ 里。官网旧文档这里最容易写错。

---

入口与命令

根 CLI 和 workflow 入口是什么关系？

它们不是一回事。

根 CLI

spec-first doctor
spec-first init --claude
spec-first clean --claude
spec-first stage0-context --stage plan --workflow spec-plan --format json

运行时 workflow 入口

Claude Code：

/spec:mcp-setup
/spec:graph-bootstrap
/spec:brainstorm
/spec:plan
/spec:work
/spec:review
/spec:compound

Codex：

$spec-mcp-setup
$spec-graph-bootstrap
$spec-brainstorm
$spec-plan
$spec-work
$spec-review
$spec-compound

---

为什么我在 Codex 里输入 /spec:plan 不生效？

因为 Codex 当前正式入口不是 /spec:*，而是 $spec-*。

正确写法：

$spec-plan

而不是：

/spec:plan

---

stage0-context 是给用户直接用的吗？

它是正式存在的根 CLI 子命令，但当前定位更偏 阶段启动时的运行时上下文输出，主要供 spec-plan、spec-work、spec-review 这类 workflow 在内部消费。

可以手动调用，但它不是日常交互的主入口。

---

工作流与阶段

当前到底是五阶段还是六阶段？

两种说法都能看到，但语义不同：

• 对外交付链路：Host Setup → Stage-0 → Ideate → Brainstorm → Plan → Work → Review → Compound
• 主工作流：Ideate → Brainstorm → Plan → Work → Review → Compound
• 核心闭环：很多历史文档仍用 Brainstorm → Plan → Work → Review → Compound

官网现在统一采用：

• 宿主准备 + Stage-0 是前置层
• Ideate → Brainstorm → Plan → Work → Review → Compound 是主工作流

---

spec-graph-bootstrap 和 spec-compound 是什么关系？

它们都可以作为 Stage-0 入口看待，但职责不同：

• spec-graph-bootstrap：当前主要 Stage-0 入口，负责 facts、routing、minimal-context
• spec-compound：偏知识沉淀与复用，不等价于主 graph-bootstrap 路径

如果你要“先把上下文构建好”，优先跑 spec-graph-bootstrap。

---

能不能跳过 spec-mcp-setup 或 spec-graph-bootstrap？

技术上你可以直接进入后续 workflow，但当前 README 明确把这两层放在前面，因为它们决定后续上下文是否可靠。

如果你的目标是用当前官方推荐路径获得更稳定结果，不建议跳过：

1. spec-mcp-setup
2. spec-graph-bootstrap

---

能力边界

Spec-First 是不是“零配置、全自动代码生成平台”？

不是。

当前 README 直接把这类期待列为 不适合场景。它更像一个治理 AI 编码交付链的工程系统，而不是自动替你完成全部开发的黑盒。

---

不使用 Claude Code 或 Codex，可以只用 CLI 吗？

从“装包并运行根 CLI”角度可以执行部分命令，但当前产品明确把目标用户限定在：

• Claude Code 用户
• Codex 用户

也就是说，官网不应该把它描述成宿主无关的通用 AI coding 平台。

---

clean 会帮我删掉所有 Spec-First 痕迹吗？

不会。

当前文档明确说明：

• clean 负责移除受管资产
• 语言策略 block 仍需手动处理
• legacy state 的升级路径是重新 init，不是依靠 clean 迁移

---

规模与资产

当前到底有多少 skills 和 agents？

以当前产品 README 与治理测试为准：

• 源码 bundle：47 个 skills、57 个 agents、4 个 agent support files
• Claude 运行时：12 个 command-backed workflow + 35 个 skills
• Codex 运行时：34 个 skills

这些数字是 当前实现事实，不是营销文案。

---

Review 阶段是不是“47 个代理一起审”？

不是。

57 是整个源码内置 agent 总数；Review 阶段只会调度其中与评审相关的那一部分。当前 README 的正式口径是：

• 17 个 reviewer personas
• 2 个 CE agents

官网不应该继续写成“26 个评审代理就是当前官方口径”。

---

还有问题？

• 安装指南
• 工作流与阶段
• Skills 生态
• Agents 体系
• GitHub Issues