什么是 Spec-First
Spec-First 是一个面向 Claude Code 与 Codex 的 workflow CLI。它的核心不是“替模型做决定”，而是先把代码库、需求、计划、评审和经验整理成 结构化、带来源依据的输入，再把这些输入稳定地送给 LLM。
换句话说，Spec-First 关注的是 提高 LLM 的决策输入质量，而不是堆更多 orchestration。
产品定位
按照产品仓库当前 package.json 与 README 的定义，Spec-First 可以概括为：
- 一个用于 spec-driven engineering / development / harness engineering 的 AI coding workflow CLI
- 一个同时覆盖 项目初始化、Stage-0 上下文构建、交付闭环、知识沉淀 的工程方法层
- 一个同时支持 Claude Code
/spec:*与 Codex$spec-*的双宿主交付系统
它到底解决什么问题
Spec-First 试图修复的不是“模型不够聪明”，而是以下几类更常见的问题：
- LLM 直接面对裸代码库，缺少 fact-backed context
- 需求、边界、验收标准只存在于聊天里，没有正式 artifact
- 计划和实现脱节，Review 无法验证“做的是否就是计划中的事”
- 已解决的问题没有进入下一轮上下文，团队反复踩坑
所以它的设计重点变成了三件事：
- 先把代码与项目状态变成结构化上下文
- 再把需求到交付的过程变成可追踪 artifact 链路
- 最后把解决方案沉淀为后续可复用知识
两个互补部分
1. CLI 控制面
根级 spec-first CLI 当前提供 4 个主命令：
spec-first doctorspec-first initspec-first cleanspec-first stage0-context
它们负责环境检查、运行时资产同步、清理，以及在 Plan / Work / Review 阶段输出 Stage-0 运行时上下文。
2. 交付工作流
运行时工作流不是根 CLI 子命令，而是初始化后写入项目的宿主入口：
- Claude Code：
/spec:* - Codex：
$spec-*，并从.agents/skills/发现
当前主工作流是：
text
Ideate → Brainstorm → Plan → Work → Review → Compound在这条主链之前，还存在两个关键前置层：
text
Host Setup → Stage-0 graph bootstrap → 主工作流其中：
spec-mcp-setup负责宿主准备spec-graph-bootstrap负责生成 Phase 0–4 facts、injection-index.yaml与minimal-context/*.json
不是“更多命令”，而是更好的输入
Spec-First 当前 README 明确强调一件事：
- 它不会用状态机替代 LLM 判断
- 它会把
provenance、confidence、fallback_reason、freshness这类质量信号显式暴露出来
这意味着它更像一套“输入质量治理层”：
- graph-bootstrap 负责把代码库编译成可消费上下文
- Brainstorm / Plan / Review / Compound 负责把过程产物结构化
- Stage-0 evaluator 与 verification summary 负责告诉 LLM 当前上下文有多可靠
Claude 与 Codex 的区别
Spec-First 支持双宿主，但两边的运行时表面并不相同：
| 维度 | Claude Code | Codex |
|---|---|---|
| 入口形式 | /spec:* | $spec-* |
| 技能发现位置 | .claude/skills/ | .agents/skills/ |
| 代理位置 | .claude/agents/ | .codex/agents/ |
| 状态文件 | .claude/spec-first/state.json | .codex/spec-first/state.json |
最容易写错的一点是：
- Codex 不是
/spec:* - Codex 运行时 不以
.codex/commands/spec/为主入口
当前可以明确承诺什么
基于产品仓库现状，官网可以明确承诺的内容包括：
- 提供
doctor / init / clean / stage0-context这类 CLI 控制面 - 提供 Host Setup 与 Stage-0 graph bootstrap 入口
- 提供
Ideate → Brainstorm → Plan → Work → Review → Compound六阶段主工作流 - 提供 CRG（Code Review Graph）相关能力与
spec-first crg *子命令体系 - 提供知识沉淀到
docs/solutions/的 compound 路径 - 提供双宿主运行时分发与治理
当前不应承诺什么
同样基于当前源码与 README，官网不应把以下表述写成既成事实：
- “零配置、全自动代码生成”
- “任何团队都适用”
- “只要安装就能直接跳过宿主准备和 Stage-0”
- “Codex 与 Claude 在入口形式上完全一致”
- “官网旧版五阶段表述就是当前唯一官方工作流”
适合谁
- 希望把 prompt-driven coding 升级成可治理交付流程的团队
- 同时使用 Claude Code 与 Codex，想共享一套方法论的开发者
- 需要显式 spec、结构化 review 与可复用知识沉淀的项目
不适合谁
- 不使用 Claude Code / Codex 的团队
- 期待零配置、全自动生成代码的场景
- 任务链路极短，不值得引入多阶段流程开销的场景