前谷歌工程师万字拆解：AI替你写代码的时代，你更需要写好一份设计文档
内容提要
本文介绍前谷歌工程师Michael Lynch的设计文档写作指南，核心是判断力：何时写、写多细、写什么。判断信号包括多人协作、周期超三月、长期运行、跨团队、需求模糊、灾难风险。文档分五类：项目定位、需求边界、技术方案、风险合规、协作留痕。关键是聚焦高代价决策，确保文档可独立阅读，推动评审而非争论。AI时代，工程师仍需掌握此能力。
延伸解读
设计文档的“判断力”比写作技巧更重要
文章强调，AI能辅助写代码，但无法替代工程师对“何时写、写多细、写什么”的判断。六个信号（多人协作、周期超三月、长期运行、跨团队、需求模糊、灾难风险）命中两条以上就值得写。这种判断力正是工程师区别于“代码生成器”的核心价值。
聚焦高代价决策，避免过度设计
Lynch提出一个实用法则：只把“做错代价大”的决策写进文档。例如，选择编程语言或存储后端这类难以更改的决策值得详细阐述；而像“加载更多”按钮的分页方式，改起来容易，就不必浪费评审时间。这能防止设计文档变成实现文档，保持其作为思考工具的意义。
文档需独立可读，推动评审而非争论
好的设计文档应能脱离作者独立阅读，因为评审者不会先听口头解释。因此，背景、目标、场景等部分要写得让没有背景知识的同事也能看懂。同时，文档的最终目的是推动评审，而不是陷入无休止的争论，因此要主动记录遗留问题和备选方案，促进高效决策。
Q&A
什么时候应该写设计文档？
根据前谷歌工程师Michael Lynch的指南，如果项目满足以下六个信号中的至少两个，就值得写设计文档：多人协作、开发周期超过三个月、系统会在生产环境长期运行、跨团队合作、需求模糊、存在灾难性风险。如果只命中一条，也大概率值得写。
设计文档应该写多详细？
设计文档的详细程度没有统一标准，取决于团队目标、风险、截止日期和团队文化。一个关键判断法则是：这个决策一旦做错，代价有多大？如果代价高且难以逆转（如选择编程语言），就需要详细阐述；如果代价低且容易修改（如分页加载方式），则不必浪费评审时间。
设计文档通常包含哪些部分？
设计文档通常包含五类内容：项目定位（标题、元信息、目标）、需求边界（背景、关联文档、目标、非目标、场景、术语表）、技术方案（图表、约束条件、SLO、监控告警、时间线、接口、依赖）、风险与合规（安全、隐私、法务）、协作留痕（日志、遗留问题、已解决问题、备选方案）。但并非每份文档都需要包含全部，应根据实际情况取舍。
设计文档中的目标和非目标有什么区别？
目标（Goals）描述项目完成后对用户、团队或公司的影响，而不是具体实现细节；非目标（Non-goals）则明确排除在项目范围之外的内容，防止读者误解。例如，目标可以是“减少因发布新版本导致的服务中断”，而非目标可以是“不引入Kubernetes”。
为什么设计文档中要包含场景（Scenarios）？
场景部分通过讲述系统在真实世界中的使用故事，帮助读者直观理解系统如何被使用，尤其是当目标描述比较抽象时。例如，描述用户如何创建报表、生成分享链接、同事点击链接查看只读副本，能让读者更清楚系统的实际交互。
在设计文档中如何定义SLO？
SLO（服务水平目标）是将模糊的要求转化为具体可衡量的指标，例如可用性、延迟、规模等。设计文档中应定义SLO，而不是SLA，因为SLA包含经济赔偿，而团队内部通常不需要。例如，主管说“移动端要流畅”，你需要明确具体延迟标准，如2毫秒。
设计文档中为什么需要记录备选方案？
记录备选方案可以提前回答读者可能提出的“为什么不用XX方案”的问题，尤其是那些一开始看起来有吸引力或你曾花时间调研的方案。但只需简短说明有力的备选方案是什么以及为何未采用，不必过度详细。
AI时代工程师还需要写设计文档吗？
需要。AI可以辅助写代码，但设计文档考验的是判断力——知道何时写、写多细、写什么，以及如何识别高代价决策和风险。这些判断AI暂时无法替代，是工程师区别于代码生成器的核心能力。
