快速开始 ​

本页展示从安装到首次进入 spec-first workflow runtime 的最短路径。主路径是先完成 CLI 与宿主 runtime 初始化；docs、小修复、首次试用等轻量任务可以直接进入对应 workflow，跨模块、provider-heavy 或高风险任务再补 setup。

5 Minute Path

先验证 CLI 和宿主 runtime，再由 setup 准备 MCP、helper 与 provider readiness。

01Installnpm install -g spec-first 后运行 doctor。
02Init Host运行交互式 init，选择要生成的宿主 runtime assets。
03Choose Path轻量任务直接 workflow；复杂任务先补 readiness。
04Run Workflow从 ideate、brainstorm、prd、plan、work 或 review 进入当前任务。
spec-first doctorspec-first initspec-first init -yspec-runtime-setup

前置条件 ​

  • Node.js >=20
  • Git 与一个目标 Git 仓库
  • 已安装 Claude Code、Codex 或一个明确 opt-in 的 preview host
  • 在目标 repo 根目录运行命令

快速开始的成功标准 ​

跑完本页后，你应该得到三类结果：

  • spec-first doctor 能识别 CLI、Node、Git 和宿主 runtime 状态。
  • spec-first init 已把对应宿主入口生成到项目本地，并写入 developer profile。
  • 轻量 workflow 可在宿主重启后直接启动；需要增强证据时，setup 会写出 readiness facts，后续 workflow 知道当前 MCP/helper/provider evidence 是否可用、是否需要降级。

1. 安装并检查 CLI ​

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

2. 按宿主初始化项目 ​

bash
spec-first init

交互式流程会让你选择 Claude Code、Codex，或显式 opt-in 的 Kiro/Qoder/Cursor/OpenCode preview host，确认姓名和语言、预览写入内容并确认。自动化脚本可以使用：

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

平时优先用交互式 spec-first init 选择宿主；自动化脚本需要限定单个宿主时，才添加 --claude、--codex、--kiro、--qoder、--cursor 或 --opencode。Kiro、Qoder、Cursor、OpenCode 都是 preview，不进入 init -y 默认宿主集。

3. 重启宿主并完成 readiness ​

步骤当前入口说明
宿主 setupspec-runtime-setupClaude/Qoder 命令拼写 runtime-setup；无历史兼容别名；preview hosts 使用同名 spec-* runtime surface
升级 CLI 并刷新 runtimespec-first updatepackage CLI 会升级全局 npm 包并尝试重新运行 init

setup workflow 负责安装并验证 required MCP servers、helper CLIs、CodeGraph / Graphify baseline 和项目 setup facts。完整 setup 未 ready 时，普通 workflow 可回退 direct source evidence，但项目规范和团队约定仍应放在 AGENTS.md、CLAUDE.md、docs/contracts/**、README、测试和已验证 solution docs 中。

如果当前只是 docs-only、小修复、首次试用或轻量 plan/work/review，可以在重启宿主后直接进入匹配 workflow，并在输出中说明 setup/provider evidence 的限制。

4. 进入工作流 ​

意图当前入口
生成和筛选想法spec-ideate
澄清需求spec-brainstorm
存量系统增量 PRDspec-prd
写计划spec-plan
编译 task packspec-write-tasks
执行实现spec-work
调试问题spec-debug
度量优化spec-optimize
UI 打磨spec-polish
代码评审spec-code-review
文档/计划评审spec-doc-review
移动 App 静态一致性审查spec-app-consistency-audit
自主浏览器 dogfood QAspec-dogfood
知识沉淀spec-compound
刷新过期知识spec-compound-refresh

不需要一次跑完整条链路。真实任务通常从当前缺口进入：缺需求用 brainstorm，缺方案用 plan，已有计划用 work，已有 diff 用 code-review，环境或 provider evidence 不可信时先回到 setup。

5. 验证 task pack ​

当 plan 被拆成 task pack 后，可以用 package CLI 做确定性校验：

bash
spec-first tasks hash docs/plans/<plan>.md
spec-first tasks validate docs/tasks/<task-pack>.md --repo .

CLI 校验结构和 hash；具体实现取舍、测试判断和 review 结论仍由宿主 workflow 与 LLM 完成。

推荐第一条路径 ​

  1. spec-first doctor
  2. spec-first init
  3. 重启宿主
  4. 运行当前宿主的 spec-runtime-setup
  5. 复杂存量项目可先补齐 AGENTS.md / CLAUDE.md / docs/contracts/** 等项目说明，必要时在 setup 中显式启用 provider pack
  6. 用 brainstorm/prd/plan/work/review 进入具体任务；移动 App 或 skill 维护场景再插入 app-consistency-audit 或 write-skill

下一步 ​