Spec-First

首次工作流走查 ​

下面用一个小需求展示 Spec-First 的真实使用方式：

text
Improve onboarding for first-time CLI users

目标不是把 workflow 变成固定状态机，而是让每一步都留下下一步能读取的高质量上下文。脚本负责确定性的安装、校验、生成和路径管理；LLM 负责需求判断、范围取舍、计划拆分和实现决策。

0. 准备 runtime ​

首次使用、换宿主、升级后重建 runtime assets，或 MCP/helper 环境变化时，先在目标项目根目录运行：

bash
npm install -g spec-first
spec-first doctor
spec-first init --codex -u <name> --lang zh
# 或
spec-first init --claude -u <name> --lang zh

初始化后重启 Claude Code 或 Codex。宿主 workflow 入口不是 shell 命令；它们在宿主会话里运行。

然后准备 required harness runtime：

目标Claude CodeCodex
安装并验证 MCP/helper runtime/spec:mcp-setup$spec-mcp-setup
编译 graph readiness facts/spec:graph-bootstrap$spec-graph-bootstrap

mcp-setup 负责安装和验证 required MCP servers、graph providers、helper tools 和 setup facts。graph-bootstrap 会基于 setup 产出的 provider 配置，写入 .spec-first/graph/*、.spec-first/providers/* 和 .spec-first/impact/*。如果这些 facts unavailable、stale 或 degraded，后续 workflow 应明确降级到 bounded direct repo reads。

1. Brainstorm 形成需求 ​

text
$spec-brainstorm "Improve onboarding for first-time CLI users"
/spec:brainstorm "Improve onboarding for first-time CLI users"

第一次 brainstorm 通常只生成一个 requirements brief，例如：

text
docs/brainstorms/2026-05-01-001-cli-onboarding-requirements.md

这个文档应该回答用户是谁、当前卡在哪里、哪些需求必须解决、哪些想法不在本轮范围内、成功标准是什么，以及 planning 还要注意哪些边界。

2. Plan 承接工程路径 ​

需求 brief 稳定后进入 plan：

text
$spec-plan
/spec:plan

计划通常写入：

text
docs/plans/2026-05-01-001-feat-cli-onboarding-plan.md

Plan 的职责是把 requirements 转成可评审、可执行的工程决策上下文。它需要说明实施目标、非目标、大致文件区域、依赖关系、风险点、验证方式和 implementation-time 决策空间。

3. 大计划再编译 task pack ​

如果 plan 很小，可以直接进入 work。如果 plan 涉及多个模块、多个阶段或明确交接，可以使用 standalone spec-write-tasks skill，把 plan 编译成 task pack：

text
docs/tasks/2026-05-01-001-feat-cli-onboarding-tasks.md

Task pack 的价值是确定性 handoff：它记录 source plan、hash、task graph、wave 和验证信号。它不是新的需求真相源；plan 变化后应重新编译或验证 freshness。

4. Work 执行最小可验证改动 ​

text
$spec-work
/spec:work

Work 阶段读取当前请求、plan/task pack、AGENTS/CLAUDE 指令、相关源码和测试，完成最小可验证改动。结果通常包括代码或文档 diff、测试或检查命令、验证记录、残余风险说明，以及项目要求的 CHANGELOG.md 记录。

5. 合并前 review，完成后 compound ​

合并前运行：

text
$spec-code-review
/spec:code-review

如果评审对象是需求、计划、任务包或文档，使用：

text
$spec-doc-review
/spec:doc-review

当问题被稳定解决，并且经验值得复用时，再运行：

text
$spec-compound
/spec:compound

Compound 适合把真实任务、真实 diff、真实测试和真实决策沉淀到 docs/solutions/，供后续会话复用。

常见判断 ​

情况推荐入口
只有一句想法，还没定义成功标准$spec-brainstorm / /spec:brainstorm
需求已清楚，但不知道怎么落地$spec-plan / /spec:plan
已有 plan 或 task pack$spec-work / /spec:work
实现失败或测试报错$spec-debug / /spec:debug
准备合并，想确认风险$spec-code-review / /spec:code-review
移动 App 改动需要 QA 前静态一致性检查$spec-app-consistency-audit / /spec:app-consistency-audit
父 workspace 下准备多仓环境$spec-mcp-setup 后 $spec-graph-bootstrap

关键边界 ​

  • docs/brainstorms/、docs/plans/、docs/tasks/ 和 docs/solutions/ 是长期协作文档层。
  • .claude/、.codex/ 和 .agents/skills/ 是 generated runtime assets，不是 source truth。
  • skills/、agents/、templates/ 和 src/cli/ 才是 Spec-First 自身能力的源码真相源。
  • .spec-first/workspace/ 是父 workspace advisory summary，不是 child repo 的 canonical truth。

下一步 ​