安装指南

Spec-First 当前以 npm 包发布。全局 CLI 负责 doctor、quickstart、init、update、clean 和 task-pack 校验；真正的研发 workflow 入口由宿主在项目内加载。Claude Code 与 Codex 是主要支持面，Kiro、Qoder、Cursor、OpenCode 是显式 opt-in preview。

Install Surface

npm 包提供 CLI 真源；init 根据交互选择把 runtime assets 投影进当前 Git 仓库。

npmspec-first package包含 CLI、source skills（含 skill-local agents）、templates 和生成逻辑。

→

CLIdoctor / init / clean检查环境、生成 runtime、清理 managed assets。

→

Hostsspec-* runtime按所选宿主生成 Claude/Codex runtime，或 Kiro/Qoder/Cursor/OpenCode preview runtime。

前置要求

要求	说明
Node.js >=20	package.json 的 engines.node 为 >=20.0.0，postinstall 会检查 Node 版本
npm / npx	用于安装 spec-first，也用于部分 MCP / provider warmup
Git	init、workspace child repo 识别、workflow 证据和变更边界都依赖 Git
Git 仓库	推荐在目标 repo 根目录运行；父 workspace 会按 child repo 规则处理
Claude Code / Codex / preview hosts	至少安装一个宿主；当前产品面统一使用 spec-* workflow 入口

推荐安装

macOS、Linux、WSL、Windows PowerShell 都使用 npm 安装：

npm install -g spec-first
spec-first --version
spec-first doctor

如果只想临时运行 CLI，可以使用 npx：

npx -y spec-first@latest doctor
npx -y spec-first@latest init

团队项目推荐全局安装，避免每次 npx 都重新解析包和下载 provider 依赖。

交互式初始化

在目标 Git repo 根目录运行：

spec-first init

当前 init 的默认路径是交互式：选择 Claude Code 和/或 Codex、确认开发者姓名、选择语言、在父 workspace 场景下选择目标 child repo 或全部 child repo、预览写入计划，然后显式确认。

初始化会写入全局 developer profile：

~/.spec-first/.developer

后续项目会优先复用该 profile。需要更换姓名或语言时，可在 init 中重新确认，或用非交互参数显式覆盖。

初始化宿主 runtime

spec-first init 会在交互中选择目标宿主，并按选择生成对应 runtime assets。初始化后重启宿主或开启新会话，然后使用 spec-* workflow 入口。Claude Code 的 /spec:* 与 Codex 的 $spec-* 是兼容别名；官网主路径统一写 spec-*。

宿主	状态	生成内容	初始化后入口
Claude Code	既有支持	.claude/commands/spec-*.md、.claude/skills/、.claude/spec-first/workflows/、.claude/agents/、CLAUDE.md managed block	spec-runtime-setup
Codex	既有支持	.agents/skills/、.codex/agents/、.codex/spec-first/、AGENTS.md managed block	spec-runtime-setup
Kiro	opt-in preview	.kiro/skills/、.kiro/agents/、.kiro/spec-first/state.json、AGENTS.md managed block	spec-runtime-setup
Qoder	opt-in preview	.qoder/commands/spec-*.md、.qoder/skills/、.qoder/agents/、.qoder/spec-first/state.json、AGENTS.md managed block	spec-runtime-setup
Cursor	generated_runtime_preview	.cursor/skills/**、.cursor/spec-first/**、项目级 .cursor/mcp.json、AGENTS.md managed block	spec-runtime-setup
OpenCode	generated_runtime_preview	OpenCode commands/skills 与 .opencode/spec-first/** managed assets	spec-runtime-setup

Kiro、Qoder、Cursor、OpenCode 不进入 init -y 默认宿主集，必须显式 --kiro、--qoder、--cursor 或 --opencode opt-in。Cursor 与 OpenCode 只声明 generated runtime 生成，不声明本地 loader 或完整 user journey 已验证。不要手工同步各宿主 generated assets；需要刷新时重新运行 spec-first init 并选择对应宿主。spec-first update 会升级全局 npm CLI，并尝试重新运行 init 刷新当前项目 runtime；它不是宿主 workflow。

非交互初始化

脚本或 CI 中使用 -y/--yes 跳过提示。未指定宿主时，-y 使用默认宿主集合；需要限定宿主时，再在 CLI reference 中查看显式宿主参数。

spec-first init -y
spec-first init -y -u <name> --lang zh

没有 -y 且当前不是交互式 TTY 时，init 会退出 2，不会静默写入。需要 dry-run 证据或自定义目标选择的自动化集成，应使用源码暴露的 require("spec-first/src/cli/init-plan") programmatic plan API，而不是依赖未公开 CLI flag。

多仓 workspace

在 Git repo 内运行时，init 初始化当前 Git root。在不是 Git repo 的父目录运行且发现 child Git repos 时，交互式流程会让你选择“全部 child repos”或某一个 child：

spec-first init

选择全部 child repos 时，父目录只写 host runtime assets 和 advisory summary，例如 .spec-first/workspace/init-summary.json；每个 child repo 仍拥有自己的 repo-local truth。写代码、测试、review autofix 或 commit 前，计划或任务仍需要明确 target_repo。

postinstall 做什么

bin/postinstall.js 当前只做两件事：

• 检查 Node.js 是否满足 >=20
• 输出安装完成提示和下一步命令

spec-first npm 包自身只有 ignore 和 simple-git 两个 runtime dependencies。当前包不包含 better-sqlite3、Tree-sitter parser、native prebuild 裁剪或本地 graph 数据库构建逻辑。Required MCP servers、helper 与 CodeGraph / Graphify baseline 的 warmup / host config 当前通过宿主内 spec-runtime-setup 执行，不是 npm package postinstall。

平台注意事项

平台 / shell	注意事项
macOS / zsh	确认全局 npm bin 在 PATH 中：通常是 $(npm prefix -g)/bin
Linux / bash	避免用 sudo npm install -g 混合权限；优先使用 nvm、fnm 或 Volta 管理 Node
Windows PowerShell	如果脚本执行被策略拦截，先检查 Get-ExecutionPolicy -List；必要时仅对当前用户调整策略
WSL	推荐在 WSL 内安装 Node、Git、spec-first 和目标宿主，避免 Windows/WSL 路径混用
CI / DevContainer	可以用 npx -y spec-first@latest doctor --json 做只读检查；init 会写文件，放到明确的 setup step 中

常用检查命令

node -v
npm -v
git --version
spec-first --help
spec-first doctor --claude
spec-first doctor --codex

doctor 检查 CLI 安装、managed runtime assets、host readiness 和 workflow verification evidence。MCP/helper 与 CodeGraph / Graphify baseline 由 spec-runtime-setup 处理；provider 输出仍只是辅助事实来源，结论必须回源确认。

下一步

• 快速开始：5 分钟跑通安装、init 和第一个 workflow
• 本地源码安装：贡献者验证未发布改动时使用源码 tarball
• CLI Reference：查看 package CLI 的命令面和参数
• Runtime Setup：准备 MCP servers、CodeGraph / Graphify baseline 和 helper CLIs
• Troubleshooting：按症状排查安装、权限、PATH、MCP 和 provider evidence 问题