SDD规范驱动开发：用三份结构化文档替代口头对齐

1. 什么是SDD？它不是又一个 buzzword，而是你每天写代码时漏掉的那张施工图

“氛围编程”这个词我第一次听到是在去年带一个新人的时候。他坐在工位上，耳机一戴，咖啡一冲，IDE打开，光标在空白文件里闪了二十分钟，最后提交了一段逻辑跳跃、命名混乱、连自己三天后都看不懂的代码——还配了句 commit message：“先跑起来再说”。这不是懒，也不是能力问题，而是缺一张图：一张在敲第一行代码前就该画好的、能回答“为什么这么写”“边界在哪”“谁来验证”的图。SDD（Specification-Driven Development，规范驱动开发）就是这张图的工程化落地方式。它不反对快速迭代，但坚决反对“先写再猜”；它不排斥灵活应变，但要求所有变更都有据可溯。核心不是文档先行，而是决策先行、共识先行、验证先行。你看到的 proposal.md、design.md、task.md，从来不是交付物，而是开发过程中的“思维脚手架”——proposal 是立项前的可行性沙盘推演，design 是技术选型的多维权衡记录，task 是把抽象设计拆解为可验证、可分配、可回溯的最小执行单元。所谓“六步实践指南”，本质是把软件开发中那些原本靠经验、靠默契、靠加班补救的隐性环节，全部显性化、结构化、版本化。它解决的不是“怎么写代码”，而是“怎么让代码值得被写”。适合三类人：带团队的技术负责人（终于能说清“为什么这个需求要两周而不是两天”）、独立开发者（告别反复返工和需求模糊带来的焦虑）、刚转行的新人（用结构代替直觉，用模板代替试错）。这不是给代码加枷锁，而是给思考装导航。

2. SDD 的底层逻辑：为什么必须用三份文档替代“口头对齐”？

2.1 传统协作的三大隐形成本，全藏在“我们以为大家都懂”里

我做过一个粗略统计：在一个中等复杂度的内部工具项目中，平均每个需求在开发阶段会产生 3.7 次因理解偏差导致的返工。最典型的一次，产品说“用户上传头像后要自动裁剪成正方形”，后端同学理解为“服务端接收后裁剪并存储”，前端同学理解为“浏览器内裁剪后上传”，而UI设计师提供的切图里压根没标注裁剪比例。结果是：前端花了两天实现Canvas裁剪，后端写了三天ImageMagick集成，最后发现双方都做了，但API协议不匹配，还得重写。这种损耗，根源不在技术，而在信息传递的熵增。口头沟通、即时消息、零散会议纪要，这些载体天然缺乏结构、不可追溯、无法验证。SDD 的三份文档，本质上是对抗这种熵增的三道防火墙：

• proposal.md对抗的是“目标漂移”：它强制回答“这个功能到底要解决什么真实问题？有没有更简单的解法？不做会怎样？”——不是写给老板看的PPT，而是写给三个月后的自己看的决策日志。
• design.md对抗的是“技术幻觉”：它拒绝“用React写就行”这类答案，要求明确写出“为什么选React而非Svelte？状态管理用Zustand而非Redux Toolkit？图片压缩用sharp而非jimp？每项选择的实测数据支撑是什么？”——不是技术炫技清单，而是给未来维护者留下的技术债说明书。
• task.md对抗的是“进度黑箱”：它把“实现用户登录”这种模糊任务，拆解为“1. 设计JWT token刷新机制（含过期时间、续期策略、黑名单实现）；2. 编写密码强度校验规则（至少8位，含大小写字母+数字+特殊字符，禁用常见弱口令）；3. 实现登录失败5次锁定IP功能（需区分客户端IP与代理IP）”——不是任务分配表，而是可逐条核对、可自动化检查的验收清单。

提示：SDD 不是增加文档量，而是消灭“无效沟通”。一份写清楚的 proposal.md，通常能省掉3次以上跨角色拉会；一份写透的 design.md，能让Code Review时间减少40%；一份颗粒度够细的 task.md，能让每日站会从“我昨天干了啥”变成“我卡在task#3的Redis连接池配置上，需要DBA协助”。

