可以直接复用的 Spec-First 案例

先看弱需求

Before 状态故意保留粗糙感。它代表很多 AI 编码提示词的真实问题：目标被暗示但没有写明，约束缺失，评审者也没有客观理由拒绝额外行为。

再看边界

有价值的不是文案变顺，而是边界变明确：非目标、影响文件或系统、兼容约束，以及实现功能时不能改变的行为。

最后看证据

规格包只有在验收标准能落到测试、截图、fixture、日志或上线信号时才算完整。案例展示的是评审者在合并前应该要求的证明。

Checkout 优惠码

一个涉及金额的 checkout 需求，变成包含校验状态、总价计算、实现任务和回滚证据的规格包。

弱需求：
给 checkout 加优惠码。
无效码不要影响付款。

规格边界：
- 付款前应用一个优惠码
- 不做后台管理
- 不重构 totals

API 错误分类

一个 API 错误清理需求，变成包含兼容说明、SDK fixture、OpenAPI 示例和迁移证据的契约规格。

弱需求：
优化 API 错误。
让客户端更容易处理。

规格边界：
- 只改 envelope
- 只做 additive response change
- 旧 SDK 仍能解析

通知偏好迁移

一个设置页需求，变成包含退订保留、重复发送预防和 worker 投递证据的迁移规格包。

弱需求：
添加通知偏好。
注意不要骚扰用户。

规格边界：
- 只处理邮件和推送
- 保留现有退订
- 证明不会重复发送

数据库 Schema 变更

一个模糊账号状态字段需求，变成包含 expand/backfill/switch、查询证据和回滚边界的迁移计划。

弱需求：
给 accounts 加 account_status。
确保报表还能用。

规格边界：
- 先 nullable expand
- parity check 通过后再 switch
- cleanup 放到后续发布

AI PR 范围漂移

一个过宽的 AI 生成 PR，变成包含允许文件、非目标、diff 映射和合并证据的评审规格包。

弱需求：
用 AI 修复设置 bug。
顺手清理相关代码。

规格边界：
- 只改允许路径
- 不改 billing 或 auth
- changed files 映射到 tasks

大报表导出

一个 CSV 导出需求，变成包含权限、filter snapshot、文件过期、队列指标和失败处理的异步 job 规格。

弱需求：
给报表加 CSV 导出。
文件准备好后邮件通知。

规格边界：
- 大客户走异步 job
- 使用当前报表 filters
- 下载链接安全过期

金额或订单状态

如果 bug 会影响价格、付款、退款或订单状态，先看 Checkout 优惠码案例。

公开响应形状

如果客户端、SDK、文档或生成代码依赖稳定契约，先看 API 错误分类案例。

迁移或用户同意

如果旧状态要安全过渡，先看 通知偏好案例 或 数据库变更案例。

AI 生成 PR 评审

如果编码助手修改了原需求之外的文件或行为，先看 AI PR 范围漂移案例。

长时间后台任务

如果工作需要后台 job 完成，并涉及权限、状态和运维证据，先看 大报表导出案例。

只展示漂亮答案

没有原始弱需求，读者就看不出哪些歧义被移除了。before 状态本身就是教学的一部分。

把证据留到最后

证据应该和规格一起设计。实现后再补证据，会把评审变成总结，而不是验证。

盲目复制领域规则

真正可复用的是规格包结构。具体业务规则必须按读者自己的系统、风险和发布流程重写。

通知偏好

把笼统设置需求改写成迁移风险、偏好状态和重复发送证据。

数据库 Schema 变更

把“加状态字段”改写成分阶段迁移任务、parity check 和回滚边界。

更多紧凑改写

对照松散工单和规格包版本，查看范围、任务、验收和证据如何落地。

AI PR 范围漂移

把“用 AI 修一下”改写成允许路径、非目标和 changed-file 证据映射。

大报表导出

把 CSV 按钮需求改写成异步 job、权限检查和队列证据。