架构决策文档为什么总被束之高阁：从Gartner体验工具包看架构交付物的用户体验设计

Tue, 21 Jul 2026 23:30:00 +0800

上周参加一个架构评审会，场景很熟悉。架构团队花了三个月做了一套完整的数字化转型架构方案，TOGAF ADM 九个阶段一个没落，产出物堆了四十多页。PPT翻到第七页的时候，业务方的负责人开始看手机。翻到第十五页，有人开始问"所以我们到底要换哪个系统"。翻到第二十五页，会议主持人说"时间差不多了，大家回去消化一下"。

那套方案后来怎么样了？放在SharePoint里，三个月后有人问起来，链接已经失效了。

这不是个例。企业架构领域有一个长期悖论：我们花大量精力生产架构文档，但这些文档的实际使用率极低。有句话说，架构师最大的幻觉就是以为有人会认真读完你的架构愿景文档。这不是架构能力的问题，而是交付物设计的问题——我们从来没认真思考过架构交付物的用户体验。

架构交付物的信任危机

先说几个行业里心照不宣的事实。

第一，大部分架构文档写完之后的唯一读者是写它的人。业务方看摘要，开发团队看接口定义，运维团队看部署图。那份号称"全局视角"的架构文档，实际上没有人从头到尾读完过。

第二，架构评审会经常变成走过场。不是因为大家不想认真评，而是因为评审材料的信息密度太低、叙事结构太散，参会人员需要花大量精力从文档里"挖"出跟自己相关的信息。等挖完了，会议时间也到了。

第三，架构决策的记录方式极其随意。有的写在Confluence页面里，有的藏在会议纪要里，有的只存在于某个人的脑子里。半年后谁也说不清当初为什么选了这个技术栈。

这些现象指向同一个根因：架构交付物是按生产者的逻辑组织的，不是按消费者的逻辑组织的。 架构师写文档时想的是"把架构描述清楚"，读文档的人想的是"这对我有什么影响，我要做什么"。这个鸿沟，就是架构交付物的用户体验问题。

Gartner 体验工具包的启发

Gartner 在客户体验领域有一套成熟的方法论，通常称为客户体验工具包（CX Toolkit）。它本来是给产品经理和市场营销人员用的，但核心工具几乎都能直接映射到架构交付物的设计上。

CX 工具	原始用途	架构交付物的映射
用户画像（Persona）	描述典型客户特征	识别架构文档的不同读者角色
客户旅程地图	梳理客户触点与情绪曲线	梳理利益相关者从"获知决策"到"落地执行"的完整路径
痛点分析	识别体验断裂点	发现架构文档的信息断裂和理解障碍
体验度量	量化体验质量	衡量架构交付物的可理解性和可操作性
反馈闭环	持续优化体验	建立架构文档的反馈和迭代机制

核心洞察是：架构交付物的"用户"不是一个人，而是一组角色各异、关注点完全不同的利益相关者。 用产品经理的话说，你在做一个多角色、多场景的B端产品，但你从来没做过用户调研。

TOGAF 交付物体系的七个体验缺陷

TOGAF 作为业界最广泛使用的企业架构框架，它的 ADM（架构开发方法）定义了一套非常完整的交付物体系。从架构愿景到业务架构、信息系统架构、技术架构、机会与方案、迁移规划，每个阶段都有明确的输入输出和交付物模板。

这套体系在方法论层面无可挑剔。但从用户体验的角度审视，它有几个结构性的问题。

有个值得思考的对比：产品经理花几个月研究用户体验地图来优化一个功能页面，但架构师产出的文档可能影响整个组织未来两到三年的技术走向，却从没有人认真研究过这些文档的阅读体验。

缺陷一：信息架构扁平

TOGAF 的交付物清单是线性罗列的。架构愿景、架构定义文档、架构路线图、架构契约……这些交付物之间的信息层级关系不清晰。读者不知道应该先看哪个、后看哪个，也不知道某个决策在哪个文档里有详细描述。

对比优秀的产品设计，用户打开后三秒内能找到想要的功能。但一份架构定义文档，读者可能需要花二十分钟才能定位到关心的决策。

缺陷二：一份文档服务所有角色

TOGAF 的架构定义文档试图在一个文档里覆盖所有利益相关者的需求。业务方关心的价值链分析、开发团队关心的应用组件交互、运维团队关心的部署拓扑，全部混在一起。

