首次工作流走查

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

Improve onboarding for first-time CLI users

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

First Workflow Walkthrough

小需求也按真实工程闭环走：先准备 runtime，再把需求、计划、执行、评审和知识沉淀串起来。

Runtimedoctor / init / setup确认宿主 runtime 与 provider facts。

→

Specbrainstorm把一句想法变成 requirements brief。

→

Planplan / tasks形成实施单元、验证方式和交接边界。

→

Closework / review / compound完成最小改动、合并前评审、沉淀复用经验。

0. 准备 runtime

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

npm install -g spec-first
spec-first doctor
spec-first init

初始化后重启当前宿主或开启新会话。宿主 workflow 入口不是 shell 命令；它们在宿主会话里运行。

然后准备 required harness runtime：

目标	当前入口	说明
安装并验证 MCP/helper runtime	spec-runtime-setup	Claude/Qoder 命令拼写 runtime-setup；Codex/OpenCode skill/command 面为 spec-runtime-setup

runtime-setup 负责安装和验证 required MCP servers、helper tools、CodeGraph / Graphify baseline 和 setup facts。完整 setup 未 ready 时，后续普通 workflow 仍可明确使用 bounded direct source reads、rg、ast-grep、git diff、测试日志和用户证据，但不得把 setup 结果包装为 complete。

1. Brainstorm 形成需求

spec-brainstorm "Improve onboarding for first-time CLI users"

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

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

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

2. Plan 承接工程路径

需求 brief 稳定后进入 plan：

spec-plan

计划通常写入：

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：

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

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

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

spec-work

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

5. 合并前 review，完成后 compound

合并前运行：

spec-code-review

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

spec-doc-review

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

spec-compound

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

常见判断

情况	推荐入口
只有一句想法，还没定义成功标准	spec-brainstorm
已有系统的一次增量需要 PRD 级需求	spec-prd
需求已清楚，但不知道怎么落地	spec-plan
已有 plan 或 task pack	spec-work
实现失败或测试报错	spec-debug
准备合并，想确认风险	spec-code-review
移动 App 改动需要 QA 前静态一致性检查	spec-app-consistency-audit
父 workspace 下准备多仓环境	spec-runtime-setup --repo <child> 或 spec-runtime-setup --all-repos

关键边界

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

下一步

• 完整示例：含 ideate / compound / sessions 的端到端链路
• Workflow 命令总览：17 个公开 workflow 的执行流程图
• 产物目录与 Git 边界：每类产物由谁生成、如何提交
• 三种开发模式：单仓单项目 / 单仓多模块 / 多仓工作区