夜雨聆风写 Spec（规格文档）的人，通常分两种。
第一种，把 Spec 写成了小说： "系统应该给用户提供良好的体验， 并确保数据的安全性……" 读完全文，你也不知道要做什么。
第二种，把 Spec 写成了代码： "用 Redis String 存 key， 设置 300 秒过期，用 xxl-job 定时清理……" 实现细节全锁死，开发毫无自由度。
前者太模糊，AI 会脑补； 后者太具体，工程会僵化。
一份合格的 SDD 规格文档， 要在这两者之间走钢丝。
今天给你一套可直接照抄的写法， 外加一份完整实战样例。
一、Spec 的五大核心组成
先记住一个原则： Spec 回答"做什么"和"为什么"， 不回答"怎么做"。
（"怎么做"属于 Plan 阶段的职责， 见系列第 6 篇的三份规范讲解）
一份标准的 SDD Spec 包含五部分：
1. 用户故事（User Story）
回答：谁需要，为什么需要。
格式固定： "作为 [角色]，我想要 [功能]， 以便 [价值]。"
2. 验收标准（Acceptance Criteria）
回答：怎么算"做完了"。
这是整份 Spec 的灵魂， 要求具体、可测试、覆盖完整。 下面单独展开讲。
3. 约束（Constraints）
回答：哪些事绝对不能做。
包括技术限制、依赖关系、 安全要求、兼容性红线。 约束写得越清楚， AI 越不会自作主张。
4. 技术决策（Technical Decisions）
回答：哪些架构选择已经定了，不许再议。
比如"消息队列选 Kafka"、 "鉴权走统一网关"。 这些写进 Spec， 防止不同开发会话重复推翻决策。
5. 实现状态（Implementation Status）
回答：每条验收标准现在走到哪一步。
已完成 / 进行中 / 待办， 用复选框逐条跟踪。 这是 Spec 与代码保持同步的账本。
二、验收标准：Spec 的灵魂
验收标准写得好不好， 直接决定这份 Spec 是价值千金还是废纸一张。
好的验收标准有三大特征：
第一，具体（Specific）。
❌ "搜索要快" ✅ "搜索结果在按键后 200ms 内更新"
第二，可测试（Testable）。
❌ "UI 要响应式" ✅ "在 320 / 768 / 1440px 宽度下正确渲染"
第三，描述行为，而非实现。
❌ "用 200ms 防抖实现"（这是实现） ✅ "输入后每 200ms 最多更新一次结果" （这是行为，更灵活）
这三条是硬标准。 写完后逐条自查， 任何一条无法被自动或手动验证， 就退回重写。
三、一份完整实战样例：登录功能
理论说完，直接上干货。 以下是一份可直接落地、 可直接投喂 AI 的 Spec 模板， 无一句废话，全部可校验。
（样例框架参考 deepdata.cn 的 SDD 规格六要素结构：功能概述、范围边界、 输入输出约束、既定决策、极端场景、验收标准）
# SPEC-LOGIN：用户账号登录功能规格
## 1. 功能概述
实现邮箱+密码方式的账号登录，
完成身份鉴权并发放会话凭证。
## 2. 范围边界
### 在范围内
1. 账号密码校验、会话生成、错误提示
2. 暴力破解风控：连续5次失败锁定15分钟
3. 全链路HTTPS传输，密码禁止明文存储
### 不在范围内
第三方快捷登录、双因素认证、
自助找回密码（后续迭代规划）
## 3. 输入输出定义
- 入参：email(string)、password(string)
- 成功出参：token、用户基础信息、会话过期时间
- 失败错误码：参数非法-400、
凭证错误-401、账号锁定-423
## 4. 既定决策（禁止私自变更）
- 会话凭证采用 JWT，过期时间 24 小时
- 密码哈希使用 bcrypt，禁止 MD5/SHA1
## 5. 边界与异常场景
1. 空邮箱/空密码：前端直接拦截，
不发起后端请求
2. 会话过期：自动跳转登录页并友好提示
3. JS 禁用环境：登录表单依然可正常提交
## 6. 验收标准
1. 合法账号可正常登录并跳转首页
2. 连续 5 次密码错误后，
账号严格锁定 15 分钟
3. 所有网络请求抓包无明文密码
4. 所有异常场景返回对应标准化错误码
## 7. 变更记录
2026-07-31 初稿定稿：全员评审通过，
禁止私自调整错误码与锁定时长
四、这份 Spec 好在哪里？
拆解给你看。
范围边界是防范围蔓延的闸门。 "不在范围内"写得越具体， 开发者和 AI 越不会顺手加需求。
输入输出定义是防契约漂移的锚点。 错误码 400 / 401 / 423 全部钉死， 前后端联调、AI 生成接口代码， 都有了唯一依据。
既定决策是防重复争论的存档。 JWT、bcrypt 一旦写死， 任何会话都不得推翻， 省去无休止的"要不要换个方案"。
边界场景是防 AI 脑补的补丁。 "JS 禁用环境"这种边角需求， 你不写，AI 绝对不会想到。
验收标准是防糊弄的尺子。 第 2 条"锁定 15 分钟"， 可以直接转化为测试用例， 也可以直接丢给 AI 生成代码。
这份 Spec 全文不到 400 字， 但信息密度远超 2000 字的 PRD。 这就是"严谨"的正确打开方式： 不是写得多，而是写得准。
五、三个最常见的写作误区
写完会写，还要会避坑。
误区一：Spec 写得太像代码。
如果团队评审时发现， Spec 读起来像伪代码， 说明你把"怎么做"写进了"做什么"。 Spec 只锁意图，实现细节留给 Plan。
误区二：Spec 写完就永久封存。
需求一定会变。 铁律是：先改 Spec，再改代码。 Spec 长期不更新，就会腐化成僵尸文档， 最终失去所有人信任。
（关于"规范腐化"的深度剖析， 见系列第 11 篇）
误区三：Spec 放在知识库里，不进代码仓库。
Spec 必须和代码同仓库、同分支、同 MR。 只有放在 Git 里， 才能实现版本管理、评审留痕、 变更可追溯。
六、写在最后
写 Spec 的本质， 是把藏在脑子里的模糊需求， 变成一份可读、可审、可测、可被 AI 理解的 刚性契约。
它不增加你的工作量， 它只是把"返工的时间"挪到了"思考的时间"。
下一篇，我们讲三份核心规范： proposal、design、tasks—— 它们怎么配合，才能串起 SDD 的完整流水线？
关注我，追完这个系列， 你会拿到一套可以直接抄的完整落地清单。
福利： 关注公众号，回复「SDD」， 领取文中登录功能 Spec 模板的 Markdown 源文件，直接改改就能用。
评论区聊聊：你现在写需求文档， 最常被 AI 或同事误解的是哪一句？
参考来源：deepdata.cn《规格驱动开发 SDD》、 planu.dev《The Complete Guide to SDD》、 CSDN《规范驱动开发》