这就像一本教科书试图同时满足初学者和专家，结果谁都不满意。

缺陷三：缺少落地指引

架构文档最常见的问题是描述清楚"架构是什么样的"，但没说清楚"这对每个人意味着什么"。技术架构文档会详细描述目标状态，但不会告诉开发团队"你们需要学什么新技术、迁移的时间窗口是什么、现有代码需要改哪些模块"。

Gartner 体验工具包里有"行动召唤"（Call to Action）的概念。每个客户触点都应引导用户走向下一步。架构交付物也一样，每个章节读完后，读者应清楚知道"我接下来该做什么"。

缺陷四：决策逻辑不透明

TOGAF 鼓励记录架构决策，但模板侧重描述"选了什么"，而不是"为什么选这个、放弃了什么备选方案、前提条件是什么"。半年后团队换人，看到文档里写着"采用微服务架构"，但不知道为什么不用单体，也不知道当时的团队规模和技术储备。

这就是架构决策记录（ADR）试图解决的问题，但大部分企业的ADR实践也只写了结论，没有完整记录推理过程。

缺陷五：视觉传达不足

大部分架构文档的视觉设计停留在2005年。Word里画几个方框，Visio里拉几条线，配色全靠系统默认。好的架构图应该能在三十秒内传达核心信息，但大部分架构图需要配合三十分钟的解释才能看懂。

缺陷六：缺少版本演进叙事

架构不是一次性的，它在持续演进。但TOGAF的交付物模板是"快照"式的，记录某个时间点的架构状态。你很难从这些快照中看出架构是怎么一步步演变成现在这样的，也很难理解每次变更背后的业务驱动力。

缺陷七：反馈机制缺失

产品上线后有用户反馈、数据埋点、A/B测试。但架构文档发布后，没有机制收集"用户"反馈。业务方有没有读懂？开发团队有没有在实施中发现架构设计与实际不符？这些问题全靠架构师自己去打听。

“架构即产品"的设计原则

说了这么多问题，怎么改？我的建议是把架构交付物当作一个产品来设计，用产品思维重新组织架构信息的生产和消费。

原则一：用户分层，交付物分级

不要试图用一份文档满足所有人。按照读者角色做分层设计：

决策层视图。 面向管理层和业务负责人。核心内容是：这个架构方案解决什么业务问题、投入多少资源、预期收益是什么、风险在哪里。篇幅控制在5页以内，用图表和关键数字说话，杜绝技术术语。

协调层视图。 面向项目经理、技术经理、产品经理。核心内容是：各团队的工作边界是什么、依赖关系是什么、关键里程碑和交付节点、需要协调的接口契约。这部分需要足够的结构化，方便拆解成可执行的任务。

执行层视图。 面向开发人员、测试人员、运维人员。核心内容是：详细的技术方案、接口定义、数据模型、部署配置、迁移步骤。这部分可以很长，但必须有清晰的导航和搜索能力。

三个视图不是三个独立的文档，而是同一套架构信息的三个不同切面。底层数据是统一的，展示方式因角色而异。

原则二：信息架构要有层级和导航

借鉴产品设计中的信息架构（IA）方法论，给架构交付物设计清晰的层级结构。采用"三层金字塔”：

第一层：架构概览。 一页纸说清楚全局。核心业务能力、关键技术选型、系统间的主要交互关系。任何角色都应从这一层开始。
第二层：域级架构。 按业务域或技术领域拆分。每个域有自己的架构描述，包含组件关系、数据流、接口定义。读者根据职责进入对应的域。
第三层：详细设计。 深入到具体组件的内部设计、接口契约的完整定义、数据库表结构、配置参数。只有需要实现这个组件的人才看这一层。

每一层都应有明确的"向下钻取"和"向上返回"导航。读者在第三层看API详细定义时，应能一键跳回这个API在整体架构中的位置。

原则三：决策记录要讲故事

架构决策记录不应只是结论的存档，而应是完整的决策叙事。好的ADR包含四部分：

背景。 面临什么问题？业务驱动力是什么？约束条件有哪些？
选项。 考虑了哪些备选方案？各方案的优缺点？
决策。 最终选了什么？权衡逻辑是什么？
后果。 带来哪些正面效果和负面效果？已知风险有哪些？

