完整示例

下面用一个具体需求走完一次端到端 workflow 链路。示例中的入口同时给出 Claude Code 与 Codex 两种语法。

场景：为 CLI 增加首次使用引导

这是一个典型的中小型功能：用户群明确（首次使用者）、需求边界相对清晰、改动跨多个产物（文档 + CLI 输出 + 测试）。用它走完一次 spec-first 链路恰好能覆盖所有阶段。

步骤 0：准备运行环境与 graph readiness

第一次使用、换宿主、升级后或 MCP/helper 环境变化时，先在终端里完成 CLI 与宿主初始化：

spec-first doctor
spec-first init --claude -u <name> --lang zh
# 或
spec-first init --codex -u <name> --lang zh

重启 Claude Code 或 Codex 后，在宿主会话里准备 required harness runtime 与 graph readiness：

/spec:mcp-setup
/spec:graph-bootstrap

$spec-mcp-setup
$spec-graph-bootstrap

mcp-setup 会安装并验证 required MCP servers、graph providers、agent-browser 等 helpers，写入 .spec-first/config/。graph-bootstrap 编译 canonical graph readiness 与 impact capability envelope 到 .spec-first/graph/ 与 .spec-first/impact/。

如果项目是 brownfield 或团队协作场景，可以接着运行：

/spec:standards
$spec-standards

它会在 .spec-first/standards/ 写候选规范、glue/reuse capability baseline 与 freshness decision。confirmed 候选才会成为后续硬约束。

步骤 1：Ideate（可选）

如果你只有一句模糊想法，先用 ideate 发散候选：

/spec:ideate "改善 CLI 首次使用体验"
$spec-ideate "改善 CLI 首次使用体验"

ideate 会基于 repo facts、graph、standards 和外部线索给出候选方向，并按价值/风险/复杂度排序。产物写入：

docs/ideation/2026-05-07-cli-onboarding-ideation.md

如果你已经知道要做什么，可以跳过这一步，直接进入 brainstorm。

步骤 2：Brainstorm 形成需求 brief

/spec:brainstorm "改善 CLI 首次使用引导：spec-first init 后给出明确下一步"
$spec-brainstorm "改善 CLI 首次使用引导：spec-first init 后给出明确下一步"

brainstorm 通过对话收敛：

• 谁是用户：第一次安装 spec-first 的开发者
• 关键问题：init 后用户不知道接下来该 /spec:mcp-setup，还是 /spec:standards，还是直接进入 brainstorm
• 关键流程：init → 重启宿主 → 第一次进入会话 → 看到下一步指引
• 范围边界：本轮只改 init 输出与文档；不改宿主入口治理逻辑
• 验收样例：init 末尾输出包含具体下一步命令、对应宿主语法

产物：

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

可选：用 /spec:doc-review 对 requirements 做语义审查，确保 actors、key flows、scope 清楚。

步骤 3：Plan 落到实施单元

/spec:plan
$spec-plan

plan 把需求转成可执行单元：

• U1：在 src/cli/commands/init.js 的成功输出里加下一步指引段
• U2：根据宿主类型（claude/codex）显示对应入口语法
• U3：更新 README.md 与官网 installation.md 同步引导文字
• U4：补充 init 输出测试

产物：

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

如果计划较大或需要并行执行，可以再用 standalone spec-write-tasks skill 把 plan 编译成 task pack：

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

spec-write-tasks 不是 /spec:* 或 $spec-* command；它是 standalone handoff skill，保持 plan 为单一真源。

步骤 4：Work 执行最小可验证改动

/spec:work docs/plans/2026-05-07-001-feat-cli-onboarding-plan.md
$spec-work docs/plans/2026-05-07-001-feat-cli-onboarding-plan.md

work 阶段读取计划、相关源码与测试，按单元顺序执行：

• 修改 src/cli/commands/init.js 添加下一步指引输出
• 修改 README / installation 同步文档
• 添加单元测试
• 运行测试 → 验证通过
• 同步在 CHANGELOG.md 加一条记录（项目铁律）

如果中途遇到 bug，可以切到 debug：

/spec:debug "init 在 windows powershell 下输出乱码"
$spec-debug "init 在 windows powershell 下输出乱码"

debug 会先复现、定位根因，再决定是否进入修复。

步骤 5：Review

合并前对 diff 做代码评审：

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

code-review 会调度 6 类 always-on personas（correctness / testing / maintainability / project-standards / agent-native / learnings-researcher），并按 diff 触发条件 reviewer（security / performance / API contract / migration / reliability / CLI / stack-specific）。

产物：

• findings.json（结构化问题）
• safe_auto fixes（安全的自动修复）
• residual risks（遗留风险与建议）

如果评审对象是需求/计划/任务包：

/spec:doc-review docs/plans/2026-05-07-001-feat-cli-onboarding-plan.md
$spec-doc-review docs/plans/2026-05-07-001-feat-cli-onboarding-plan.md

doc-review 调度 always-on coherence + feasibility，并按文档信号启用 product / design / security / scope / adversarial reviewers。

步骤 6：Compound 沉淀经验

当问题被稳定解决、值得复用时：

/spec:compound
$spec-compound

compound 会并行 Context Analyzer / Solution Extractor / Related Docs Finder（必要时加 Session Historian），写入：

docs/solutions/<category>/cli-onboarding-2026-05-07.md

下一次 AI Coding 时 spec-learnings-researcher 会自动检索并把相关历史经验带入 reviewer 视野。

步骤 7（可选）：Sessions 回看

如果你接手别人的工作或自己也忘了之前怎么调查的：

/spec:sessions "之前怎么调查过 cli onboarding 的？"
$spec-sessions "之前怎么调查过 cli onboarding 的？"

sessions 会基于当前仓库和分支检索 Claude Code / Codex 的会话历史，给出尝试过的路线、关键决策和已知失败。

产物总览

走完整条链路后，仓库里会留下：

docs/ideation/2026-05-07-cli-onboarding-ideation.md
docs/brainstorms/2026-05-07-001-cli-onboarding-requirements.md
docs/plans/2026-05-07-001-feat-cli-onboarding-plan.md
docs/tasks/2026-05-07-001-feat-cli-onboarding-tasks.md          # 可选
docs/solutions/cli/onboarding-2026-05-07.md                     # compound 后
git commits（带 spec_id）
.spec-first/config/*                                            # 本机 control-plane
.spec-first/graph/*                                              # 本机 graph readiness

下次类似需求出现时，AI 不再从零开始：它会读到上一次的 requirements、plan、solution，并自动把过往经验作为评审与设计输入。

关键边界回顾

类型	位置	是否提交
长期协作文档	docs/brainstorms/ docs/plans/ docs/tasks/ docs/solutions/ docs/ideation/	通常提交
Generated runtime	.claude/ .codex/ .agents/skills/	不提交（init 自动加 .gitignore）
Control-plane facts	.spec-first/config/ .spec-first/graph/ .spec-first/impact/ .spec-first/providers/	不提交，本机重建
Standards baseline	.spec-first/standards/	部分（confirmed 候选可提交）

更详细的产物分类与 Git 策略见 产物目录与 Git 边界。

阅读下一步

• Workflow 命令总览：21 个命令的执行流程图
• Skills 参考：每个 skill 的契约式信息
• Compound 指南：本示例最后一步的深入说明
• 产物目录与 Git 边界：哪些产物提交、哪些不提交