工作流概览

本页统一用“Claude Code /spec:*”示例说明；如果你使用 Codex，请把对应入口理解为 $spec-*。Codex 的 runtime 入口来自 .agents/skills/，不是 /spec:*。

Spec-First 当前不是“直接从 Brainstorm 开始”的单链条工具，而是一个分层 workflow：

Host Setup → Stage-0 graph bootstrap → Ideate → Brainstorm → Plan → Work → Review → Compound

其中前两层负责 让上下文先变可靠，后六层负责 把需求变成可交付结果并沉淀知识。

---

第 0 层：宿主准备

spec-mcp-setup

在进入任何 graph-bootstrap 或主工作流前，先完成宿主准备：

• Claude Code：/spec:mcp-setup
• Codex：$spec-mcp-setup

它的职责不是产出功能文档，而是确保宿主、MCP 和运行环境准备完成。产品 README 里把这一步视为 bootstrap gate 的前置条件。

---

第 0.5 层：Stage-0 graph bootstrap

spec-graph-bootstrap

这是官网此前最容易遗漏的一层。它当前是主要的 Stage-0 入口，用来生成：

• Phase 0–4 facts
• injection-index.yaml
• minimal-context/*.json

它的目标是把“裸代码库”先编译成带 provenance、confidence、fallback_reason 的结构化上下文，再供后续 workflow 消费。

如果你跳过这一步，后续 Plan / Work / Review 就失去最关键的事实基线。

---

六阶段主工作流

1. Ideate

适用于“还不确定要做什么”。

• 输入：可选聚焦提示
• 输出：docs/ideation/*.md
• 作用：从真实代码库扫描结果中提出值得做的方向

2. Brainstorm

适用于“知道大概方向，但需求边界还不够清晰”。

• 输入：想法、目标或问题
• 输出：docs/brainstorms/*.md
• 作用：澄清目标、约束、非目标与验收标准

3. Plan

适用于“需求已经明确，需要把它变成执行计划”。

• 输入：需求文档或清晰目标
• 输出：docs/plans/*.md
• 作用：明确文件范围、风险、验证、Implementation Units 与 Scope Boundaries

4. Work

适用于“计划已就绪，开始实现”。

• 输入：计划文档
• 输出：代码、测试及必要文档更新
• 作用：按计划执行，而不是边做边重新发明流程

5. Review

适用于“实现已完成，需要结构化评审”。

• 输入：代码变更，可选 plan: 对照
• 输出：结构化评审报告
• 作用：从 correctness、testing、maintainability、risk 等角度检查变更

6. Compound

适用于“本轮已经解决问题，希望把经验留给下一轮”。

• 输入：已解决的问题与方案
• 输出：docs/solutions/**/*.md
• 作用：把最佳实践、根因和解决方案写成可检索知识

---

阶段顺序与跳转

并不是每次都要从第一步走到最后一步。当前产品 README 明确支持按任务状态切入：

• 方向不清楚：从 Ideate 开始
• 需求不清楚：从 Brainstorm 开始
• 需求清楚：直接进入 Plan
• 计划已存在：直接进入 Work
• 代码已完成：直接进入 Review
• 只是要沉淀经验：直接进入 Compound

但如果要拿到最可靠的输入，仍然建议优先完成：

Host Setup → Stage-0 graph bootstrap

---

输入与产物

层级 / 阶段	主要输入	主要输出
Host Setup	当前宿主环境	宿主 marker
Stage-0 graph bootstrap	代码库	facts + injection-index.yaml + minimal-context/*.json
Ideate	聚焦提示	docs/ideation/*.md
Brainstorm	想法 / 问题	docs/brainstorms/*.md
Plan	需求文档	docs/plans/*.md
Work	计划文档	代码 + 测试
Review	代码变更	结构化评审报告
Compound	已解决问题	docs/solutions/**/*.md

---

Claude 与 Codex 的入口对照

阶段	Claude Code	Codex
Host Setup	/spec:mcp-setup	$spec-mcp-setup
Stage-0	/spec:graph-bootstrap	$spec-graph-bootstrap
Ideate	/spec:ideate	$spec-ideate
Brainstorm	/spec:brainstorm	$spec-brainstorm
Plan	/spec:plan	$spec-plan
Work	/spec:work	$spec-work
Review	/spec:review	$spec-review
Compound	/spec:compound	$spec-compound

---

不要再混淆的两件事

1. 根 CLI 与 workflow 入口不是一回事

根 CLI 是：

spec-first doctor
spec-first init --claude
spec-first clean --claude
spec-first stage0-context --stage plan --workflow spec-plan --format json

而 /spec:* 或 $spec-* 是初始化后写入项目的 runtime workflow 入口。

2. Codex 不是 /spec:*

官网旧文档里最常见的错误，就是把 Codex 也写成 /spec:*。当前产品实现已经明确区分：

• Claude：/spec:*
• Codex：$spec-*

---

推荐启动路径

首次接入

安装 CLI → doctor → init → 重启宿主 → spec-mcp-setup → spec-graph-bootstrap

日常需求交付

Ideate（可选）→ Brainstorm → Plan → Work → Review → Compound

---

下一步

• 安装指南
• 快速开始
• Review 详细指南
• Skills 生态