安装指南

Spec-First 当前以 npm 包形式发布。安装包提供根级 spec-first CLI，再通过 init 把 host-filtered runtime assets 写入具体项目。

前置要求

• Node.js >= 20
• Git
• 一个 Git 仓库
• 至少安装一个目标宿主：Claude Code 或 Codex

spec-first init 会写入项目文件；建议先确认工作树状态，避免把生成资产和你自己的未提交修改混在一起。

1. 安装 package CLI

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

如果只想查看命令面：

spec-first --help

2. 检查环境

spec-first doctor

也可以限定宿主范围：

spec-first doctor --claude
spec-first doctor --codex

doctor 会检查环境、manifest 和 managed runtime assets；它不会替代宿主内的 setup workflow。

3. 初始化项目

进入目标 Git 仓库后，按实际使用的宿主运行：

spec-first init --claude -u <name> --lang zh
spec-first init --codex -u <name> --lang zh

只使用 Claude Code 时只运行 --claude；只使用 Codex 时只运行 --codex；同一仓库要支持两个宿主时才两个都运行。

4. 初始化后做什么

初始化生成的是宿主可加载的 runtime assets。你需要重启宿主或打开新会话，然后在宿主里运行对应入口：

目标	Claude Code	Codex
安装并验证 harness runtime	/spec:mcp-setup	$spec-mcp-setup
编译 graph readiness facts	/spec:graph-bootstrap	$spec-graph-bootstrap
编译项目规范与 glue baseline	/spec:standards	$spec-standards
更新 spec-first/runtime assets	/spec:update	$spec-update

不要把这些宿主入口当成 package CLI 子命令；spec-first CLI 只负责安装、清理、检查和 task-pack 校验等确定性操作。

根级 CLI 命令

命令	用途
spec-first --help	查看 package CLI 命令面
spec-first --version	查看当前版本与快速提示
`spec-first doctor [--json] [--claude	--codex]`
`spec-first init (--claude	--codex) [-u NAME] [--lang zh
`spec-first clean (--claude	--codex) [--dry-run]`
spec-first tasks hash PLAN_PATH [--json]	计算计划文件 hash，用于 task-pack 追踪
spec-first tasks validate TASK_PACK_PATH [--json] [--repo PATH]	校验 task-pack 与仓库上下文

Runtime assets 写入位置

层级	当前 contract
源码资产	上游 skills/、agents/、templates/、src/cli/ 是编辑真源
Claude runtime	.claude/commands/spec、.claude/skills、.claude/spec-first/workflows、.claude/agents、.claude/spec-first/state.json
Codex runtime	.agents/skills、.codex/agents、.codex/spec-first/state.json

生成副本可被 init 或 update 覆盖；需要改能力时应修改上游源码资产，而不是直接修改 runtime copies。

当前源码内置 42 个 source skill definitions（含 using-spec-first meta skill）、21 个 workflow command templates 和 51 个 source agent profiles。Codex init 会生成 25 个 .agents/skills runtime directories 与 51 个 .codex/agents files；Claude Code 会生成 21 个 /spec:* commands 及对应 workflow/standalone/internal skill copies。

清理 runtime assets

spec-first clean --claude
spec-first clean --codex

清理命令只面向 spec-first managed assets。执行前仍应确认工作树状态，避免误把本地未提交工作混入生成资产差异。

下一步

你想	推荐去
用最短路径跑通第一个 workflow	快速开始
用一个真实需求体验完整链路	首次工作流走查
看端到端示例（含 ideate / brainstorm / plan / work / review / compound）	完整示例
配置 .gitignore	.gitignore 参考
理解资产分类与 Git 边界	产物目录与 Git 边界