Intent → Spec → Plan → Tasks → Code → Review → Knowledge

为什么使用 spec-first？

30 秒理解

AI coding 宿主擅长生成和修改代码，但一次会话结束后，意图、范围、取舍、验证证据和未决风险很容易丢失。spec-first 将这些内容保留在项目边界内，并让不同宿主可以消费同一套 spec-* workflow 入口。

你可以把它理解为三层协作：

• 宿主负责模型、工具、权限和代码执行。
• spec-first负责连接 intent、context、scope、artifact、claim、evidence 和 handoff。
• 项目 owner负责价值判断、授权副作用和最终语义验收。

你会得到什么

快速开始

需要 Node.js >=20.0.0、npm、Git，以及至少一个受支持的 AI coding 宿主。以下命令在目标 Git 仓库根目录执行。

1. 安装并初始化

npm install -g spec-first
cd <your-repository>
spec-first quickstart

quickstart 会检查 Node.js、Git 和已安装的宿主 CLI，并进入初始化流程。选择宿主后，重启已选择的宿主，使其发现生成的入口。

需要脚本化或显式指定宿主时：

spec-first doctor
spec-first init --codex -y -u <name> --lang <zh|en>

初始化会在写入前预览受管 runtime 文件；它不会自动 stage 或提交文件。多宿主、非 Git 目录、dry-run 和 preview 宿主用法见完整快速开始指南。

2. 首次运行 workflow

在宿主会话中运行（这些不是 shell 子命令）。首次 workflow 前先准备 runtime；后续在 readiness 或配置变化时重跑：

spec-runtime-setup

随后生成第一个需求产物：

spec-brainstorm "改进 CLI 新用户 onboarding"

这会把模糊想法收敛为可审查的 requirements artifact，通常位于：

docs/plans/YYYY-MM-DD-NNN-<type>-<topic>-plan.md

如果需求已经明确，可直接使用 spec-plan；准备执行时使用 spec-work。如果没有值得持久化的决策，workflow 可以合法地不创建文档；这不表示运行失败。

找不到入口时，运行 spec-first doctor --verbose，并核对 Runtime Capability Catalog 中的宿主限制。

选择合适的 Workflow

研发主流程

按当前任务进入一项即可，不要求从头依次运行。以下是能力地图，后续步骤由当前任务、验证结果和授权决定。

按需使用的研发能力

产品反馈与发布配套能力：spec-sweep 扫描已配置反馈源，spec-product-pulse 汇总时间窗内产品信号，spec-riffrec-feedback-analysis 分析指定反馈采集，spec-promote 为已交付功能起草推广文案。它们不自动获得外发或发布权限。

内部辅助 Skill

以下 Skill 由持有相应授权的 workflow 按需调用，不是推荐给用户直接运行的研发入口：

不确定从哪里开始时，由 using-spec-first 选择一个最匹配入口。上述 Skill 在宿主会话中使用，不是 spec-first 的 shell 子命令；具体调用形式以宿主发现的入口为准。完整边界见公开入口与 Skill 目录。

从 Prompt 到可信变更

粗略想法 -> spec-brainstorm --\
已有 PRD -> spec-prd ----------+-> spec-plan -> [spec-write-tasks] -> spec-work -> spec-code-review -> spec-compound

spec-prd 是已有 PRD 或 brownfield 请求的替代入口；spec-doc-review 是跨阶段的可选 review lane，可审查 requirements、plan 或 task pack。

一个完整的最小路径

粗略想法
  → spec-brainstorm
  → spec-plan
  → spec-work
  → spec-code-review
  → spec-compound（有合格经验时）

例如：

spec-brainstorm "为 CLI 增加配置导入"
# 审查 docs/plans/ 中的 requirements-only plan
spec-plan <plan-path>
# 执行 implementation-ready plan
spec-work <plan-path>

每个 workflow 都会说明它是否创建 artifact、是否修改源码以及需要哪些验证。不要把“模型说已完成”当作现场结果；以可回源的命令、日志、测试或 owner evidence 为准。

仓库会留下什么

项目会留下什么

docs/
  ideation/      spec-ideate 的方向探索
  brainstorms/   spec-prd 的澄清产物
  plans/         requirements-only 与 implementation-ready plans
  tasks/         从 plan 派生的可选 task packs
  solutions/     已验证且可复用的工程经验
  validation/    测试、审查和现场验证证据
.spec-first/
  workflows/     条件式验证证据（默认 gitignore）

这些目录中的 artifact 只证明其直接证据覆盖的 claim。宿主 runtime assets 是可重建的 delivery projection，不是 canonical source；行为修改应回到 skills/、templates/、src/cli/ 和 checked-in docs，再用 spec-first init 刷新投影。

信任如何建立

spec-first 遵循一条简单分工：脚本准备事实，LLM 做语义判断，项目 owner 授权副作用。

• 完成声明的范围不能超过证据直接支持的范围。
• mutation、verification、handoff、source/runtime 和 knowledge 出口有明确边界。
• provider 和历史 artifact 默认是带 provenance、freshness 与 limitation 的 advisory input，进入结论前需要回源确认。
• 长时或高影响工作需要 scope、checkpoint、停止条件、恢复点和独立验证。

完整原则见项目角色契约、Source/Runtime 边界、Verification Summary 合同和 Honest Closeout 合同。

宿主支持

生成 runtime、宿主发现入口和真实 workflow 验证是不同层次。运行 spec-first doctor --verbose 查看当前项目事实；详细状态以Runtime Capability Catalog为准。

适用边界

适合以下团队：

• 已经使用 AI coding 宿主；
• 需要跨会话或跨宿主保留意图和交接；
• 需要计划、review 和验证证据；
• 希望将合格经验沉淀回项目。

以下情况通常不需要它：

• 只想复制一次性 prompt；
• 不允许仓库保存 workflow artifact；
• 需要独立 IDE 或中心化流程引擎；
• 希望工具替项目 owner 决定产品优先级和架构。

CLI 参考

spec-first quickstart  # 检查前置条件并进入 init
spec-first doctor      # 检查环境和 runtime 健康状态
spec-first init        # 生成所选宿主的 runtime assets
spec-first update      # 升级 CLI 并刷新 runtime assets
spec-first clean       # 移除所选 generated runtime assets
spec-first plans audit --status completed --json

运行 spec-first --help 查看全部选项。

开发与贡献

npm run typecheck
npm run test:unit
npm run test:smoke
npm run test:integration
npm run test:release
npm run build

源码变更应发生在 canonical source surfaces。只有 runtime source 变化时，才通过 spec-first init 重新生成 runtime copies。更多信息见贡献指南、安全策略、版本记录和 GitHub Issues。

项目使用 MIT License。

相关文档

• 用户手册
• Runtime Capability Catalog
• 项目角色契约

加入社区

• GitHub Issues
• 官方网站