即使半年后有人质疑这个决策，他们也能看到完整的推理过程。如果前提条件变了，可以基于新条件重新评估，而不是盲目推翻。

原则四：让架构图自己说话

好的设计不需要说明书，好的架构图也应如此。几个实操建议：

用颜色编码表示系统状态。 绿色表示已建成、黄色表示建设中、红色表示待规划。读者扫一眼就知道实施进度。
用线条粗细表示数据流量。 核心数据流用粗线，辅助数据流用细线。一眼看出系统瓶颈。
用分层布局表示架构层次。 业务层在上、应用层在中、基础设施层在下。不需要看图例就能理解层次关系。
每张图配"关键要点"框。 用三到五个要点总结核心信息。读者只看要点框也能获取80%的信息。

原则五：建立度量与反馈机制

这是最容易被忽略、但可能是最重要的一条。

怎么度量架构交付物的"用户体验"？几个可操作的指标：

触达率。 架构文档发布后，目标读者中有多少人打开过？多少人阅读时长超过五分钟？
可操作性。 读者读完后，能否准确回答"这个架构决策对我的工作有什么影响"？可做简单的理解度测试。
实施偏差。 开发团队实施过程中，有多少次偏离了架构设计？偏离原因是架构设计不合理，还是文档没说清楚？
反馈量。 架构文档发布后收到多少条反馈？反馈集中在哪些部分？

这些数据不需要复杂工具。在Confluence或类似平台上，页面访问量和评论数就是最基础的度量。关键是架构团队要有意识地关注这些数据，并根据反馈持续迭代文档。

一个可落地的改进路径

上面说的原则听起来都挺好，但怎么在实际项目中落地？分享一个我觉得比较务实的渐进式改进路径。

第一步：做一次"架构文档用户调研"。 找五个不同角色的利益相关者，问他们三个问题：上次看架构文档是什么时候？在文档里找什么信息？找到了吗？这三个问题的答案会让你迅速定位到最大的体验断裂点。

第二步：为现有文档加一个"执行摘要"层。 不需要重写整个文档。给每份核心架构文档加一页执行摘要，用非技术语言回答三个问题：这份文档描述了什么？关键决策是什么？对各角色意味着什么？这一页的价值可能超过后面五十页的总和。

第三步：引入架构决策记录的标准模板。 不用太复杂，四段式（背景、选项、决策、后果）就够用。关键是让团队养成习惯，每次重要决策都留一份记录。这份记录不是给现在的团队看的，是给六个月后的团队看的。

第四步：把架构图从Word搬到专业工具。 Arcway、Structurizr、C4 Model 的配套工具，甚至 draw.io 都比 Visio 好。这些工具支持"一个模型，多个视图"，改一处全局更新，解决了手动维护多份图表一致性的问题。

第五步：建立季度架构回顾机制。 每个季度花半天时间回顾架构决策的执行情况。哪些决策被正确实施了？哪些被绕过了？为什么？这个回顾本身就是一个反馈闭环，产出应反哺到架构文档的迭代中。

从"交付物"到"交付体验"

回到开头那个场景。如果那套数字化转型架构方案是按"架构即产品"的思路设计的，评审会可能是另一个样子。

会议开始前，业务负责人已看过为他定制的一页纸摘要，知道这个方案要解决什么问题、需要多少投入。开发负责人已拿到应用架构的域级视图，清楚自己的工作边界。运维负责人已看过部署架构的变更清单，知道哪些基础设施需要扩容。

评审会不是用来"宣讲"的，而是用来"对齐"的。每个人带着自己的理解来，讨论有分歧的地方，确认下一步行动。

这才是架构交付物应该达到的效果。不是让所有人都读完你写的每一页，而是让每个人都能快速找到对自己有用的信息，理解自己需要做什么，然后行动起来。

架构师的核心能力不只是设计好的架构，还包括把架构有效地传达给需要它的人。当我们将架构交付物从"文档"重新定义为"产品"，将利益相关者从"读者"重新定义为"用户"，整个架构沟通的范式就会发生根本性的变化。

这个变化不会一蹴而就。但每改进一点，架构方案从"被束之高阁"到"真正落地"的概率就高一分。对于企业架构师来说，这可能是投入产出比最高的一项能力升级。

用户体验 on 文艺技术笔记