spec-driven-workflow

规格驱动工作流

规格是关于要构建什么以及如何判断是否完成的共同事实来源。

快速规模指南

规模	工作流
微小	跳过正式工作流；在聊天中处理
小	起草规格 → 实现
中	起草规格 → 分析 → 规划 → 实现 → 审查
大	先研究，再执行完整工作流

规模不明确时，请阅读 references/problem-size-guide.md。

阶段门控流程

当前产物达到足够完善的程度后，才能进入下一阶段（中型及以上由用户审查；小型由自己检查）。

SIZE → SPECIFY → ANALYZE (medium+) → PLAN (medium+) → CLEAR → IMPLEMENT → REVIEW
                    ↑______________ living spec + plan sync ______________|

1. 规模 — 根据问题规模匹配工作深度（见上表）。
2. 编写规格 — 先明确假设，再编写可测试的需求（推荐使用 REQ-XXX）。默认采用需求优先。请阅读 references/spec-writing-guide.md。
   • 缺陷修复（不明显／高风险缺陷）：采用现状／预期／不变项的格式 — 请阅读 references/bugfix-workflow.md。
   • 设计优先（严格的 NFR、现有架构，或需在确定范围前评估可行性）：先起草 TECH／方案，再推导 REQ — 参见 references/spec-writing-guide.md。
3. 分析（中型及以上）— 规划前检查各项需求之间是否存在冲突、歧义和遗漏。请阅读 references/analyze-requirements.md。
4. 规划（中型及以上）— 将工作拆分为具体且可验证的任务。多文件变更前，最好先写出计划。
   • 架构材料包（大型；以及架构／集成存在歧义的中型项目）：多阶段实现前，必须提供系统上下文视图和容器视图（或说明“无需 — 架构已验证”），并通过 solution-architecture / /design-architecture 为不可逆的选择关联 ADR。参见 references/problem-size-guide.md。
   • 示踪弹（大型；以及架构／集成存在歧义的中型项目）：多阶段实现前，必须包含一个精简的纵向切片和一次验证，或明确说明“无需 — 架构已验证”并给出理由。参见 references/problem-size-guide.md。
   • 最好将构建任务与验证／审查任务拆开，以便 QA 能与下一个 REQ 切片并行进行（小型项目可选）。
5. 清理上下文（中型及以上）— 将探索结果保存到持续更新的规格／计划中；以精简上下文开始实现。不要把完整的探索记录作为工作上下文。可以进行有界探索（使用子 Agent 或专门的聊天），但重要发现必须已写入产物。对于多会话工作，请阅读 references/session-handoff.md（开始检查清单：编码前准备好持续更新的规格、计划和进度）。
6. 实现 — 遵循规格／计划；将每项需求映射到测试，除非该需求不涉及行为且已明确说明理由。中型及以上项目在会话结束时（或工作未完成时），应按照 session-handoff.md 写好交接／进度部分 — 不要把它当成 AFK 产品。
7. 审查 — 单独进行评估（生成者 ≠ 评估者）：以反驳为导向检查规格符合度、回归防护、安全敏感路径、测试，以及面向用户的表层变更是否导致文档／README 偏离（交由 /update-readme / readme-authoring 处理；除非用户要求，否则不要在审查中全面同步）。不要把实现会话中的自评当作已完成。请阅读 references/review-evaluator.md。
8. 棕地项目 — 大幅变更前，使用 extract-spec 记录现有行为。请阅读 references/brownfield-workflow.md。

编写规格前

立即明确假设。 列出你的假设，并在起草前邀请用户纠正：

ASSUMPTIONS:
1. …
2. …
→ Correct me now or I'll proceed with these.

将模糊目标改写为成功标准（可衡量／可测试），然后确认：

REQUIREMENT: "Make the dashboard faster"
SUCCESS CRITERIA:
- LCP < 2.5s on 4G
- Initial data load < 500ms
→ Are these the right targets?

规划测试切入点（中型及以上）。 优先选择最有用的现有边界（API、模块、端口），而不是另行创建；在将其纳入规格前先与用户确认。详情：references/spec-writing-guide.md。