2.2 SDD 与 TDD/BDD 的本质区别：不是测试先行，而是契约先行

很多人第一反应是：“这不就是TDD（测试驱动开发）换了个马甲？” 或者 “BDD（行为驱动开发）的文档版？” 这是个关键误区。TDD 的核心是“用测试用例定义函数接口”，BDD 的核心是“用自然语言描述用户行为”，而 SDD 的核心是“用结构化文档定义系统契约”。三者关注点完全不同：

举个真实例子：我们做支付回调幂等性设计时，TDD 会写test_callback_idempotent_returns_200()，BDD 会写Given a duplicate callback request When received Then return HTTP 200 and no double charge，而 SDD 的 design.md 里会明确写：

## 幂等性保障方案 - **唯一标识来源**：使用商户订单号 + 支付平台流水号组合生成 `idempotency_key` - **存储介质**：Redis集群（主从+哨兵），TTL=24h，key格式：`pay:idempotent:{md5(idempotency_key)}` - **冲突处理**：若检测到重复key，直接返回HTTP 200，响应体包含`{"status":"already_processed","original_timestamp":"2023-10-05T14:22:33Z"}` - **监控指标**：`idempotency_hit_rate`（命中率需≥99.5%，低于则告警）

这份文档，既是开发依据，也是测试用例生成器，更是运维监控的配置源。它把“应该怎么做”变成了“必须这么做”的契约。

2.3 SDD 六步实践指南：不是线性流程，而是螺旋式校准

网上流传的“SDD六步”常被误解为瀑布式流程：1.写proposal→2.写design→3.写task→4.编码→5.测试→6.上线。这是危险的简化。真实的 SDD 是一个基于反馈的闭环校准系统，六步本质是六个校准点：

1. Proposal 校准点：当产品提出“要做个搜索框”，SDD 要求立刻暂停，问：“当前用户搜索失败率是多少？主要卡在哪些词？现有方案瓶颈在前端渲染还是后端查询？有没有AB测试数据证明新方案能提升转化率？”——校准的是问题真实性。
2. Design Scope 校准点：设计阶段不是闭门造车。我们会把 design.md 初稿发给运维（问基础设施支持）、安全团队（问合规风险）、甚至客服（问用户投诉高频点）——校准的是方案可行性。
3. Task 拆解校准点：task.md 不是开发经理拍脑袋列的。每个task必须能对应到 design.md 中的具体条款，且由实施者签字确认“我能独立完成且知道验收标准”——校准的是责任清晰度。
4. Implementation 校准点：编码不是闷头写。每日同步时，开发者需对照 task.md 声明：“已完成task#5的数据库索引优化，实测QPS从1200提升至3800，但发现缓存穿透问题，建议在task#7中增加布隆过滤器”——校准的是进展可信度。
5. Verification 校准点：测试不是等代码交完才开始。QA 会提前根据 proposal.md 中的业务目标、design.md 中的性能指标、task.md 中的验收条款，生成测试矩阵——校准的是质量覆盖度。
6. Post-Mortem 校准点：上线后不庆祝，而是开15分钟快复盘：“proposal.md 中预估的用户增长20%是否达成？design.md 中设定的99.9%可用性是否达标？哪些task实际耗时超出预估300%？原因是否在design阶段被忽略？”——校准的是认知迭代率。

这六步没有固定顺序，可能因一个线上bug，倒退回proposal校准点重新审视问题定义；也可能因技术突破，在design校准点推翻原有架构。它的价值不在步骤本身，而在每一次校准都强制暴露认知盲区。

3. 三份核心文档怎么写？拒绝模板套话，只讲实战细节

3.1 proposal.md：用“反向OKR”写清楚“为什么不做比做更重要”

proposal.md 最常见的失败，是写成需求说明书或技术方案预告。它真正的灵魂在于反向论证。我们团队的标准结构是：

