Best Practices

Spec-First 的价值不在于多跑命令，而在于把 AI coding 的关键判断显式化：事实从哪里来、scope 怎么定、计划如何执行、review 看什么、经验如何回流。

新项目接入

1. 先安装并初始化宿主。

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

2. 重启宿主，先跑 setup。

spec-runtime-setup

3. 第一个需求从 brainstorm 或 plan 开始。需求不清楚时先 brainstorm；目标清楚但 HOW 不清楚时 plan。

存量项目接入

存量项目先补 runtime setup、项目说明和必要的 provider evidence，再进入具体 feature。

spec-runtime-setup
spec-brainstorm 或 spec-plan

Provider evidence 不 ready 时，不要强行把它当硬事实。让 workflow 说明 degraded 状态，并补直接源码读取。项目规范应维护在 AGENTS.md、CLAUDE.md、docs/contracts/** 或已验证 solution docs 中。

小团队如何使用

场景	推荐
一个人快速交付	brainstorm 可轻量，plan 要写清文件和验证
两三人协作	requirements、plan、review findings 建议提交
多人维护同一模块	用 AGENTS.md / CLAUDE.md / docs/contracts/** 固化项目规则，用 compound 沉淀稳定解法
新成员接手	先读 docs/plans/、docs/solutions/ 和最近 review findings

大需求如何拆分

大需求不要直接丢给 spec-work。推荐顺序：

spec-brainstorm
  -> spec-doc-review
  -> spec-plan
  -> spec-write-tasks
  -> spec-work
  -> spec-code-review
  -> spec-compound

使用 spec-write-tasks 的信号：

• plan 有 3 个以上 implementation units
• 文件范围跨模块
• 有真实依赖或并行机会
• 验证面跨 unit / integration / smoke
• 需要明确 stop_if 和文件 ownership

多端需求如何处理

先在 brainstorm 中拆清楚 actors、platform flows 和 scope boundaries，再在 plan 中把 Web、iOS、Android、backend、API、analytics、i18n 等文件边界列出来。移动 App 需求在实现前后可加入：

spec-app-consistency-audit

它做静态一致性审查，不替代模拟器、真机、自动化测试或 QA。

什么时候用 optimize 或 polish

spec-optimize 只适合有可重复 measurement 的目标。没有指标、预算和 scope 时，不要把它当成“多试几版”的普通 work；先回到 plan 定义 measurement scaffold。

spec-polish 只适合浏览器可见 UI 已经能运行的情况。它的价值在于启动 dev server、让用户实际看页面、基于反馈小步调整；非 UI 代码仍走 work / review。

写高质量 spec

好的 requirements 不需要很长，但必须回答：

• 谁在什么场景下使用
• 成功行为是什么
• 不做什么
• 哪些边界需要保留给 plan 或 implementation
• 验收样例是什么
• 旧行为、数据、权限、错误状态是否受影响

不确定的事实不要写成结论。用 open questions 或 implementation-time unknowns 承接。

从 PRD 进入 brainstorm

粗糙 PRD、会议纪要或产品笔记不应直接丢给 plan，让 plan 去猜 WHAT。存量系统上的增量需求优先用 spec-prd 先写成 PRD-grade requirements：

spec-prd "基于现有订单后台，补齐批量退款审批 PRD"

spec-prd 会先确认 current-state evidence，再写 change delta、requirements、acceptance examples 和 scope boundaries。它的输出仍在 docs/brainstorms/*-requirements.md，只是 frontmatter 标记为 artifact_kind: prd-requirements。

把 PRD 当输入时，不要把它当最终 spec。让 spec-prd 或 spec-brainstorm 做三件事：

• 把业务语言转成 actors、flows、requirements 和 acceptance examples
• 标出 scope creep、冲突和缺失
• 明确哪些问题必须在 plan 前确认，哪些可以推迟到实现期

PRD 已经很清楚且有 current-state evidence 时，可以直接进入 spec-plan，但仍应保留 scope boundaries。

从 brainstorm 到 plan

spec-plan 需要明确 HOW，而不是重复 requirements。高质量 plan 至少包括：

• requirements trace
• implementation units
• files to create / modify / inspect
• test scenarios
• risks and mitigations
• provider / direct-read evidence
• deferred implementation unknowns

如果 provider evidence stale 或 unavailable，在 plan 中写清楚 fallback evidence。

从 plan 到 tasks

小计划可以直接 spec-work。大计划才用 spec-write-tasks，避免把任务拆分变成另一套计划。

task pack 应该保留：

• source_plan
• source_plan_hash
• spec_id
• dependencies
• wave
• files
• test_focus
• done_signal
• stop_if

执行前用 CLI 校验：

spec-first tasks validate docs/tasks/<task-pack>.md --repo .

让 code-review 更有效

在 review 前准备好：

• 需求或 plan 路径
• 当前 diff
• 已运行的测试命令
• Graph readiness 状态
• 你已知的风险或未验证项

使用正确入口：

输入	入口
代码 diff / PR	spec-code-review 或 spec-code-review
requirements / plan / task pack	spec-doc-review 或 spec-doc-review
移动 App PRD/Figma/source 一致性	spec-app-consistency-audit 或 spec-app-consistency-audit

沉淀知识

问题解决后，用 spec-compound 把可复用经验写到 docs/solutions/。适合沉淀的内容：

• 根因和排查顺序
• 为什么某个方案稳定
• 哪些方案试过但不适合
• 项目内可复用模式
• 下次遇到类似问题该先看哪里

过期或重复的 learning docs 用 spec-compound-refresh 清理，不要让知识库变成历史噪音。

避免上下文膨胀

• 让 setup、graph 和 project guidance 先提供事实，再让 LLM 选择上下文。
• plan 只写关键文件和验证面，不粘贴大段源码。
• task pack 只派生执行切片，不重新讲完整需求。
• review findings 聚焦可行动问题，不堆 advisory。
• Graph degraded 时直接说 limitation，不用补一堆无关文件。

避免 AI 乱猜

• 要求 workflow 标注 assumption、blocked、degraded、not verified。
• 对可检查事实运行命令或读取源码，不让 LLM 记忆代替证据。
• 对产品范围不清的问题回到 brainstorm。
• 对实现路径不清的问题回到 plan。
• 对 task pack freshness 不可信的问题重新生成或 validate。

使用 graph evidence

Graph evidence 最适合回答：

• 哪些模块可能受影响
• 有哪些复用候选
• 哪些文件是上下文入口
• review 应该重点看哪些消费者
• provider 证据本身是否 stale / degraded

Graph evidence 不适合单独决定：

• 产品范围
• 最终架构取舍
• 测试是否充分
• 代码是否可合并
• 安全风险是否完全消除

下一步

• 快速开始：跑通第一条链路
• Workflow 总览：理解每个节点
• 运行时治理：确认 source/runtime 和多宿主边界
• 契约与质量门禁：建立 handoff、verification 和安全证据纪律
• Skills 参考：查每个 skill 的输入输出和边界
• Troubleshooting：遇到安装或 provider 问题时排查