为什么架构文档对现代团队至关重要
让我告诉你我工程生涯中最糟糕的一个季度。
那是 2019 年。我是一家金融科技初创公司核心平台团队的技术负责人。我们有一个漂亮的微服务架构——23 个服务、事件驱动、适当隔离。系统运行良好。我们清楚地知道一切是如何工作的。
然后三件事接连发生：
- Sarah，我们的首席工程师，离开去了一家大厂
- Marcus，构建了我们支付集成的人，被竞争对手挖走了
- Lisa，唯一了解我们遗留对账服务的人，因病长期休假
六个月内，关于我们架构的一半机构知识离开了公司。而我们几乎没有文档。
接下来的几个月里，我们在逆向工程自己的系统。本应一周完成的功能花了一个月，因为我们必须先弄清楚现有代码是如何工作的。我们引入了 bug，因为我们不理解某些设计决策背后的微妙原因。我们做出的架构变更与我们已经忘记的约束条件产生了冲突。
那次经历把我从一个文档怀疑论者转变为文档布道者。不是因为我突然喜欢写文档，而是因为我亲眼看到了没有文档会发生什么。
缺失文档的真实成本
让我们坦诚地谈谈糟糕的文档到底花了多少代价。不是用含糊的"这很重要"来说，而是用我亲眼目睹的具体影响。
入职时间
在那家金融科技公司，新工程师需要 4-6 个月才能变得有生产力。不是因为他们不聪明——他们非常优秀——而是因为理解我们的系统需要通过潜移默化吸收多年的部落知识。
在我们投资于文档之后，这缩短到了 6-8 周。同样水平的工程师，同样复杂的系统。唯一的区别是他们有了地图，而不是盲目摸索。
算术很简单。如果你每年雇 5 个工程师，每个人浪费 3 个月来上手，那就是每年损失 15 个人月。按高级工程师的薪水算，你每年在损失的生产力上花费约 25 万美元。
决策延迟
没有文档的情况下，每次架构讨论都从零开始。
"我们为什么在这里用 Kafka 而不是 RabbitMQ？"
没人知道。让我们讨论两个小时。
"我们能从服务 A 到服务 B 添加一个同步调用吗？"
取决于某个可能存在的约束条件。让我们花一天来调查。
"如果支付服务挂了会怎样？"
好问题。让我们花一周追踪代码。
当架构上下文被记录下来时，这些问题都有答案。不一定是即时的答案，但至少你知道去哪里找。决策周期从几周缩短到几天。
事件响应
凌晨 2 点。告警响了。结账流程失败了。你是值班工程师，你加入公司才两个月。
没有文档时，你在疯狂地 grep 代码，试图在系统着火的同时理解它。你在 Slack 频道里 ping 人，希望某个了解支付流程的人还醒着。
有文档时，你打开系统架构，看到结账流程是如何工作的，识别出涉及哪些服务，知道在哪里查找问题。你甚至可能找到这个确切场景的故障排除手册。
我经历过这两种情况。平均恢复时间的差异是显著的。
技术债务累积
这是一个我反复看到的模式：
- 团队构建了一个架构良好的系统
- 文档不存在或过期
- 新工程师加入，不理解架构
- 他们添加了违反架构原则的功能
- 技术债务累积
- 最终，有人提出重写
重写并不总是必要的。通常，原始架构是好的——它只是没有被理解。没有文档，每一条架构原则都离被遗忘只有一次团队轮换的距离。
好的文档到底是什么样的
为了文档而文档是没用的。我见过团队产出了数百页没人读的文档。关键是以正确的方式记录正确的东西。
记录"为什么"，而不仅仅是"什么"
代码展示系统做什么。文档应该解释为什么。
为什么我们选择 PostgreSQL 而不是 MongoDB？为什么这些服务是分开的而不是合并的？为什么这个端点接受这种特定格式？
这些"为什么"的问题有答案，但答案不在代码里。它们在做出决策的人的脑子里。如果你不写下来，当这些人离开时答案就丢失了。
保持可发现性
最好的文档如果没人能找到也是没用的。我们金融科技公司其实有一些文档——埋在一个没有从任何地方链接的 Confluence 空间里，搜索功能几乎不能用。
文档应该是：
- 从代码中链接（README 文件、代码注释中的文档链接）
- 逻辑组织（而不仅仅是按时间顺序堆放）
- 可搜索（全文搜索所有文档）
我们最终将架构文档移到了代码仓库本身。现在它出现在代码评审中，与代码一起版本控制，不会偏离现实太远。
使其可维护
更新起来痛苦的文档不会被更新。
这就是为什么我对精心制作的 UML 图持怀疑态度。它们刚创建时很美，六个月后就绝望地过时了，因为更新它们需要专门的工具和技能。
简单的格式效果更好：
- 任何人都能编辑的 Markdown
- 与代码一起存放的文本图表（Mermaid、PlantUML）
- 刻意保持简单维护的 C4 图表
被维护的文档就是容易维护的文档。
面向多种受众
不同的人需要不同级别的细节。
新工程师需要系统概览。产品经理需要理解服务边界。架构师需要看到组件关系。值班工程师需要运维信息。
C4 模型在这里很有效，因为它显式地提供了不同的缩放级别。系统上下文给高管看，容器图给架构师看，组件图给开发者看。
开始记录的实践步骤
如果你从零开始，以下是我发现有效的方法：
第 1 周：系统上下文
花几个小时创建一个图表，展示：
- 你的系统作为一个方框
- 谁在使用它
- 它连接了哪些外部系统
仅此一项就很有价值。它建立了边界，给新团队成员一个起点。
第 2 周：容器图
将你的系统分解为可部署的部分：
- 服务、应用、数据库
- 它们如何通信
- 使用什么技术
这成为基础设施讨论和入职的参考。
第 3 周：关键决策
记录你最重要的三个架构决策：
- 决定了什么
- 为什么这样决定
- 考虑了哪些替代方案
这可以避免重新争论旧辩题，帮助新团队成员理解系统形态背后的原因。
持续前进：作为工作流的一部分
初始文档是容易的部分。保持它的更新则更难。
将文档作为完成定义的一部分。如果一个 PR 改变了架构，它应该更新相关文档。这不会自动发生——它需要评审纪律和文化承诺。
有些团队添加了自动化检查：验证 README 文件是否存在的 CI 任务，或者询问"这个变更是否改变了架构？如果是，你是否更新了文档？"的 PR 模板。
文化挑战
坦白说：让团队写文档通常是一场文化战役。
工程师通常更喜欢写代码而不是写文档。文档感觉像是开销，而不是产出。当截止日期迫近时，文档是第一个被砍掉的。
我发现有帮助的方法：
使之个人化
当新工程师加入时，让他们在入职过程中记录学到的东西。他们用新鲜的眼光看系统，注意到老手忽略的缺口。而且，他们直接受益于拥有他们希望存在的文档。
表彰文档
在冲刺评审中提及文档更新。表彰维护好文档的工程师。让人们看到文档是被珍视的，而不仅仅是被容忍的。
尽可能自动化
需要的手动文档越少，它越可能发生。使用从代码生成文档的工具。使用 AI 创建初稿。使用自动更新的代码即图表。
这部分也是我构建 Archyl 的原因。创建和维护架构文档的手动开销是主要障碍。AI 辅助的发现和可视化编辑降低了这个障碍。
与痛点关联
人们在感受到痛苦时才会改变行为。下次有人因为没有文档而花好几天理解一个系统时，指出来。"如果我们有文档，这本可以是一个小时的任务。"
结论
文档不令人兴奋。它不是我们任何人进入软件工程的原因。但它是一个能够在创建者离开后继续存活的系统和一个变成不可维护的混乱之间的区别。
我提到的那家金融科技公司？在那段痛苦的时期之后，我们认真地投资了文档。架构图表、决策记录、运维手册，全部搞了。大约花了六个月的专注努力。
下一次有人离开时，对团队几乎没有造成干扰。他们的知识在系统中，不仅仅在他们的脑子里。
这就是文档的真正意义：对知识丢失的保险。和所有保险一样，在你需要它之前，它都感觉很贵。