# [项目名称] Proposal：[一句话结论，如“不建设新搜索服务，优化现有Elasticsearch集群”] ## 1. 当前痛点（用数据说话，拒绝形容词） - 用户侧：近30天搜索无结果率 23.7%（监控平台截图链接），其中 68% 请求超时（>3s） - 技术侧：ES集群CPU持续 >90%，GC频率达 12次/分钟（Prometheus截图链接） - 商业侧：搜索页跳出率 58%，较行业均值高 22个百分点（Google Analytics报告链接） ## 2. 可选方案对比（必须量化，拒绝“更好/更优”） | 方案 | 预估工期 | 成本 | 风险 | 关键指标影响 | |------|----------|------|------|--------------| | A. 新建专用搜索服务（Go+ES） | 6人*3周 | $42k（服务器+人力） | 高（需重写所有搜索逻辑，历史数据迁移风险） | QPS提升至5000，但首屏加载+1.2s | | B. 优化现有ES集群（增加节点+查询调优） | 2人*2周 | $8k（云服务扩容） | 低（无代码变更，仅配置调整） | QPS提升至3200，首屏加载不变 | | C. 前端增加搜索建议（减少无结果请求） | 1人*1周 | $3k | 极低 | 无结果率降至12%，但QPS无提升 | ## 3. 推荐方案及理由（聚焦“为什么放弃其他选项”） **推荐B方案**。理由： - 成本效益比最优：$8k投入带来23.7%→12%的无结果率下降，ROI=146% - 风险可控：所有操作均可灰度，失败可秒级回滚 - **关键洞察**：监控显示92%的超时请求集中在“空关键词搜索”，说明问题本质是流量治理而非算力不足，B方案直击要害 ## 4. 成功定义（SMART原则，拒绝模糊） - ✅ 达标：30天内无结果率 ≤15%，且ES CPU <70% - ⚠️ 预警：若第15天无结果率仍 >18%，启动方案C作为补充 - ❌ 失败：投入超$10k或导致搜索服务不可用 >5分钟

注意：proposal.md 必须包含可证伪的成功定义。我们曾因一条“提升用户体验”的模糊目标，导致项目延期两个月还在争论“体验是否提升”。后来改成“首页加载时间从3.2s降至≤1.8s（Lighthouse实测）”，争议当天就平息了。另外，所有数据必须附原始链接，不是“据数据显示”，而是“见https://grafana.internal/p99-search-latency”。

3.2 design.md：技术决策的“法庭笔录”，不是技术选型的“朋友圈晒单”

design.md 最大的陷阱，是写成技术栈罗列（“选用React 18 + TypeScript + Vite”）。它真正的价值在于记录决策背后的博弈与妥协。我们的写法是：

# [模块名称] Design：[核心决策，如“采用最终一致性而非强一致性”] ## 1. 决策背景（触发点） - 用户下单后需同步更新库存、积分、物流单号三个系统 - 当前强一致性方案（分布式事务）导致下单成功率仅 82%，超时集中在库存服务 ## 2. 备选方案分析（重点写“为什么不行”） ### 方案A：Saga模式（补偿事务） - ✅ 优势：业务逻辑清晰，各服务自治 - ❌ 劣势：补偿链路过长（平均5步），失败后用户感知延迟 >30s；且积分服务无逆向操作接口 - 📉 数据：模拟测试中，Saga失败率 17%，平均恢复时间 42s ### 方案B：本地消息表 + 定时扫描 - ✅ 优势：实现简单，依赖少 - ❌ 劣势：定时扫描间隔导致最终一致性延迟 ≥2min，违反“用户下单后5秒内可见物流单号”SLA - 📉 数据：压测显示，1000TPS下消息表写入延迟峰值 1.8s ### 方案C：事件驱动 + 消息队列（Kafka） - ✅ 优势：吞吐量高（实测 12000TPS），延迟可控（P99<100ms），支持死信队列重试 - ⚠️ 折衷：需增加Kafka运维成本；订单服务需改造为发布事件，非侵入式改造工作量≈3人日 - 📈 数据：小流量灰度7天，下单成功率提升至 99.2%，平均延迟 87ms ## 3. 最终决策及依据 **采用方案C（Kafka事件驱动）**，依据： - 直接满足SLA（<5秒可见物流单号），且预留扩展空间（后续可接入实时风控） - 运维成本增加可控（已有Kafka集群，仅需新增topic和监控） - **关键折衷记录**：为降低改造成本，订单服务采用“双写”模式（同步写DB + 异步发Kafka），接受极小概率（<0.001%）下DB成功但Kafka发送失败，此场景由下游服务幂等消费兜底 ## 4. 验收指标（可测量、可监控） - ✅ 下单成功率 ≥99% - ✅ 订单创建到物流单号可见时间 P99 ≤3s - ✅ Kafka消息积压 <1000条（监控告警阈值）

