技术方案文档怎么写

技术方案的价值在评审会上就兑现完毕：把分歧提前暴露，避免写代码时返工。文档不需要优美，需要的是可被挑战。

一个够用的骨架

1. 背景与目标（3-5 句） 要解决什么问题、为什么现在做、成功的标准是什么。让不了解上下文的人能读懂。

2. 需求边界 明确「做什么」，同样重要的是「不做什么」。范围蔓延大多源于这里没写清楚。

3. 方案概述 一图胜千言：模块关系、数据流、时序。文字部分写核心决策——选了什么，为什么。

4. 关键设计点 每个值得讨论的点独立成节：备选方案、取舍理由。例：

库存扣减选择「Redis 预扣 + 数据库乐观锁落库」。 备选的纯数据库悲观锁在压测中（200 并发）出现锁等待超时；纯 Redis 方案在对账延迟窗口内有超卖风险，故组合使用。

5. 兼容与迁移 存量数据怎么处理、接口是否破坏兼容、新老版本共存期多长。

6. 风险与预案 列出 top 3 风险，每条带触发条件和应对。写不出风险，说明还没想透。

7. 上线计划 灰度策略、监控指标、回滚方式。回滚方案写不出来的方案，本质上没有完成设计。

写作的几条纪律

• 先写备选方案的缺点，再写优点——强迫自己诚实；
• 数字比形容词可信：「压测 QPS 3500」而不是「性能很好」；
• 方案文档的核心章节是「为什么这么选」，实现细节可以后补到代码注释里；
• 长度控制在评审人 15 分钟内读完。写不完说明拆分任务，而不是写更长。

评审会的开法

提前 24 小时发出文档，会上只讨论分歧点，不朗读文档。每个分歧的结论当场记入文档（包括被否掉的方案和理由）——这份记录在下一次类似决策时的价值，超过方案本身。

事后验证：上线后回看文档，「预判的风险发生了吗」「性能数字对得上吗」。这份对照会快速提高估算能力——这是写方案最大的隐藏收益。