不要默默补全含糊的需求 — SDD 的存在正是为了防止这种失败。

活文档规范 + 计划同步

决策或范围发生变化时，更新规范；优先在实现变更前更新规范。将 PR 链接回其对应的规范章节或所满足的 REQ-XXX。

重大 REQ/设计编辑后： 重新运行 /plan-impl（或刷新 Cursor Plan YAML todos），使任务与活文档规范保持一致。不要根据过时的计划进行实现。

产物存放位置

编写规范或计划前，确定输出位置（不要默认使用 .cursor/）：

1. 用户明确指定的路径（--out、@file、具体路径）
2. 项目现有约定（docs/specs|plans 或 .cursor/docs/specs / .cursor/plans）
3. 客户端默认位置 — Cursor / 或 Cursor 接线配置 → .cursor/...；否则 → docs/specs + docs/plans

创建或定位规范/计划时，阅读 references/artifact-homes.md。
存放位置为 Cursor 时，阅读 references/cursor-adapter.md（必须包含 Plan YAML todos）。

斜杠命令是可选的轻量封装；详情见 references/commands-reference.md。

渐进式披露

仅在需要时加载参考资料：

参考资料	阅读时机
references/artifact-homes.md	创建/定位规范或计划；路径不明确时
references/cursor-adapter.md	使用 Cursor / 命令或 .cursor/plans / .cursor/docs 存放位置时
references/session-handoff.md	中型及以上的多会话任务开始/结束时；进度 + 下一个 REQ
references/review-evaluator.md	使用 /review 或处于 Review 阶段时；生成器 ≠ 评估器
references/problem-size-guide.md	规模不明确或存在争议时
references/spec-writing-guide.md	编写或审查规范时；Design-First 与 Requirements-First
references/analyze-requirements.md	中型及以上任务运行 /plan-impl 前，或重大 REQ 编辑后
references/bugfix-workflow.md	非简单的 Bug 修复；需要回归防线时
references/greenfield-workflow.md	新功能，且没有需要保留的现有行为时
references/brownfield-workflow.md	修改或记录现有代码时
references/commands-reference.md	使用斜杠命令或选项时
references/getting-started.md	用户询问如何安装/设置 ADSK 时
references/spec-driven-overview.md	用户询问 SDD 的原因时（不用于常规执行）
references/best-practices.md	用户询问技巧/外部链接时
references/extending.md	添加规则/命令/技能或配对上游包时

质量门槛

• 需求存在歧义时，起草前先明确说明假设。
• 需求应具体且可测试。
• 中型及以上的规范在制定计划前，应进行跨需求分析（或明确说明“ N/A — 微型 REQ 集已完成审查”）。
• 对于行为并非简单直接的中型及以上规范，应指出首选测试接缝（现有的最高效用边界）。
• Bug 修复规范（如有）应记录不变行为，且测试应覆盖该防线。
• 重大活文档规范编辑后，在实现前重新同步计划/todos。
• 对于大型/有歧义的中型计划，如果集成边界不明确，应通过 solution-architecture 设置架构包门槛（或注明“ N/A — 架构已验证”）。
• 已实现的需求应有自动化测试（或在确实不涉及行为时简要说明理由）。
• 失败即关闭的验证： 声称完成前，运行 project-cmds（或项目文档指定的验证命令）。如果未配置验证，不得声称完成 — 应指示用户运行 /quick-start，或设置 project-cmds / 可移植的等效方案。禁止在未验证时仅凭“看起来不错”就下结论。
• 多会话交接（中型及以上）： 会话开始时读取活文档规范 + 计划 + 进度；会话结束时按照 session-handoff.md 更新交接信息（下一个 REQ/T#、git 预期）。这不是 AFK/Ralph 产品。
• 生成器 ≠ 评估器（中型及以上）： 不得仅凭实现阶段的自评声称完成；应按照 review-evaluator.md 运行单独的、以反驳为导向的 /review（Bug 修复必须设置不变行为防线）。