实操心得：design.md 的每一项技术选择，都必须回答三个问题：1）这个选择解决了proposal.md里的哪个具体痛点？2）它引入了什么新风险？3）我们如何监控和应对这个风险？我们曾因没写清“Kafka分区数设置为12的依据（基于当前峰值流量12000TPS * 1.5冗余系数 / 单分区吞吐1000TPS）”，导致上线后分区不足，紧急扩容引发服务抖动。现在，所有参数都要求附计算过程。

3.3 task.md：把“开发任务”变成“可验证的契约条款”

task.md 不是待办清单，而是面向未来的法律合同。它的颗粒度决定了项目能否真正可控。我们拒绝“实现用户登录”这种任务，坚持拆解到原子级可验证单元：

# [功能模块] Task Breakdown ## Task #1：JWT Token 生成与验证 - **依据**：design.md 第3.2节 "Token有效期与刷新机制" - **输入**：用户ID、角色权限列表、设备指纹 - **输出**：JWT token（含claims：`sub`, `role`, `exp`, `iat`, `jti`） - **验证标准**： - ✅ 生成token的`exp`字段 = 当前时间 + 2小时（硬编码，非配置） - ✅ `jti`为UUIDv4，确保全局唯一 - ✅ 使用HS256算法，密钥从环境变量`JWT_SECRET`读取（禁止硬编码） - ✅ 单元测试覆盖：100%分支覆盖率，含`exp`过期、`jti`重复、密钥错误三种异常场景 ## Task #2：Token 刷新机制 - **依据**：design.md 第3.3节 "Refresh Token 安全策略" - **输入**：有效refresh token - **输出**：新access token + 新refresh token（旧refresh token立即失效） - **验证标准**： - ✅ refresh token存储于Redis，key=`refresh:{jti}`，TTL=7天 - ✅ 每次刷新后，旧refresh token的Redis key被DEL操作 - ✅ 同一refresh token重复使用返回401，且记录审计日志 - ✅ 压测：1000并发刷新请求，99%响应时间 <200ms ## Task #3：登录失败锁定 - **依据**：proposal.md 第4节 "安全基线要求" - **输入**：用户名、密码 - **输出**：成功登录跳转，或失败提示（不区分用户名/密码错误） - **验证标准**： - ✅ 连续5次失败后，该IP地址被加入Redis黑名单`login:block:{ip}`，TTL=15分钟 - ✅ 黑名单检查在密码校验前执行，避免暴力破解 - ✅ 日志记录：`LOGIN_ATTEMPT_FAILED|ip=192.168.1.100|username=test|timestamp=...`

关键技巧：task.md 的每一条，都必须能直接转化为自动化测试用例或CI检查项。我们用脚本自动解析task.md，生成Jest测试骨架和SonarQube规则。例如，看到“密钥从环境变量读取”，CI就会检查代码中是否存在process.env.JWT_SECRET以外的密钥引用。看到“TTL=15分钟”，就会检查Redis SET命令是否带EX参数。这使得task.md不仅是开发指南，更是质量门禁。

4. 如何落地SDD？从“文档负担”到“效率引擎”的实操路径

4.1 工具链搭建：用最小成本撬动最大协同

SDD 的成败，80%取决于工具是否顺手。我们不用笨重的Confluence或Notion，坚持“代码即文档”原则，所有文档都放在Git仓库根目录，与代码同版本、同权限、同Review：

• 文档模板：提供标准化的.md模板（proposal-template.md, design-template.md, task-template.md），内置Markdown锚点和TODO标记，新项目cp即可用。
• 自动化检查：在CI中集成markdownlint检查基础格式，用自研脚本validate-sdd.py验证：
  • proposal.md 是否包含“成功定义”章节且含✅/⚠️/❌符号
  • design.md 中每个技术选择是否引用了proposal.md的痛点编号
  • task.md 中每个task是否关联了design.md的章节号
