指南导览
本页按真实研发链路组织官网指南。Spec-First 的核心不是固定阶段列表，而是把 CLI、宿主 runtime、workflow 入口和项目内产物连成可验证的工程闭环。
使用指南时先判断当前缺口，而不是从第一页顺序读完：环境不可信先准备 runtime setup，需求不清先 brainstorm，方案不清先 plan，已有 plan 就 work，已有 diff 就 review，问题解决后再 compound。
Guide Map
从安装到知识沉淀，官网指南按真实研发动作组织，而不是按内部模块堆叠。
01Install安装 CLI，确认 Node、Git、宿主和 init 边界。
02Prepare Codebasesetup、provider evidence、project guidance 建立事实边界。
03Run Workflow从当前缺口进入 brainstorm、plan、work、review。
04Compound把解决过程沉淀为下一次会话能读取的团队知识。
入门
| 页面 | 适合场景 |
|---|---|
| 安装指南 | 安装 spec-first CLI，运行交互式 init 生成宿主 runtime assets |
| 本地源码安装 | 从源码打包本地 tarball，验证未发布改动的 install / init / doctor 链路 |
| 快速开始 | 从 doctor、init 到 setup 和第一个 workflow 的最短路径 |
| CLI Reference | 查看 package CLI 的真实命令面、参数、输出边界和常见错误 |
| 深入解析地图 | 从设计哲学、runtime、workflow、contract、verification 和安全边界理解 spec-first 的完整工程模型 |
| 运行时治理 | 理解 source assets、init plan、managed state、developer profile 和多宿主 runtime 投递 |
| 工作流系统 | 理解需求、计划、任务、执行、调试、优化、评审与知识沉淀之间如何分工 |
| 契约与质量门禁 | 理解 workflow contract、artifact summary、context governance、verification、review finding 和安全边界 |
| 首次工作流走查 | 用一个小需求看清 requirements、plan、task pack、work、review 如何衔接 |
| 完整示例 | 端到端示例：CLI 引导改进的 ideate→brainstorm→plan→work→review→compound 全链路 |
按当前目标选择入口
| 你现在要做什么 | 首选页面 | 进入的 workflow |
|---|---|---|
| 第一次把 spec-first 接入仓库 | 安装指南 → 快速开始 | doctor、init、spec-runtime-setup |
| 想判断一个想法值不值得做 | Ideate 指南 | spec-ideate |
| 需求还散、边界不清楚 | Brainstorm 指南 | spec-brainstorm |
| 存量系统增量需要 PRD 级需求 | PRD 指南 | spec-prd |
| 目标已定，需要实施路径 | Plan 指南 | spec-plan |
| 已有计划，需要改代码和验证 | Work 指南 | spec-work |
| 有明确指标，需要多实验优化 | Optimize 指南 | spec-optimize |
| 页面已可运行，需要边看边打磨 UI | Polish 指南 | spec-polish |
| 已有 diff 或文档，需要质量检查 | Code Review 指南、文档评审入口见 Workflow 总览 | spec-code-review、spec-doc-review |
| 需要查看官网同步的版本更新 | 版本更新 | 源仓库 docs/VERSION/ |
| 问题已解决，想沉淀经验 | Compound 指南 | spec-compound |
准备阶段（Codebase）
进入主链 workflow 前，先把环境、provider readiness 和规范基线准备好；若 setup 降级，必须明确回退到 direct evidence。
Codebase Readiness
准备阶段把“当前项目能提供什么证据”显式写成 facts，后续 workflow 才知道何时增强、何时降级。
CLIdoctor / init检查 CLI、生成 host runtime assets。
Setupspec-runtime-setup准备 MCP、helper tools、CodeGraph / Graphify provider readiness。
Evidenceprovider pack显式 opt-in 后提供候选证据；默认仍以 direct reads 为准。
| 页面 | 适合场景 |
|---|---|
| MCP Setup | 安装并验证 MCP servers、helper CLIs，以及完整 setup 所需的 provider readiness |
| Provider Evidence | 理解 provider evidence 为什么只是增强事实层，不是 source truth |
| Provider Pack | 查看 CodeGraph、Graphify 与 direct reads 的能力边界 |
| Control-plane Artifacts | 查看 .spec-first/config、workspace advisory、provider pack 产物由谁生成、谁消费 |
| Project Guidance Sources | 查看项目规范应由哪些 source docs、contracts、测试和 verified solution docs 承载 |
主链工作流
主链不是强制线性状态机，按当前最匹配的节点进入即可。
Main Workflow
主链路可以从当前最缺的节点进入；关键是每一步都有明确输入、输出和下一步可读的产物。
OptionalIdeate基于代码事实生成候选方向。
SpecBrainstorm / PRD收敛需求，或在存量系统上写清 change delta。
PlanPlan / Tasks拆实施单元、文件范围、风险和验证方式。
CodeWork / Debug在计划边界内改代码、定位 bug、补测试。
ReviewReview / Compound结构化评审，再沉淀可复用经验。
| 页面 | 适合场景 |
|---|---|
| Workflow 命令总览 | 逐个理解 17 个公开 workflow skill 的输入、分支、产物和交接方式 |
| Ideate 指南 | 需要发散候选方向或判断想法质量 |
| Brainstorm 指南 | 目标还不够清楚，需要形成 requirements brief |
| PRD 指南 | 已有系统增量、粗糙 PRD 或产品笔记需要写成 PRD-grade requirements |
| Plan 指南 | 目标已定，需要设计工程路径和验证方式 |
| Work 指南 | 已有 plan 或 task pack，需要执行最小可验证改动 |
| Debug 指南 | 测试失败、stack trace 或异常行为需要先复现再决定修复 |
| Optimize 指南 | 目标可度量，需要受限实验、measurement log 和保留最佳方案 |
| Polish 指南 | 浏览器可见 UI 需要启动 dev server、收集反馈并小步打磨 |
| Code Review 指南 | 合并前对 diff、PR 做结构化代码评审 |
| App 一致性审查 | 移动 App 在运行时验证前需要静态审查 PRD、Figma、source、路由、架构 |
| Compound 指南 | 问题已稳定解决，需要沉淀可复用经验 |
| 版本更新 | 查看官网同步展示的分支版本说明、preview 边界和升级提示 |
工程实践
| 页面 | 适合场景 |
|---|---|
| 深入解析地图 | 已经完成入门，希望系统理解 AI Coding Harness、source/runtime、workflow contract 和证据边界 |
| 运行时治理 | 需要判断 source assets、runtime mirrors、managed state 和多宿主投递边界 |
| 工作流系统 | 需要从证据姿态理解各 workflow 入口的职责和交接方式 |
| 契约与质量门禁 | 需要理解 handoff、verification、review finding、context governance 与安全证据边界 |
| 三种开发模式 | 判断单仓单项目、单仓多模块、多仓工作区下 .spec-first 的权威边界 |
| 产物目录与 Git 边界 | 判断哪些文档、runtime copies 和 .spec-first/ facts 应该提交或忽略 |
| .gitignore 参考 | init 自动维护的 managed block 内容、典型产物树和多仓特殊处理 |
| Best Practices | 新项目、存量项目、团队协作、大需求、review 和 knowledge 的实战建议 |
| Todo 与任务系统 | 大计划需要可交接、可 hash、可 validate 的执行任务包 |
帮助
| 页面 | 适合场景 |
|---|---|
| Troubleshooting | 按症状排查安装、init、doctor、MCP、provider evidence 和平台问题 |
| 常见问题 | 快速确认入口、review 拆分、当前数量事实 |