从模糊需求到可执行规格

这些例子展示 Spec Coding 的核心动作：把弱 AI 编码提示词改写成评审者、测试人员和编码代理都能遵守的文件。

Before模糊工单或提示词
After规格、任务、验收、证据
Use复制到 issue、PR 或仓库

示例 1：通知偏好

模糊工单

让通知设置更清楚。
用户应该知道自己订阅了什么。

规格包版本

spec.md
- 目标：按事件展示邮件、站内信和推送偏好。
- 非目标：不新增通知供应商。
- 风险：迁移时重复发送通知。

acceptance-criteria.md
- Given 现有用户关闭了邮件
  When 偏好完成迁移
  Then 每个事件的邮件仍保持关闭。

test-evidence.md
- 迁移 dry run
- 旧移动端截图
- 重复通知回归测试

示例 2：API 错误处理

模糊工单

优化 API 错误。
让客户端更容易处理。

规格包版本

spec.md
- 目标：统一 code、message、trace_id 和 retryable。
- 非目标：不改变 endpoint 行为。
- 约束：旧 SDK 仍能解析响应。

acceptance-criteria.md
- Given 请求参数校验失败
  When API 返回 422
  Then 响应包含 code、message、field_errors、trace_id。

test-evidence.md
- 400/401/409/422 契约测试
- SDK 兼容 fixture
- 变更示例的发布说明

示例 3：报表导出

模糊工单

给报表加 CSV 导出。
大客户也要能用。

规格包版本

spec.md
- 目标：支持最多 100 万行的异步 CSV 导出。
- 非目标：不做 PDF 导出。
- 风险：长任务和过期筛选条件。

tasks.md
- 保存导出请求和筛选条件
- worker 使用 retry 和 idempotency key
- 文件准备好后通知用户

test-evidence.md
- 100 万行压测
- worker 失败重试测试
- 过期下载链接检查

完整案例

Checkout 优惠码

看一个涉及金额的 checkout 需求，如何变成包含校验、总价计算和回滚证据的有边界规格。

打开优惠码案例

API 错误分类

看一个 API 错误清理需求，如何变成包含 fixtures、SDK 检查和 OpenAPI 示例的兼容契约。

打开 API 错误案例

通知偏好迁移

看一个宽泛设置页需求，如何变成包含退订保留、重复发送证据和 worker 检查的迁移规格包。

打开通知案例

数据库 Schema 变更

看一个模糊字段需求，如何变成 expand、backfill、switch、cleanup 分阶段迁移计划。

打开数据库案例

AI PR 范围漂移

看一个过宽的 AI 生成 PR，如何变成包含允许路径、非目标和 changed-file 证据的评审规格包。

打开 AI PR 案例

大报表导出

看一个 CSV 导出需求，如何变成包含权限、状态流转、队列证据和失败处理的异步 job 规格。

打开导出案例

什么时候要从快速改写升级成完整案例

小 UI 或文案改动，用一段 before/after 就够了。只要实现可能悄悄改变金额、权限、用户同意、外部契约、数据迁移或后台任务，就应该升级成完整规格包。

共享契约

如果 SDK、外部集成或另一个团队会消费结果，就要补兼容说明和 fixture，而不是只写一段解释。

状态迁移

如果要回填旧数据，就把规格拆成 expand、dry run、switch 和 cleanup，并给每个阶段写回滚信号。

用户信任

如果涉及计费、通知、隐私或同意状态，证据必须证明旧选择没有被覆盖。

这些示例背后的改写规则

模式看起来重复，是因为失败模式本来就很重复：需求写了想要的结果，却把边界、风险和证明方式留在脑子里。改写不需要变成完整 PRD，它只需要回答评审者原本会在第一个 AI 生成 diff 过大之后才追问的问题。

好的改写会写清角色、当前状态、触发动作和可观察结果，也会写清什么不应该变化。对 AI 编码来说，非目标往往是规格包里最重要的一行，因为它能阻止助手“顺手”重建相邻系统。

保留

用户意图、运行风险，以及上线后必须可观察到的结果。

补充

非目标、约束、验收标准、允许实现切片，以及合并前需要的证据。

删除

“做得更好”“处理边界情况”“优化体验”这类没有绑定可测试状态的空话。

使用改写前的质量检查

QA 能测试吗？

如果 QA 写测试前还必须追问作者，验收标准仍然太模糊。

评审能拒绝漂移吗？

如果评审者找不到非目标或允许文件边界，规格包就挡不住过大的 diff。

发布能证明吗？

如果 evidence 只写“测试通过”，就补上具体命令、fixture、截图、日志查询或指标。

如何迁移这些示例

不要先复制领域细节，要复制改写动作。先写下团队平时会直接丢给 AI 编码工具的那句模糊需求，然后用四个过滤器处理它：行为到底改什么、什么不在范围内、最可能的失败模式是什么、PR 合并前应该看到什么证明。

小改动可以把改写结果放在一个 issue 评论里；高风险改动建议拆成多个文件，让每个产物只负责一件事。spec 负责行为和边界，tasks 负责实现切片，acceptance 负责可观察结果，evidence 负责证明。角色分开后，规格包更容易评审，也更容易在实现发现新约束时更新。

这些示例也展示了什么时候应该停止写。只要评审者能理解目标行为、拒绝范围漂移，并说出需要哪些验证证据，再继续堆 prose 反而会让规格变差。目标不是长文档，而是足够结构化，让代码生成少执行隐藏假设。

改写时要避开的反模式

这些问题会让改写看起来更整洁，但实现风险没有真正降低。评审时应该看边界、证据和可测试性，而不是只看文字是否像文档。

只给模糊需求换标题

标题变专业，但边界没有增加，留给实现者的歧义仍然一样多。

先列任务再定行为

任务只有在目标行为和非目标明确之后才有意义，否则只是把假设拆得更细。

证据没有负责人

如果没人负责测试、截图、日志查询或复查日期，证据清单就很容易变成口号。

复用这些改写前的最后检查

把示例迁移到自己的需求时，先不要问“这段写得像不像规格”，而要问“评审者能不能凭它阻止错误实现”。如果非目标没有挡住一个真实诱惑，验收标准没有给 QA 一个可执行场景，证据没有指向具体测试或截图，那么改写仍然停留在文案层。

最可靠的做法，是让一个没有参与需求讨论的人读这份规格。如果他能说出要改什么、不改什么、风险在哪里、合并前看什么证明，说明规格已经足够指导 AI 编码。如果他还需要追问背景，说明还应该补上下文，而不是急着开始实现。

把你的工单转成规格包

当需求已经可以讨论、但还不适合直接交给 AI 写代码时，就用生成器先把边界写清楚。

生成规格包

编辑说明

这些示例作为实用教学材料维护，重点展示具体 before/after 动作，而不是泛泛的最佳实践列表。