Google 的设计文档文化：写文档不是目的，把权衡想清楚才是
前言
Malte Ubl（Google 资深工程总监，现 JavaScript 基础设施负责人）七年前写过一篇《Design Docs at Google》，讲 Google 内部的设计文档文化。这篇是老经典，Gergely Orosz（Uber）转发过，Uber 的 RFC/ERD 制度也和它同源。 " 为什么现在还值得读？因为 AI 编程时代写代码越来越便宜，但"决定写什么代码"这件事没有变便宜——设计文档的核心恰恰是记录你为什么这么决定。
文章里有句话值得先放在这：
软件工程师的工作不是生产代码，而是解决问题。在项目早期，非结构化文本可能比代码更好的工具——更简洁、更易理解、在更高的层面沟通问题和方案。
- 原文：https://www.industrialempathy.com/posts/design-docs-at-google/
一、设计文档是什么
先说它不是什么：不是格式严格的规定文档，不是实现手册，更不是给老板看的汇报材料。
它是一份相对非正式的文档，由系统的主作者在动手写代码之前写，记录高层实现策略和关键设计决策——重点是决策时的权衡（trade-offs）。
除了记录设计本身，它还顺手干六件事：
- 在改动还便宜的早期，暴露设计问题
- 在组织内围绕设计达成共识
- 确保安全、隐私、可观测性这些横切关注点被考虑
- 把资深工程师的知识规模化地灌进组织
- 形成组织关于设计决策的记忆
- 成为设计者技术履历里的一份作品
第一条规则就一个词：用什么形式写，取决于项目。没有强制模板。但实践里确实沉淀出了一个被反复验证的结构。
二、核心模块：一份设计文档的解剖
几个模块单独说说。
非目标是精华。不是"系统不该崩溃"这种反着说的目标，而是本可以合理成为目标、但你明确选择不做的。作者举例：设计数据库时，ACID 合规是目标还是非目标？你必须知道。而且就算它是非目标，如果某个方案顺带提供了 ACID 又不伤害真目标，你照样可以选它——非目标是决策边界，不是禁令。
被否掉的备选方案，可能是全文最重要的章节。列出那些"合理情况下也能达到类似效果"的设计，重点写每个的权衡、以及为什么这些权衡在当前项目目标下不如主方案。读者心里正嘀咕"为什么不那样做"，这一节就是回答。
克制是共同美德。API 别粘贴完整接口定义，数据存储别粘贴完整 schema，代码只在描述新算法时才出现——它们的共同问题是啰嗦、含无关细节、很快就过时。只写和权衡相关的部分。
横切关注点是组织级的抓手。团队应该标准化自己必须考虑的关注点清单。Google 要求项目有独立的隐私设计文档，有专门的安全和隐私评审——虽然评审只要求在上线前完成，但最佳实践是尽早拉安全隐私团队进场，让设计从第一稿就把这些考虑进去。
三、约束程度决定文档形态
这是原文里最容易被忽略、但最见功力的一节：解空间的约束程度，决定设计文档该长什么样。
一端是绿地项目：目标明确，方案自由，文档可以天马行空，但必须快速定规则收敛，否则解空间大到无法讨论。
另一端是强约束系统：难改的遗留系统、受宿主语言限制的库设计。这种情况你能做的事屈指可数，文档的重心变成创造性地组合受限选项——可能有好几个方案，没有一个真正好，文档的任务是选一个伤害最小的。
两种情况的文档长得完全不一样。拿模板硬套，是设计文档变成形式主义的第一步。
四、主执行链路：设计文档的生命周期
四个阶段里，有几点值得抄走：
评审的陷阱是流程。轻量做法是发到团队列表让大家评论；重度做法是正式评审会。后者很有价值但会显著拖慢进度——把最关键的反馈拉到前面来要，别堵在评审会上。Google 自己也走过弯路：小公司时代靠一个中央邮件列表靠资深工程师把关，公司大了以后集中式玩不转了。
评审的真正价值要摆对位置。不是"发现问题"，而是"在改动还便宜的阶段发现问题"——把组织的集体经验灌进设计，顺便保证横切关注点没被落下。
实现期文档会烂，有救。计划撞上现实，设计必然要改。经验法则：系统没上线，文档必须更新。现实中人类懒得更新文档，改动常常变成一份份新文档——最后的状态像美国宪法加一堆修正案。作者的建议很朴素：至少从旧文档链接到这些修正案，给未来做"文档考古"的维护工程师留条活路。
维护期的妙用是自省。Google 工程师接手陌生系统的第一反应往往是"设计文档在哪？"而对作者自己：一两年后重读你写的设计文档——哪些判断对了？哪些错了？今天你会怎么决定？这是工程师进阶最好的练习之一。
五、什么时候不写
写设计文档是有成本的，这笔账文章算得很清醒。
判断的核心是：设计方案是否模糊——因为问题复杂、方案复杂，或者两者都有。不模糊，就别写。
一个明确的反指标：如果你的文档本质上是"实现手册"——通篇"我们打算这么做"，没有权衡、没有备选、没有决策过程（或者方案简单到根本没有权衡）——那你还不如直接开始写代码。
还有一组常见的抬杠：敏捷开发要不要设计文档？作者的回应有两层：
- 敏捷不是不为已知问题把方案想对的借口——大多数项目总有一批真正已知的问题
- 原型本身可以就是设计文档的一部分。"我试过了，能跑"是支持某个设计最好的论据
快速迭代和设计文档不兼容？兼容，把文档写小就行。文档给了一个很实用的中间形态：1-3 页的迷你设计文档——增量改进、敏捷项目的子任务都能用，步骤和大文档一样，只是更精简、聚焦在有限的问题集上。
最后是自查清单，五个问题：
- 你对正确的软件设计没把握，值得花前期时间换取确定性吗？
- 让平时没空逐行看代码的资深工程师参与设计，有帮助吗？
- 设计方案模糊甚至有争议，围绕它达成组织共识有价值吗？
- 团队是否有时会忘记考虑隐私、安全、日志这些横切关注点？
- 组织是否急需文档来提供遗留系统的高层洞察？
三个及以上答"是"，你的下一个项目就该写设计文档了。
记住
工程师的工作不是生产代码，而是解决问题。设计文档的核心不是格式，是把权衡写下来——你考虑过什么、放弃了什么、为什么选这个。
结构可以记：背景、目标与非目标、设计本体、被否掉的备选、横切关注点。但解空间的约束程度决定文档形态，模板别硬套。
该不该写就看一个问题：设计方案模糊吗？模糊，写；不模糊，直接动手。文档太大？拆成迷你设计文档，一样走全流程。
参考资源
- 原文：Design Docs at Google — https://www.industrialempathy.com/posts/design-docs-at-google/
- 作者：Malte Ubl（Google 工程总监）
- 同源实践：Uber RFC/ERD 制度