Spec 模板库

功能规格模板

一页写清目标、非目标、验收标准和边界条件。

API 规格模板

覆盖接口契约、请求响应结构和错误码约定。

数据库规格模板

覆盖字段、约束、索引、迁移策略和回滚说明。

变更提案

先写目标、非目标、验收标准、开放问题和证据要求，再进入实现。

设计文档

记录架构选择、被拒绝方案、接口、约束、上线顺序和回滚方式。

任务计划

把实现拆成可评审切片，写明允许文件、验收链接和测试命令。

证据日志

把测试、截图、日志、指标、手工检查和发布停止信号连接到规格。

AI 编码评审

检查生成代码是否越界、是否修改允许文件、是否补齐验收证据。

工程宪章

定义团队的规格门禁、证据标准、AI 编码边界和例外规则。

功能规格片段

复制模板后，应尽快把它改成决策记录，而不是保留一堆空标题。

## 退款重试行为
责任人：账单平台
非目标：本次不更换支付渠道

验收：
- Given 支付渠道第一次退款请求超时
  When worker 使用相同 idempotency key 重试
  Then 只创建一个 refund_id
  And 状态为 pending 时，客服不能创建第二笔退款

把规格写到这个程度，再交给工程师或 AI 编码工具实现，评审成本会低很多。

API 契约片段

API 模板要在 schema diff 进入发布评审前，把调用方影响写出来。

Endpoint: GET /orders/{id}
变更：新增 refund_status
兼容性：对生成客户端有风险

证据：
- 旧移动端能处理未知 enum
- webhook consumer 会忽略新字段
- 发布说明写明迁移窗口

如果示例和你的业务不一样，保留结构，替换字段、角色和证据。

范围不清时，用功能规格模板

当团队还在讨论功能应该包含什么、排除什么、如何验收时，从功能规格开始。它会逼着团队先写清目标、非目标、验收标准、边界条件、依赖和上线方式，再进入实现。

多端协作时，用 API 规格模板

当前端、后端、移动端或合作方需要一个稳定契约时，用 API 模板。它把接口行为、请求响应示例、错误语义、兼容规则和契约测试要求放在同一个地方。

数据变更有风险时，用数据库规格模板

迁移、改表、回填、报表口径变化，都适合先写数据库规格。它让约束、索引影响、回滚策略和兼容窗口提前进入评审，而不是上线前才发现。

1. 只保留团队会维护的章节

好的规格不是仪式性文档。保留能帮助决策的章节：目标、非目标、验收标准、边界条件、依赖、上线和测试证据。没人会看的套话可以删掉。

2. 把模糊意图改成可观察行为

不要写“优雅处理错误”。改成用户会看到什么、API 返回什么、日志记录什么、是否重试、哪些输入会被明确拒绝。

3. 实现前先评审规格

让产品、开发、QA 用十几分钟过一遍规格。目标不是润色文字，而是在代码出现之前找出歧义、漏项和风险边界。

4. 合并前补齐测试证据

进入实现后，把规格放在任务旁边。每条验收标准都应该对应自动化测试、手工验证说明，或一个明确记录的“不自动化原因”。

检查边界是否写清

每份复制出来的模板都应该回答：哪些不做、空输入怎么处理、权限如何限制、重复数据如何处理，以及团队愿意接受哪种失败模式。

把模板连接到下一步

规格准备好后，可以用 功能规格生成器整理实现文档，用 API 契约检查清单验证接口，或用 边界情况清单补风险。

它写的是决策，不只是章节

填完的模板应该说明谁能执行操作、哪些数据会变化、失败时发生什么、重复请求如何处理，以及哪些内容刻意不做。只有空标题不算进展。

它给 QA 可观察证据

每条验收标准都应该落到一个可验证结果：UI 状态、API 响应、数据库记录、日志、指标、告警或人工验证说明。如果无法证明，就还没准备好。

它能约束 AI 编码范围

把模板交给 AI 编码工具时，要同时给出非目标，并要求模型说明每处代码改动对应哪条验收标准，避免它自行扩展需求。

需求变化后也要更新

模板不是一次性产物。如果评审中修改了范围、上线方式或兼容规则，合并代码前应同步更新规格，让后来的人看到最终决策。

把模板当成团队约定

模板不是临时复制的文章片段，而是团队的工作协议。最好放在仓库或知识库中，标注适用场景、负责人、最近更新日期和评审方式。

按事故和返工更新模板

如果一次事故暴露了缺少幂等性、回滚或权限边界，就把这个检查项补进模板。模板应该随着团队踩过的坑变得更具体。

保留轻量版本

不是所有任务都需要完整模板。建议同时保留短版规格、完整规格、API 契约和数据库规格，让团队按风险选择，而不是把所有事都塞进同一个文档。

定期删除没人使用的章节

如果某个章节连续几次评审都没人填写或没人看，就要么删掉，要么改成更具体的问题。模板越贴近真实评审，越容易被持续使用。

每个任务都需要规格吗？

不需要。拼写修复、很小的文案调整不必写完整规格。当工作会改变行为、数据、API、上线风险或多人协作方式时，模板才真正有价值。

这些模板能配合 AI 编码工具吗？

可以。模板结构就是为了给 AI 编码工具一个边界清楚的请求：只实现这个范围，保护这些契约，并为这些验收标准提供测试证据。

订单筛选改版

优先用功能规格模板，因为核心风险是范围、角色、空结果、权限和验收标准。只有当它新增或改变接口时，再补 API 规格。

退款接口新增状态

优先用 API 规格模板，因为调用方需要知道新增状态如何处理、是否可重试、旧客户端是否兼容，以及错误结构是否稳定。

订阅表增加状态字段

优先用数据库规格模板，因为主要风险在迁移阶段、回填批次、旧代码兼容、索引影响和回滚边界。

功能先行，再补契约

当需求还在定义阶段，先用功能 Spec 写清目标、非目标和验收标准。等确定会影响接口时，再补 API 规格，避免一开始就陷入字段细节。

数据风险单独评审

只要涉及回填、约束、索引或旧代码兼容，就把数据库规格拆出来单独评审。数据变更的失败成本通常高于普通功能分支。

复盘反向更新模板

事故复盘里发现的缺口，应回写到功能、API 或数据库模板中。模板会随着真实失败经验变得更具体，这比一次性追求完整更有价值。