03 · 技术方案写作：从需求到可评审的设计文档
技术方案是"写下来之前先想清楚"的产物，不是"写完之后再补"的文档。 它把需求、设计、权衡、风险变成一页可评审的东西，让错误发生在文档阶段，而不是上线之后。
速览卡
| 项 | 内容 |
|---|---|
| 一句话定位 | 用"背景 → 目标 → 方案 → 权衡 → 风险"五段式，把一次改造写成可评审、可追溯、可回滚的设计文档 |
| 核心内容 | 为什么写方案、五段式结构、每段怎么写、评审会怎么开、常见反模式、和 F02/F04 的关系 |
| 读完能回答 | 一份方案要包含哪些部分？评审时重点看什么？怎么让方案不被"空谈"？ |
| 相关板块 | F02 · 需求拆解 ｜ F04 · 技术选型 ｜ B32 · 规格驱动开发与 AI 协作 |
一、方案文档解决什么问题
没有方案文档的改造长这样：开完会各做各的，联调发现接口对不上，评审时才发现方向错了，改完上线又回滚。
方案文档的价值：
| 价值 | 说明 |
|---|---|
| 逼自己想清楚 | 写下来的过程会暴露"我以为我想清楚了"的漏洞 |
| 让评审有对象 | 别人能针对具体段落给意见，而不是对着空气聊 |
| 让决策可追溯 | 三个月后回看，知道"为什么选 A 不选 B" |
| 让交接变轻 | 新人看方案文档就能理解系统怎么来的 |
前端转全栈的额外收益：你能把前端 + 后端 + 数据 + 部署写进同一份方案，站在全链路视角做设计，这是纯前端或纯后端工程师少有的优势。
二、五段式结构
一份可评审的方案，最少五段，顺序固定：
text
一、背景与问题 为什么现在要做这件事（现状痛点 + 触发条件）
二、目标与非目标 这次要做到什么、明确不做什么
三、方案设计 总体架构 + 关键流程 + 接口/数据契约
四、方案对比 为什么是这个方案（候选方案 + 取舍 + 决策）
五、风险与回滚 哪里会出事、怎么监控、怎么回退顺序即逻辑：先说清问题，再谈方案。很多人把第三段写得极长、第一段一笔带过，评审时发现大家连"要解决什么"都没对齐。
三、每一段怎么写（含示例）
3.1 背景与问题：一页纸讲清"现状"
写清楚三点：现状是什么、痛点是什么、不做会怎样。用具体数据，不用形容词。
text
现状：设备列表在弱网下平均 3.8s 出首屏，P50 1.2s / P95 6s。
痛点：用户点击后长时间空白，跳出率随 P95 明显上升。
不做会怎样：Q3 留存目标大概率达不成。3.2 目标与非目标：把 F02 的验收搬进来
目标要可观测（数字或行为），非目标要写"这次不做"：
| 目标 | 非目标 |
|---|---|
| 首屏 P95 降到 2s 内 | 不做离线缓存（下个迭代） |
| 弱网下先出骨架屏 | 不做多端同步 |
3.3 方案设计：给"别人能实现"的细节
- 总体架构：新增/改动的模块，一张图或几行文字说明数据流
- 关键流程：主路径（正常流程）画清楚，异常路径单独列
- 契约：接口、字段、错误码、空数据约定（前端转全栈尤其要把契约写成方案的一部分）
3.4 方案对比：把"为什么选它"写下来
至少列 2~3 个候选，用统一维度对比，最后给出决策和理由：
| 方案 | 优点 | 代价 | 决策 |
|---|---|---|---|
| 方案 A：前端聚合 | 改动小、快 | 多请求、弱网差 | 放弃（痛点就是弱网） |
| 方案 B：后端聚合接口 | 一次请求、可控 | 后端要加接口 | 采用 |
3.5 风险与回滚：写给"出事了怎么办"
| 风险 | 监控信号 | 回滚方式 |
|---|---|---|
| 新接口拖垮数据库 | QPS / 慢查询上升 | 前端切回旧接口（功能开关） |
| 数据迁移丢数据 | 对账脚本跑批 | 保留旧表双写 |
回滚写不出来，说明方案还没想清楚。"回滚靠 git revert"不算回滚，要看线上数据、依赖、迁移怎么办。
四、评审会怎么开
评审不是"念文档"，是对决策负责：
- 会前：方案提前发，评审人先读，会上只讨论分歧
- 会上：主讲 15 分钟讲清背景、目标、方案、对比；评审人重点打风险
- 会后：把结论写进文档（采纳 / 驳回 / 修改点），更新状态
评审最常见的失败：把评审会当成"方案宣讲会"，参会人临时看文档，最后变成"都挺好"。会前阅读 + 会后结论落档，才是评审的价值。
五、反模式
| 反模式 | 表现 | 对策 |
|---|---|---|
| 方案 = 代码大纲 | 通篇"用 X 组件调 Y 接口"，没有权衡 | 补"为什么"和"对比" |
| 方案 = 架构图 | 一张大图没有文字决策 | 每个关键决策配一句话理由 |
| 写给别人看 | 通篇自我辩解 | 只写"事实 + 决策 + 风险"，让数据说话 |
| 无版本/无状态 | 不知道哪版是最新、是否已采纳 | 文档头部标注状态与更新时间 |
自检清单
- [ ] 方案包含"背景 → 目标 → 方案 → 对比 → 风险"五段
- [ ] 背景里有具体数据或现象，不是形容词
- [ ] 目标可观测、非目标明确写了"这次不做"
- [ ] 契约（接口/字段/错误码）已落到文档
- [ ] 至少对比 2 个候选方案，决策有理由
- [ ] 每个风险都有监控信号和回滚方式
- [ ] 文档标注了状态、版本与更新时间
常见误区
| 误区 | 事实 |
|---|---|
| "小改动不用写方案" | 判断标准是风险不是大小；小改动写一页"决策记录"也值得 |
| "方案写得越长越好" | 长度和清晰度无关，重点是决策可追溯 |
| "评审通过就完事了" | 结论要落档，否则三个月后没人知道当时为什么这么定 |
| "方案写完再想风险" | 风险应该在设计时同步考虑，写完补只是走形式 |
动手练习
练习 A：给最近一个功能补方案
选一个已上线的功能，按五段式补一份"回溯方案"，重点写第三段契约和第五段回滚——你会发现当初很多决策没被记录。
练习 B：写方案对比
拿 F04 技术选型的候选对比表，扩写成方案文档第四段，补上"为什么采用 / 放弃"的完整理由。
练习 C：模拟评审
把方案发给一位同事，只给 15 分钟，让他指出"哪一段最没说服力"。针对反馈修改后，再发一次。
相关文档
本区
- 02 · 需求拆解 —— 方案的目标与非目标来自这里
- 04 · 技术选型 —— 方案第四段的候选对比方法论
- 01 · 工程方法论全景 —— 闭环定位
其他域
- B32 · 规格驱动开发与 AI 协作 —— 规格驱动与 AI 协作的实战
- C02 · API 设计 —— 方案里的接口契约怎么写
- D02 · 部署与 CI/CD —— 方案的发布与回滚章节参考