技术设计:把模糊想法变成可评审的文档
这一章讲三件事: 设计流程的真实形状(螺旋,不是直线); 为什么「定义问题」比「选方案」更值得花力气; 以及设计文档怎么写、怎么评、怎么不让它腐烂。 读完你会拿到一份 11 节的设计文档模板,和把小任务缩放成 3 句话的判据。
1. 这一章讲什么
被要求改系统时,入门工程师最常见的动作是直接跳进编码。原书开篇就指出这条路的风险:一心潜入代码在小事上尚可,但你会最终遇到一项庞大到跳不进去的任务——那时你需要技术设计1。
本章在全书链条里的位置:第 02 章的「债务提案邮件」和第 04 章的「依赖九问」都是它的局部;本章把这套思考升级成完整流程——它的产出(设计文档)是第 11 章架构决策的载体,它的「发布计划」一节直接调用第 07 章的展开模式。
2. 顶层全景
问题空间(不清楚)
┌──────────────────────────────┐
│ 探索:问利益相关者 / 调查 / 实验 ←─┐
└──────────┬───────────────────┘ │ 螺旋式上升:
▼ │ 每转一圈,
撰写设计文档 ──→ 分发评审 ──→ 修订 │ 问题更清楚、
▲ │ │ 信心更足
└──────────────┘ │
┌──────────────────────────────┐ │
│ 实施(出现偏差 → 回写文档) ────────┘
└──────────────────────────────┘
图说:设计不是「研究完→写文档→拿批准」的流水线,
而是独立工作与协作讨论交替的螺旋。主走查在 3.2:
一个特性请求如何被四个提问改写。
3. 核心原理
3.1 设计是螺旋,不是漏斗
原书把它画成一个圆锥:你从圆锥底部出发——那里你连问题空间(要解决的问题的边界和内容)、需求和可能的方案都不清楚,所以「在这个过程的早期,你不可能拥有一份令你有信心的解决方案」2。研究、头脑风暴、小实验,让你每转一圈都更清楚一点;到了圆锥顶部,你对方案充满信心,才把它传给全组织评审。而且设计没有终点:实施中一定会出现偏差,任何重大偏差都必须回写进设计文档——否则文档变成对后来者的误导3。
这个螺旋观解释了两个工作习惯。给设计留时间:好的设计需要创造力,原书引保罗·格雷厄姆《管理者的时间表,制造者时间表》——写代码的人需要整块不被打断的时间,关聊天、关掉各种提醒,并且允许思想在散步和泡茶时继续游荡4。用设计尖峰对冲交付压力:尖峰(design spike)是极限编程的术语,指有时间限制的调查——在冲刺里排一个尖峰任务,给你一段「只管想清楚」的合法时间5。
3.2 主走查:一个特性请求是怎么被改写的
设计流程的第一步不是想方案,是定义问题。原书给了两个动作:「用你自己的语言向利益相关者重述问题」;以及一把裁剪刀——问「如果我们不解决这个问题会怎么样?」,如果答案可以接受,很多问题根本不需要解决6。
我们拿原书自带的例子走完全程7。
输入:原始特性请求。 「供应经理希望看到库存页面上列出的每件物品的目录和页码,显示目录信息将使我们在供应不足时更容易重新订购物品。我们可以让合同工来扫描所有的目录,我们可以使用一个 ML(机器学习)模型将扫描的图像转换成数据库中的物品描述。」——注意这个请求自带了一个方案(把目录扫描成图片,再用 OCR(从图片里认出文字)转成数据)。
提问。 原书说这样的请求应该触发一串问题:供应经理现在是怎么下订单的?一件物品会不会出现在多个目录?没有这个特性时他们怎么应付?痛点是什么?哪个痛点对企业影响最大?
重述后的问题陈述。 回答之后,问题被改写成完全不同的形状:供应经理需要的是在供应量不足时方便地重新订购物品;现状是他们在 Excel 表格里人工维护「库存条目—供应商名称—SKU(库存量单位,商品的唯一编号)」的对照,又慢又容易错;一个 SKU 可能有多位供应商,经理想比价压成本,但电子表格限制每件物品只能记一家;他们的优先级排序是:数据准确性 > 下单时间 > 订单成本;另外约一半供应商本来就有在线目录。
结论。 原书自己总结:完善的问题描述「将导致一份与原来截然不同的解决方案」——扫描目录和机器学习模型这两个方案被抛弃了;真正的问题空间里,在线供应商目录的信息反而成了方案的原料8。
这条走查的每个机制都值得单独记:重述暴露误解;「不解决会怎样」砍掉伪需求;问「现在怎么对付的」挖出真实的现状;问优先级防止平均用力。写出来的问题陈述还要明确范围——哪些在范围内、哪些 明确不在,分发出去请大家纠偏9。
3.3 探索:调查、实验、批判
问题定义清楚后,进入方案空间的探索。三个动作各有一条纪律:
调查要带过滤嘴。 网上有大量别人解决类似问题的资料:工程博客、行业大会的幻灯片、学术论文(顺着论文末尾的参考文献还能滚雪球)。但原书提醒两件事:公司博客「本质上是一种营销活动」,常常只描述简化后的架构、略去棘手的部分——可以给作者写信要细节10;以及那句值得贴在显示器上的话:你的问题不是谷歌的问题,即使你在为谷歌工作——把相似但不相同的方案全盘照搬,是设计中最常见的错误11。
实验要舍得扔。 写 API 草案、做部分实现、跑性能测试,会让你对想法增长信心、暴露权衡;但「不要迷恋你的实验性代码」——概念验证的使命是说明想法,然后被扔掉或重写;不写测试、不打磨,以最快的速度学习12。
给创造力留物理条 件。 除了 3.1 的时间块,原书还给了一条朴素建议:找出自己最能深度集中的时段(克里斯是午饭后,德米特里是清晨),把它在日历上圈出来并保护它13。
3.4 设计文档:写作即思考
什么时候需要文档? 不是每个变更都要。原书给了三个标准:项目需要至少一个月的工程时间;变更对扩展和维护有长期影响;变更显著影响其他团队14。三条都不到的,3 句话的问题陈述就够了——流程可以缩放,这是本章开头的承诺。
文档是工具,不是交付物。 原书列了它的五重用途:帮你思考、获得反馈、让团队了解情况、培养新工程师、支撑项目规划15。其中最容易被低估的是第一重:「写作拥有一种暴露你不知道的东西的能力」——写不下去的地方,就是你还没想清楚的地方16。写作还有个物理特性:它是一种有损的信息传递方式——你写下想法,队友在脑子里不完整地重建它;好的写作提高还原度,而且 写得好的人不会被忽视17。
文档会腐烂,有两个经典死法。 陷阱一:提案完成后文档再没更新过,与实现渐行渐远,误导未来的人;陷阱二:文档更新了,但讨论的历史丢了——后来的人看不到「为什么当年不做 X」,于是重蹈覆辙18。原书给的保鲜技巧:把设计文档和代码放进同一个库做版本控制——代码评审的流程顺带评审文档,代码变了文档一起改19。
模板。 原书给了一份 11 节的结构,要点摘录20:
| 节 | 回答的问题 |
|---|---|
| 概要 | 解决什么问题、为什么值得解决;给不同读者(安全/运维/数据)指路 |
| 现状与背景 | 系统现在长什么样,专有名词是什么意思 |
| 变更的目的 | 为什么现在做;好处要与业务挂钩——「减少 50% 的内存占用」不如「解决安装软件时最常见的拒绝理由」21 |
| 需求 | 可接受方案必须满足的硬约束(用户/技术/安全合规) |
| 潜在的解决方案 | 被你否掉的方案和否掉的理由——预先回答「为什么不做××」 |
| 建议的解决方案 | 你选了什么,为什么 |
| 设计与架构 | 构成图、UI/代码/API/持久层各自的变更点 |
| 测试计划 | 怎么验证(不是逐条测试用例) |
| 发布计划 | 部署/展开策略、特性开关、回滚——第 07 章的机制在这里落笔 |
| 遗留的问题 | 明确列出「已知的未知」,这是征求读者意见的钩子 |
3.5 协作:不要让人惊讶
设计最终是团队的事。原书的协作章有三块:
认清你的流程档位。 常见两档:架构评审(重)——设计必须拿到运维、安全等外部利益相关者的批准,要文档、可能多轮会议,只有大型或有风险的变更值得走22;RFD(request for decision,请求裁定)(轻)——一份精要的书面材料+白板讨论,用来快速敲定「需要一些讨论但不必全面评审」的决定23。先搞清楚你所在团队的档位:错过一步设计评审,项目可能在最后一刻脱轨。
黄金律:不要让人惊讶。 如果正式的设计文档是其他团队第一次听说你的工作,「你就是在为自己的失败埋下伏笔」——突然出现又没给人家发言权,再好的设 计也会迎来本能的抵触24。反过来,在研究阶段就找相关团队闲聊式地要反馈,不但设计更好,「早期参与你工作中的各方都可以在以后成为你工作的拥护者」25。
头脑风暴是设计讨论的主形态。 原书给了几条参数化的建议:2 到 5 人;约两个小时——思想需要时间展开,别压缩;用白板不用幻灯片;指定会议记录员但要换着人来,不然总做记录的人没法贡献26。对个人还有一条:为别人的设计出力——提出问题和给予建议一样重要,你的问题可能帮到所有同样疑惑的人27。
4. 作者的判断与证据
- 「设计是螺旋」:作者判断,依据是他们主持过大量设计流程的经验;圆锥图是示意,不是测量。
- 库存案例:原书自带的完整示例(带前后两个版本的问题陈述),是本章唯一走完全程的实证材料。
- 「写作暴露你不知道的东西」:作者判断,原书加了 句「在这一点上请相信我们」——自认是经验之谈。
- 「博客是营销」:作者对信息源的警惕,与第 01 章「在线资源不如出版物可靠」的口径一致。
- 三个「是否需要设计文档」的标准:作者给的行业经验值(一个月工时等),不是规范。
5. 边界与局限
- 「一个月工时」这类阈值是硅谷中型团队的口径,小公司可能几周的变更就需要正式设计,大公司一个月的项目可能还不值得惊动评审。
- 本章只讲流程,不讲设计思维本身:如何划分模块、如何选数据结构,是第 11 章和无数算法书的领域。
- 头脑风暴的规模建议(2-5 人)没有讨论远程会议的变体;异步分布式团队需要改造。
- 模板没有配「写坏了的样子」的反例——读者只能靠样例正向模仿。
6. 可带走的
- 任务大到「跳不进去」时,先停下来做设计;小的用 3 句话,大的才上全流程;
- 设计先问「如果不解决会怎样?」——过不了这关的问题不立项;
- 原始需求常常自带方案;重述问题、问现状、问优先级,方案可能整个换掉;
- 别照搬谷歌:你的问题不是谷歌的问题,即使你在为谷歌工作;
- 概念验证代码的宿命是垃圾桶——别测试、别打磨,尽快学;
- 给设计圈出整块时间;冲刺里排「设计尖峰」对冲交付压力;
- 设计文档写给自己看:写不下去的地方就是没想清楚的地方;
- 文档要保鲜:与代码同库版本控制,实施偏差必须回写;
- 走评审流程前先分清档位:架构评审(重)还是 RFD(轻);
- 「不要让人惊讶」:早期、随口、经常地同步——早期参与的人会成为你的拥护者。
7. 原文地图
| 主题 | 原书章 | 原文位置 |
|---|---|---|
| 跳不进去的任务 | 第10章 技术设计流程 | text/19-ch10.txt:3(搜「直接跳入」) |
| 螺旋式上升 | 第10章 技术设计流程 | text/19-ch10.txt:24(搜「螺旋式上升」) · text/19-ch10.txt:32(搜「圆锥体的底部」) |
| 偏差回写 | 第10章 技术设计流程 | text/19-ch10.txt:57(搜「重大的偏差」) |
| 制造者时间表 | 第10章 技术设计流程 | text/19-ch10.txt:165(搜「保罗·格雷厄姆」) |
| 设计尖峰 | 第10章 技术设计流程 | text/19-ch10.txt:184(搜「design spike」) |
| 强有力的提问 | 第10章 技术设计流程 | text/19-ch10.txt:76(搜「解决这个问题会怎么样」) |
| 修剪范围 | 第10章 技术设计流程 | text/19-ch10.txt:83(搜「不要害怕修剪」) |
| 主走查:特性请求 | 第10章 技术设计流程 | text/19-ch10.txt:88(搜「供应经理希望看到」) · text/19-ch10.txt:91(搜「machine learning」) |
| 主走查:重述 | 第10章 技术设计流程 | text/19-ch10.txt:90(搜「重新订购物品」) · text/19-ch10.txt:108(搜「SKU 可能有多位供应商」) · text/19-ch10.txt:111(搜「优先事项」) |
| 方案被抛弃 | 第10章 技术设计流程 | text/19-ch10.txt:118(搜「已经被抛弃了」) |
| 博客是营销 | 第10章 技术设计流程 | text/19-ch10.txt:128(搜「营销活动」) |
| 不是谷歌的问题 | 第10章 技术设计流程 | text/19-ch10.txt:142(搜「不是谷歌的问题」) |
| 概念验证 | 第10章 技术设计流程 | text/19-ch10.txt:153(搜「概念验证类的代码」) |
| 文档三标准 | 第10章 技术设计流程 | text/19-ch10.txt:202(搜「一个月的工程时间」) |
| 写作暴露未知 | 第10章 技术设计流程 | text/19-ch10.txt:229(搜「暴露你不知道的东西」) |
| 有损传递 | 第10章 技术设计流程 | text/19-ch10.txt:256(搜「有损的信息传递」) |
| 两个陷阱 | 第10章 技术设计流程 | text/19-ch10.txt:278(搜「提案文件被废弃」) |
| 同库版本控制 | 第10章 技术设计流程 | text/19-ch10.txt:289(搜「同一个库中进行版本控制」) |
| 模板 | 第10章 技术设计流程 | text/19-ch10.txt:308(搜「现状与背景」) |
| 50% 内存的反例 | 第10章 技术设计流程 | text/19-ch10.txt:349(搜「50%的内存占用」) |
| 架构评审 vs RFD | 第10章 技术设计流程 | text/19-ch10.txt:456(搜「架构评审委员会」) · text/19-ch10.txt:466(搜「RFD」) |
| 不要让人惊讶 | 第10章 技术设计流程 | text/19-ch10.txt:485(搜「为自己的失败埋下伏笔」) |
| 拥护者 | 第10章 技术设计流程 | text/19-ch10.txt:491(搜「拥护者」) |
| 头脑风暴参数 | 第10章 技术设计流程 | text/19-ch10.txt:510(搜「2 人到 5 人」) · text/19-ch10.txt:513(搜「两个小时左右」) · text/19-ch10.txt:521(搜「白板而不是幻灯片」) · text/19-ch10.txt:524(搜「会议记录员」) |
| 为设计出力 | 第10章 技术设计流程 | text/19-ch10.txt:542(搜「问题会帮助你成长」) |