什么是 Spec-First
Spec-First 是面向 Claude Code、Codex、Kiro、Qoder、Cursor 与 OpenCode 的 Node.js CLI + workflow asset package。其中 Claude Code 与 Codex 是主要支持面，其他宿主按 source catalog 标注为 opt-in preview 或 generated-runtime preview；它不是单纯的方法论文章，也不是只靠 prompt 模板维持的开发习惯，而是一套可以安装到项目里的 workflow runtime。
一句话定义
Spec-First 把 AI coding 的关键中间态写回仓库：需求、计划、任务、实现证据、review 结果和可复用经验都成为项目资产。CLI 负责安装、生成和校验；LLM 与人负责语义判断、工程取舍和最终质量。
| 常见问题 | Spec-First 的回答 |
|---|---|
| 这是不是 prompt 模板库？ | 不是。Prompt 只是入口体验的一部分，Spec-First 重点治理 workflow、artifact 和 review loop。 |
| 会不会替代 Claude Code、Codex 或 preview hosts？ | 不替代。它把同一套 workflow assets 投影到不同宿主里，并明确区分既有支持、preview 与 degraded 边界。 |
| 会不会接管项目构建、测试或 CI？ | 不接管。它读取和调用项目现有工具，把结果作为证据交给 workflow。 |
| 会不会让脚本替代工程判断？ | 不会。脚本只准备确定性事实；需求、方案、实现和评审仍由 LLM 与人决定。 |
Product Shape
Spec-First 把确定性 CLI、宿主 runtime 和 workflow governance 接成一个项目内闭环。
核心定位
Spec-First 负责确定性部分：
- 检查环境与 managed runtime assets：
spec-first doctor - 初始化或清理宿主运行时：
spec-first init、spec-first clean --<host> - 交付 host-specific workflow assets：当前产品面统一使用
spec-*workflow 入口 - 校验 task-pack hash 与结构：
spec-first tasks hash、spec-first tasks validate - 通过 setup 与 provider readiness 形成 readiness facts
- 通过 App audit、skill audit 和 task-pack 校验提升专项 review 输入质量
LLM 仍负责语义判断：需求取舍、方案设计、实现细节、评审结论和质量判断不会被 CLI 硬编码。
最小使用路径
第一次接入一个项目时，最小路径是：
install CLI -> init host runtime -> setup facts -> enter workflow进入 workflow 时不需要从 brainstorm 开始。当前缺什么就补什么：目标不清楚用 brainstorm，方案不清楚用 plan，已有计划用 work，已有 diff 用 code-review，问题已解决且值得复用再 compound。
它解决什么问题
临时 prompt 可以启动一次对话，但很难稳定支撑长期工程：
- 上下文依赖个人记忆，换会话后容易断裂
- 需求、计划、实现、评审之间缺少可检查的边界
- agent 能力分散，入口和责任不清晰
- 经验沉淀难以回流到下一轮任务
Spec-First 把这些能力变成项目级 runtime：入口可安装、资产可更新、readiness 可检查、task-pack 可验证、经验可沉淀。
为什么不是 prompt 工具
Prompt 可以改善单次回答，但不能解决工程链路里的长期问题：事实是否新鲜、计划是否可审查、任务是否可交接、review 是否有证据、经验是否进入下一次循环。Spec-First 的核心判断是：
AI coding is not a prompt problem. It is a workflow problem.
Spec > Code. Systems > Prompts.因此它优先建立 workflow、artifact、runtime 和 evidence 边界，而不是把更多规则塞进一个超级 prompt。
产品组成层
| 层级 | 作用 |
|---|---|
| CLI 层 | 安装、初始化、清理、doctor、task-pack hash/validate |
| Runtime 资产层 | workflow skills、commands、agents、templates 和 host-specific copies |
| Workflow 治理层 | brainstorm、plan、work、debug、code-review、doc-review、app-consistency-audit、write-skill、compound 等宿主入口 |
这是 Spec-First 自身的产品组成。要理解 Spec-First 在 AI 工程方法论中的位置（Prompt / Context / Harness Engineering），见 三层工程模型。
不会做的事
- 不替代 Claude Code、Codex 或其他宿主（宿主级体验由它们提供）
- 不替代 RAG / MCP servers（Context Engineering 工具）
- 不接管现有工具链（不强制使用某个测试框架、构建工具或 CI）
- 不依赖外部 SaaS（runtime 全部 repo-local）
- 不让 LLM 跑
npm install、git push等改变环境的脚本（CLI 拥有这些） - 不让脚本替代设计决策（scope / 方案 / 评审由 LLM 与人类完成）
适合谁
| 用户 | 典型收益 |
|---|---|
| 独立开发者 | 把需求、计划、实现和 review 留在 repo，减少跨会话丢上下文 |
| 小团队 | 用统一 workflow 替代每个人自己的 prompt 和私有经验 |
| 存量项目维护者 | 通过 setup、graph 和 project guidance 降低 AI 误读老代码的概率 |
| AI coding heavy users | 用 task pack、review、compound 把一次性对话变成可复用流程 |
评估是否该引入
如果你的团队已经在 AI coding 中遇到以下任一问题，Spec-First 通常值得引入：
- 同一类需求反复解释，跨会话上下文经常丢失。
- PR review 只能看到改了什么，看不到为什么这样改。
- 大任务需要多人或多个 agent 分工，但缺少清晰交接边界。
- 解决过的工程问题没有沉淀，下次仍从头排查。
- 希望 Claude Code 与 Codex 共享一套项目级 workflow 约定。
不适合的场景
- 只想一次性问答，不需要在项目里留下产物。
- 不能安装 Node.js 20+ 或不能写项目文件。
- 不使用 Claude Code、Codex 或当前 source catalog 支持的宿主。
- 希望工具全自动替代产品、架构、测试和 review 判断。