概念导览
Spec-First 是面向 Claude Code、Codex 与 preview hosts 的 Node.js CLI + workflow asset package。它把 AI coding 会话中的需求、计划、执行、review 和知识沉淀变成项目内可检查的工程资产。
本栏目先回答三件事：Spec-First 到底是什么、它在 AI 工程分层里解决哪一层问题、它把哪些文件当作 source truth 或 generated runtime。理解这三点后，再读指南页会更容易判断自己该从 setup、plan、work 还是 review 进入。
Concept Map
从产品定位到落地使用，先建立正确心智，再进入指南。
StartSpec-Firstrepo-local workflow runtime for six supported hosts
→推荐阅读顺序
| 页面 | 回答的问题 |
|---|---|
| 什么是 Spec-First | 它与 prompt 模板、单纯方法论和 agent 编排工具有什么区别 |
| 三层工程模型 | Prompt / Context / Harness 三层为何 spec-first 选择第三层 |
| 运行模型 | npm CLI + project-local runtime 的资产分类与 Git 边界 |
| 工作流总览 | CLI、setup、provider evidence、brainstorm/prd、plan、work、review、compound 如何衔接 |
| Ideate 阶段 | 什么时候先发散候选想法，什么时候直接进入 brainstorm 或 plan |
| 记忆与知识沉淀 | 哪些内容是 durable docs，哪些只是 runtime/control-plane facts |
| 深入解析地图 | 从最新工程资料整理出的设计哲学、运行时、工作流、契约质量和安全边界地图 |
读完应该能判断
- 当前任务缺的是事实、需求、计划、实现、评审还是知识沉淀。
- 哪些资产应该改 source，哪些 generated runtime 只能由
init重建。 - 哪些事实由 CLI 或 provider 生成，哪些判断必须留给 LLM 与人。
- 哪些产物应提交给团队复用，哪些
.spec-first/facts 只是本机运行时状态。
不同读者的最短路径
| 你是 | 推荐路径 |
|---|---|
| 第一次接触 spec-first | 什么是 Spec-First → 三层工程模型 → 安装指南 |
| 想理解整体架构 | 三层工程模型 → 运行模型 → 工作流总览 |
| 想理解治理边界 | 运行模型 → 工作流总览 → 深入解析地图 |
| 想立刻动手用 | 快速开始 → 完整示例 |
| 想理解知识沉淀 | 记忆与知识沉淀 → Compound 指南 |
当前理解基线
- CLI 只负责确定性动作：
doctor、quickstart、init、update、clean、repair-worktree、tasks、plans和session。 - 当前产品面统一使用
spec-*workflow 入口；不同宿主只在 runtime 投递形态上不同。 - setup 和 provider readiness 准备事实，不替代 LLM 对需求、方案、实现和 review 的语义判断。
.claude/、.codex/、.agents/skills/是 generated runtime assets；skills/（含 skill-localreferences/agents）、templates/和src/cli/才是 source truth。- 长期协作文档（
docs/brainstorms/等）默认提交；本机 control-plane facts（.spec-first/config|workspace|sessions|providers/）默认不提交。