概念导览
Spec-First 是面向 Claude Code 与 Codex 的 Node.js CLI + workflow asset package。它把 AI coding 会话中的需求、计划、执行、review 和知识沉淀变成项目内可检查的工程资产。
推荐阅读顺序
| 页面 | 回答的问题 |
|---|---|
| 什么是 Spec-First | 它与 prompt 模板、单纯方法论和 agent 编排工具有什么区别 |
| 三层工程模型 | Prompt / Context / Harness 三层为何 spec-first 选择第三层 |
| 运行模型 | npm CLI + project-local runtime 的资产分类与 Git 边界 |
| 工作流总览 | CLI、setup、graph bootstrap、brainstorm、plan、work、review、compound 如何衔接 |
| Ideate 阶段 | 什么时候先发散候选想法，什么时候直接进入 brainstorm 或 plan |
| 记忆与知识沉淀 | 哪些内容是 durable docs，哪些只是 runtime/control-plane facts |
不同读者的最短路径
| 你是 | 推荐路径 |
|---|---|
| 第一次接触 spec-first | 什么是 Spec-First → 三层工程模型 → 安装指南 |
| 想理解整体架构 | 三层工程模型 → 运行模型 → 工作流总览 |
| 想立刻动手用 | 快速开始 → 完整示例 |
| 想理解知识沉淀 | 记忆与知识沉淀 → Compound 指南 |
当前理解基线
- CLI 只负责确定性动作：
doctor、init、clean、tasks hash和tasks validate。 - Claude Code 使用
/spec:*，Codex 使用$spec-*；入口语法不同，workflow 边界一致。 - setup 和 graph bootstrap 准备事实，不替代 LLM 对需求、方案、实现和 review 的语义判断。
.claude/、.codex/、.agents/skills/是 generated runtime assets；skills/、agents/、templates/和src/cli/才是 source truth。- 长期协作文档（
docs/brainstorms/等）默认提交；本机 control-plane facts（.spec-first/config|graph|impact|providers/）默认不提交。