第二章：架构文档的目的与读者
好，咱们接着聊。上一章我们讲了架构文档到底是个什么东西。这一章，我想聊聊一个更根本的问题——我们为什么要写它？写给谁看？又在什么场景下看？
说实话，我见过不少团队，架构文档写得比小说还厚，结果没人看。为什么？因为写的人没想清楚这三个问题。我自己也踩过这个坑，所以今天把这部分单独拎出来讲。
2.1 为什么需要架构文档
你可能觉得，代码就是最好的文档。嗯，这话对了一半。代码确实能告诉你“做了什么”，但它说不清楚“为什么这么做”。
我个人的习惯是，把架构文档看作团队的共享心智模型。说白了，就是让所有人对系统的理解保持一致。
架构文档的核心价值：
- 沟通的桥梁——不同角色之间，靠它对齐认知
- 决策的记录——为什么选A方案而不是B，白纸黑字写下来
- 演化的基线——以后改东西，有个参照物
- 入门的向导——新人来了，不用追着你问东问西
我在项目中遇到过一件事，印象特别深。有一次，一个同事改了一段刹车压力调节的代码，他觉得只是优化了算法。结果测试的时候，ABS在低附路面上的表现完全变了。后来一查，他根本不知道原来的设计里有一个安全回退机制，而那个机制在架构文档里写得清清楚楚。你说，如果文档没人看，或者压根没写，这锅谁来背？
所以，架构文档不是写给领导看的，也不是为了应付评审。它是团队的救命稻草。
2.2 文档的读者是谁
这个问题，我建议你写文档之前先想清楚。不同的人，关心的东西完全不一样。
| 读者角色 | 他们关心什么 | 文档里该有什么 |
|---|---|---|
| 系统架构师 | 整体结构、模块划分、接口定义 | 架构视图、组件图、接口规范 |
| 软件工程师 | 具体模块的职责、数据流、状态机 | 详细设计、时序图、伪代码 |
| 测试工程师 | 关键路径、异常处理、测试策略 | 测试用例设计、边界条件、故障注入点 |
| 项目经理 | 技术风险、依赖关系、交付节奏 | 技术决策记录、依赖清单、里程碑 |
| 功能安全工程师 | 安全机制、故障响应、ASIL等级 | 安全分析、FMEA、故障树 |
| 新人/维护者 | 系统全貌、关键概念、常见陷阱 | 术语表、快速入门、避坑指南 |
你看，同样是ABS的架构文档，给不同的人看，侧重点完全不同。我曾经见过一份文档，把所有内容混在一起，结果软件工程师嫌太粗，项目经理嫌太细，谁都不满意。
我的建议是：按读者分层。核心章节写给所有人看，但每个小节可以标注“本文主要面向XXX读者”。这样大家各取所需。
2.3 文档的阅读场景
这个问题容易被忽略。你想想看，读者是在什么情况下翻开这份文档的？
- 场景一：系统设计阶段
架构师和工程师一起讨论方案。这时候文档是讨论的载体。我建议用图为主，文字为辅。一张清晰的架构图，胜过千言万语。 - 场景二：代码评审阶段
评审者需要对照文档，检查实现是否偏离了设计。这时候文档要精确、可追溯。每个模块的接口、行为、约束，都得写清楚。 - 场景三：问题排查阶段
线上出了bug，工程师翻文档找线索。这时候文档要快速定位。我习惯在文档里加一个“常见问题”章节，把以前踩过的坑列出来。 - 场景四：新人入职阶段
新人啥都不懂，文档是他的救命稻草。这时候文档要循序渐进，从整体到局部，从概念到细节。 - 场景五：功能安全评审
这是最严格的场景。文档要完整、无歧义，每一个安全机制都要有对应的说明和验证方法。
一个小技巧： 我写文档的时候，会在每个章节开头加一个“阅读指引”，告诉读者“如果你只有5分钟，请读这一节；如果你在排查问题，请跳到第X节”。这样能节省大家的时间。
2.4 避坑指南
讲了这么多，最后分享几个我亲身踩过的坑。
我曾经犯过的错：
- 坑一：文档写得太完美——恨不得把所有细节都画出来。结果文档比代码还复杂，没人愿意看。后来我学会了“80%原则”：覆盖核心场景，留20%的细节让代码说话。
- 坑二：读者定位模糊——一份文档想讨好所有人。结果谁都不满意。现在我写文档前，会先问自己：“这篇文档的第一读者是谁？”
- 坑三：只写“是什么”，不写“为什么”——比如“这里用了状态机”，但没写“为什么用状态机而不是查表”。后来别人改代码的时候，完全不知道当初的权衡，很容易改出问题。
- 坑四：文档和代码脱节——架构图画得漂漂亮亮，代码里根本不是那么回事。嗯，这个最要命。我现在的做法是：每次迭代结束，花半小时更新文档。不追求完美，但至少保证关键部分是对的。
好了，这一章就到这里。总结一下：架构文档的目的，是让团队对系统有一致的理解；读者是多元的，要分层对待；阅读场景不同，文档的侧重点也不同。 下一章，我们聊聊架构文档的具体内容结构，也就是到底该写些什么。