我写过或评审过的每一份设计文档，都活在两个对话的交叉点：文档声称要讲的那个技术对话，以及组织实际上正在进行的关于范围、所有权和预算的政治对话。假装只有第一个存在，就是设计被批准之后却还是在原地绕圈的原因。这篇文章是我学会在不失去任何一边的情况下为两种受众写作的过程。

两种受众，两种对话

每份好的设计文档同时在回答两个问题：

  • 技术问题： 这个东西应该怎么运作？
  • 政治问题： 谁拥有它，谁资助它，谁获得功劳，谁失去选项，谁必须点头才能让它发生？

文档声称是关于第一个的。会议通常是关于第二个的。如果你只为技术受众写，你会得到”看起来不错，我们缩小范围吧”这类评论，然后眼睁睁看着你的范围三周后在一个 Slack 讨论串里重新扩大，而你没有参与其中。

我是怎么吃到苦头才学会这个的

在我早期的一次工程管理任期里，我写了一份我当时认为非常精彩的基础设施整合设计文档。架构图：干净。权衡：列举了。迁移计划：原子的。替代方案：考虑过了。

文档在评审中被批准了。六个月后，项目交付了大约40%的计划，两个相邻团队在做同样工作的各自版本，而我在一个房间里试图向一个 VP 解释为什么我们没做完。我走出那个房间，意识到：

  • 我的文档从没点名三个对我正在整合的系统有重叠主张的 VP。
  • 它从没承认 A 团队的 on-call 轮值是迁移窗口上的一个约束。
  • 它从没说我们刻意不做什么，这意味着其他团队假设他们关心的功能都在范围里。
  • 它从没说谁会在建成之后拥有整合后的系统，这意味着当它真正重要时，答案变成了”没有人”。

架构是没问题的。文档在政治上失败了，我以惨痛的方式学到了——政治是设计的一部分。

我现在使用的模板

从那以后我写的每份设计文档都有这些部分，按这个顺序。政治性的部分是承重的，不是可选的：

1. 问题（一段话，用户或运维可见的）
2. 约束（团队、预算、时间线、现有系统）
3. 提案（细节之前的一段话总结）
4. 非目标（这个方案明确*不*做什么）
5. 考虑过的替代方案（至少两个；每个附上失选理由）
6. 技术设计（图表+文字）
7. 迁移/推出计划
8. 所有权（具体的人名；"平台团队"不是一个名字）
9. 悬而未决的问题（我们还不知道的）
10. 决策日志（评审中决定了什么、何时、由谁）

所有人都期待的部分是3、6和7。架构住在那里。但第2、4和8部分才是文档要么推动项目落地、要么悄悄杀死它的地方。

约束不是脚注

第2部分应该是评审中讨论最激烈的部分。不是技术设计。是约束。

约束长这样：

  • “A 团队的 on-call 轮值无法消化更多告警——任何新服务在我们切换流量前必须满足零增量 page 的标准。”
  • “数据库迁移窗口每季度2小时。任何需要更多时间的设计都无法交付。”
  • “这个项目的预算是额外基础设施支出零元——我们必须在现有容量内运行。”
  • “VP X 已向董事会承诺这个功能在 Q3 交付。无论工程价值如何，一个滑过 Q3 的设计在政治上代价昂贵。”

如果你把这些写下来，你就把政治对话写进了文档。 现在阅读它的人知道他们在同意什么或反对什么。另一种做法——把这些约束留为隐式，希望每个人都和你有同样的理解——是六个人带着六个不同的项目走出设计评审的方法。

非目标是你保护范围的方式

第4部分——非目标——是任何设计文档里杠杆最高的单一部分。

它明确说：” 这个提案不包括 X、Y 或 Z。如果你想要那些，那是另一份文档的事。”

在健康的设计评审里，非目标部分是范围蔓延被早期捕获的地方。没有它，范围蔓延会在批准后的几个月里悄悄发生，当时不在评审现场的利益相关者开始假设他们相邻的关切被包含了。

我现在拒绝批准没有非目标部分的设计文档。没有非目标的文档是一个通过遗漏同意了一切的文档。

所有权要落到人名，不是头衔

第8部分——所有权——是你要么分配责任、要么把它泄漏进虚空的部分。

好的：

所有权： Amal H. 拥有推出。推出后，库存团队（DRI：Ben L.）拥有运维。SLO 定义在 ops/inventory.md。在稳定运行90天后，所有权转移给平台团队（DRI：Priya N.）做长期维护。

坏的：

所有权： 平台团队将拥有这个。

坏的版本看起来像所有权，但不是——“平台团队”没有日历，没有传呼机，没有绩效考核。给一个人命名，就在那个人和那个责任之间创造了一段关系。给一个团队命名，制造的是责任扩散。

为评审写，还是为批准写

大多数设计文档都搞错的一个微妙之处：你为健康评审写的文档和你为批准剧场写的文档不一样。

对评审友好的文档：

  • 有大量非目标。
  • 诚实地列举替代方案，包括作者自己认为最差的那个。
  • 有一个”悬而未决的问题”部分，充满了真正未解决的事情。
  • 以一个在评审之后才填写的决策日志结尾。

批准剧场文档：

  • 有”这个计划”，以不可避免的方式呈现。
  • 用一句话否定每个替代方案。
  • 没有悬而未决的问题，因为作者不想显得没准备好。
  • 预先填写了决策日志：“已批准。”

如果你所在组织的设计文档文化奖励批准剧场文档，那是文化在失败——但它也是可以修复的，从你自己的文档开始。写对评审友好的文档，并接受其中一些会被拒绝。这才是设计评审应该运作的方式。批准率100%是批准流程为0%。

2026年的转折

AI 辅助写作在这里改变了一些东西。我现在能在20分钟内生成一个”看起来完整”的设计文档初稿。这对技术部分很好——它们结构清晰，权衡枚举了，文字风格一致。

对政治部分来说是主动有害的。LLM 不知道那三个有重叠主张的 VP 是谁。它不知道哪个团队的 on-call 是脆弱的。它不知道这个季度的预算表象与真实预算是什么。

我当前的工作流程：让 AI 起草第3、6、7和9部分。自己写第1、2、4、8和10部分。 AI 也可以在那些部分上帮助改进文字，但内容必须来自我，因为它住在人们的脑子里，不在仓库里。

我现在对每份设计文档问的那个问题

在我批准或拒绝一份设计文档之前，我大声问作者一个问题：“如果这个按原文交付，谁会不高兴？”

如果他们说不出具体的人名，这份文档还没准备好评审。因为那些具体的人是存在的——他们总是存在——如果作者不知道他们是谁，这些人会在第三个月出现，问为什么没有咨询他们。

如果作者能说出他们的名字，下一步是”你和他们谈过了吗？“如果答案是没有，去谈。如果答案是谈过了，这份文档可能准备好了。

那个问题给我省下的返工时间，超过了我有过的任何其他习惯。