• 智能提示：VS Code插件SDD Helper，在编写代码时，自动提示：“当前文件修改涉及design.md第4.2节，请确认task.md中task#7已更新”。
• 可视化追踪：用GitHub Projects看板，将proposal.md的“成功定义”设为Epics，design.md的每个方案设为Issues，task.md的每个task设为子Issue，状态自动同步。

踩坑记录：早期我们尝试用Notion管理文档，结果出现“design.md在Notion里更新了，但Git里还是旧版”的灾难。后来强制规定：所有SDD文档必须以纯文本.md存在Git中，任何外部平台只是只读镜像。这看似麻烦，却杜绝了90%的版本混乱。

4.2 团队习惯养成：从“抗拒写文档”到“不写文档不敢开工”

改变习惯比改变工具难十倍。我们的渐进式推行策略：

• 第一周：只改commit message
  要求所有commit必须关联task编号，如git commit -m "feat(auth): implement JWT generation (task#1)"。这强迫开发者建立“代码→task→design→proposal”的追溯链。

• 第二周：强制proposal-review
  任何PR关联的task，必须先有proposal.md PR被合并。Review重点不是文笔，而是“成功定义是否可测量”。一次驳回，就让整个团队明白：模糊的目标不被允许。

• 第三周：design-md as source of truth
  所有API文档、数据库Schema、配置项，必须从design.md中提取生成（用swagger-from-design.py脚本）。当开发者发现“改了design.md就能自动生成API文档”，写design的意愿飙升。

• 第四周：task-driven standup
  每日站会只问三个问题：1）你今天要完成哪个task？2）这个task的验收标准是什么？3）卡点是否已在task.md中注明？——会议时间从25分钟压缩到8分钟。

真实体验：一位资深后端工程师最初嘲讽“写文档是给领导看的”，直到他负责的支付模块出bug，靠design.md中“幂等性key生成规则”一行，5分钟定位到前端传参错误。他第二天主动申请成为SDD模板维护者。最好的推广，是让文档成为解决问题的第一把手，而不是事后追责的证据。

4.3 规避常见陷阱：那些让SDD变“形式主义”的雷区

SDD极易滑向“为文档而文档”的深渊。我们总结出四大高危雷区：

1. “完美文档”陷阱

   • 表现：proposal.md写到10页，design.md画满UML图，task.md列了200条子任务
   • 解法：所有文档必须遵循“最小可行文档”（MVD）原则。proposal不超过2页，design核心决策不超过5条，task总数控制在20条以内。我们用“电梯测试”：你能用30秒向路人说清proposal的核心结论吗？不能，就删减。

2. “静态文档”陷阱

   • 表现：design.md定稿后不再更新，但实际开发中绕过了原方案
   • 解法：每次重大变更，必须触发SDD校准循环。例如，task#5因技术限制无法实现，不是偷偷改代码，而是发起新的design.md PR，说明“原方案B不可行，现采用方案C，理由见XXX”，并更新所有关联文档。

3. “单点 author”陷阱

   • 表现：只有Tech Lead写design.md，其他人只执行
   • 解法：强制“共同 authorship”。design.md开头必须列出：作者（主笔）、Reviewer（跨职能代表）、Approver（决策者）。我们曾规定，没有运维代表签字的design.md，CI直接拒绝合并。

4. “文档 vs 代码”陷阱

   • 表现：文档写得天花乱坠，代码却完全不遵循
   • 解法：用代码强制文档落地。例如，task.md要求“密码强度校验”，就在代码中植入硬编码规则：

     // src/utils/passwordValidator.js // @sdd-task: task#3.2 - Password strength validation per design.md 4.1 export const validatePassword = (pwd) => { if (!/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[!@#$%^&*]).{8,}$/.test(pwd)) { throw new Error("Password must be 8+ chars, with upper/lower/digit/special"); } };

     CI检查会扫描@sdd-task注释，确保每条task都有对应代码实现。

