安装指南
Spec-First 当前以 npm 包形式发布，安装后提供根级 CLI，再通过 init 把运行时资产同步到具体项目。
前置要求
- Node.js
>= 20 - Git
- 一个 Git 仓库
- 至少安装以下宿主之一：
- Claude Code
- Codex
补充说明：
spec-first init会读取git config user.namegraph-bootstrap依赖git ls-files- 因此 非 Git 目录不属于支持范围
1. 从 npm 安装
bash
npm install -g spec-first
spec-first -v安装脚本会执行 postinstall，用于输出安装确认信息并清理当前平台不需要的原生 tree-sitter 预编译产物。
2. 检查环境
bash
spec-first doctor也可以只检查某一宿主：
bash
spec-first doctor --claude
spec-first doctor --codex如果 doctor 报告 legacy managed state，官方 README 当前给出的升级路径是重新运行 init。
3. 初始化项目
进入你的目标项目目录后运行：
bash
spec-first init --claude
# 或
spec-first init --codex如果需要显式指定开发者身份与语言：
bash
spec-first init --claude -u <name> --lang <zh|en>
spec-first init --codex -u <name> --lang <zh|en>init 实际会写入什么
当前产品 README 明确说明：init 不是只读命令。它会把 Spec-First 的运行时资产同步到项目。
Claude Code 项目
通常会写入：
text
.claude/commands/spec/
.claude/skills/
.claude/agents/
.claude/spec-first/state.json
.claude/spec-first/.developer
.claude/settings.json
.claude/hooks/session-start
CLAUDE.md
CHANGELOG.md（仅在缺失时 bootstrap）Codex 项目
通常会写入：
text
.agents/skills/
.codex/agents/
.codex/spec-first/state.json
.codex/spec-first/.developer
AGENTS.md
CHANGELOG.md（仅在缺失时 bootstrap）这里最重要的差异是：
- Claude 使用
.claude/commands/spec/与/spec:* - Codex 主要通过
.agents/skills/暴露$spec-* - Codex 不是
.codex/commands/spec/主入口
根级 CLI 命令
当前根级 CLI 可以稳定承诺的主命令是：
| 命令 | 用途 |
|---|---|
spec-first doctor | 检查环境、平台状态和受管资产 |
spec-first init | 初始化并同步运行时资产 |
spec-first clean | 删除受管资产 |
spec-first stage0-context | 输出 Stage-0 运行时上下文 |
示例：
bash
spec-first stage0-context --stage plan --workflow spec-plan --format json运行时 workflow 入口
请不要把根 CLI 命令和 workflow 入口混为一谈。
Claude Code
text
/spec:mcp-setup
/spec:graph-bootstrap
/spec:ideate
/spec:brainstorm
/spec:plan
/spec:work
/spec:review
/spec:compoundCodex
text
$spec-mcp-setup
$spec-graph-bootstrap
$spec-ideate
$spec-brainstorm
$spec-plan
$spec-work
$spec-review
$spec-compound4. 初始化后的推荐动作
初始化完成后，推荐按下面顺序开始：
- 重启宿主 CLI
- 运行宿主准备
- 运行 Stage-0 graph bootstrap
- 再进入 Ideate / Brainstorm / Plan 等主工作流
示例：
bash
/spec:mcp-setup
/spec:graph-bootstrap或在 Codex 中：
bash
$spec-mcp-setup
$spec-graph-bootstrap从源码安装
如果你需要从本地源码安装：
bash
git clone https://github.com/sunrain520/spec-first.git
cd spec-first
npm pack
npm install -g ./spec-first-<version>.tgz
hash -r清理受管资产
如果需要移除受管资产：
bash
spec-first clean --claude
# 或
spec-first clean --codexclean 会删除受管资产，但不会替你清除所有用户自定义内容；README 里特别说明，语言策略 block 仍需手动处理。