5. SDD 实战问题排查手册：从“文档写不完”到“文档救了命”

5.1 典型问题速查表

5.2 一次真实故障的SDD救援全过程

故障背景：某电商大促期间，订单创建接口成功率从99.9%骤降至62%，大量用户点击下单后无响应。

传统排查：

• 开发查日志，发现大量TimeoutException
• 运维查服务器，CPU正常，网络正常
• DBA查数据库，慢查询无新增
• 3小时后，仍无结论，临时扩容服务器，效果甚微

SDD驱动排查：

1. 锁定design.md：打开order-service/design.md，定位到“订单创建性能保障”章节，其中明确写：

   “订单创建接口P99延迟 ≤800ms，超时阈值设为1200ms，由Spring Cloud Gateway统一配置”

2. 验证契约：用curl直连Gateway，发现X-RateLimit-Remaining头为0，意识到是限流触发
3. 溯源proposal.md：查proposal.md中“大促容量规划”，发现写道：

   “按历史峰值1.2倍预估，需支持5000TPS，限流阈值设为6000TPS”

4. 发现矛盾：监控显示当前TPS仅4200，远低于6000阈值，为何触发限流？
5. 深挖task.md：在task.md中找到task#17：“实现基于用户等级的动态限流”，其验收标准写：

   “VIP用户限流阈值=普通用户×3，阈值配置从Redis读取，key=rate:limit:vip”

6. 真相大白：运维同事误将rate:limit:vip的值从18000改为1800（少了一个零），导致VIP用户限流过严。
7. 修复：10秒内修正Redis值，成功率瞬间回升至99.5%。

这次故障，SDD的价值不是预防（毕竟人为失误无法杜绝），而是将3小时的混沌排查，压缩为10分钟的精准定位。proposal定义了目标，design锁定了范围，task暴露了细节，三者叠加，让问题无处遁形。

5.3 个人经验沉淀：SDD让我少写的5类废话邮件

在推行SDD前，我每周平均写17封解释性邮件。现在，这个数字是0。因为SDD文档天然承担了这些沟通：

• “为什么这个需求要两周？”→ proposal.md中的“可选方案对比”和“成功定义”已说明
• “这个接口参数到底怎么填？”→ design.md的API章节和task.md的验证标准已定义
• “上次说的XX方案，现在进展如何？”→ GitHub Projects看板实时同步所有task状态
• “这个bug是不是我们改出来的？”→ Git Blame + task.md关联，5秒追溯到具体决策
• “上线后出了问题，谁来负责？”→ design.md的“决策依据”和proposal.md的“成功定义”划清责任边界

SDD不是消灭沟通，而是把情绪化、模糊化、重复性的沟通，转化为结构化、可追溯、一次性的文档资产。当你把精力从解释“为什么”转向解决“怎么做”，真正的开发效率才开始释放。

6. SDD 的边界在哪里？它不是银弹，而是你的开发罗盘

SDD 解决不了所有问题。它不擅长处理极度模糊的探索性项目（如AI模型训练的初期调参），也不适用于一次性脚本或个人学习项目。它的力量，恰恰在于承认边界，并在边界内最大化确定性。我把它比作航海罗盘：GPS（精确坐标）在开阔海域最有效，但在浓雾弥漫的峡湾，罗盘（方向指引）反而更可靠。SDD 就是那个在需求迷雾、技术混沌、协作摩擦中，始终指向“我们共同承诺了什么”的罗盘。

它不保证代码零bug，但保证每个bug都能快速归因；
它不承诺需求永不变更，但确保每次变更都有迹可循；
它不消除团队分歧，但把分歧从“我觉得”升级为“proposal第2.1条数据是否准确”。

最后分享一个小技巧：我们团队的SDD文档，最后一行永远是<!-- Last reviewed: 2023-10-05 -->。不是为了形式，而是提醒自己——文档不是刻在石头上的律法，而是写在沙滩上的潮汐线，它存在的意义，是让我们看清水来过、退过、又来了的方向。当你开始习惯在敲下第一个console.log前，先写完proposal.md的“成功定义”，你就已经告别了“氛围编程”。剩下的，只是让代码，忠实地兑现那份契约。