软件工程 / 架构设计方法论知识图谱 / 分组目录 / 方法论层 / 架构文档化方法
methodology · G · P1 · active

架构文档化方法

Architecture Documentation (Views and Beyond)
P1进阶verified方法论 methodology方法G · 架构设计质量属性GL-METHOD · 方法论层

§1摘要与结论

TL;DR · 一句话结论

以「文档化相关视图，再文档化适用于多个视图的信息」为组织原则的架构文档化方法：先按预期用途与干系人关注选择视图，再表达每个视图的「如何组织、架构是什么、为何如此」，并以跨视图信息与一致性校验避免文档过载与失真。

别名：Views and Beyond、V&B、架构文档化、文档化方法、view selection　|　英文：Architecture Documentation (Views and Beyond)　|　类型：方法 / process

§2局部关系图

架构文档化方法 的 1-2 跳邻域关系图前置依赖（prerequisite）：本质复杂度不可消除，故架构只能在约束下权衡前置依赖（prerequisite）：先划定边界，才能约束依赖方向前置依赖（prerequisite）：边界划分是对多重质量属性的权衡依据推导（derives_from）：粒度决定偶然复杂度与理解成本依据推导（derives_from）：文档化方法以架构描述为对象组织视图与对应关系依据推导（derives_from）：文档化依视图与视角约定组织架构信息依据推导（derives_from）：敏感点与权衡点分析是架构权衡判断的内核细化（refines）：效用树构造与敏感点识别细化 ATAM 评估流程的分析环节组合（combination）：决策记录与文档化方法共同承载架构决策与理由促成（enables）：架构文档是架构评估流程的输入前置依赖（prerequisite）：视图与视角概念是理解架构描述构成与对应关系的前提组合（combination）：架构描述记录边界与接口的外部可见属性组合（combination）：架构描述按干系人关注点组织局部表达促成（enables）：敏感点与权衡点分析为架构风格选型提供判据案例印证（case_instance）：印证：按关注点将系统分解为可独立处理的 18 个模块案例印证（case_instance）：印证：以视图与依赖图文档化架构，支撑无源码理解案例印证（case_instance）：印证：去中心化与本地优先等主张皆为显式架构取舍案例印证（case_instance）：印证：以分层文档组织视图，再补跨视图信息案例印证（case_instance）：印证：按不同关注点组织层级与模块视图案例印证（case_instance）：印证：把不可见的架构转写为可复核的架构描述案例印证（case_instance）：印证：以装配与注入关系还原依赖方向案例印证（case_instance）：印证：以蓝本为参照的多视图文档与深链互引案例印证（case_instance）：张力：受蓝本粒度约束，增量定位精度受限案例印证（case_instance）：印证：查询引擎、工具、权限、记忆的关注点分离案例印证（case_instance）：印证：多源交叉验证与分章文档化案例印证（case_instance）：印证：编译期特性裁剪消除偶然复杂度案例印证（case_instance）：印证：多层门控链与可再构建交付案例印证（case_instance）：印证：五段式节点页与图谱化文档案例印证（case_instance）：印证：以代码审查工具为解析对象的质量工程实现（implements）：静态分析平台为代码评审提供自动化检查信号实现（implements）：质量门控把分析结果转化为变更准入判断案例印证（case_instance）：印证：从设计文档识别需求缺口作为债务信号案例印证（case_instance）：印证：以自动化代码审查工具为载体沉淀质量实践案例印证（case_instance）：印证：多层门控链持续校验交付物完整性案例印证（case_instance）：印证：事件地图交叉核对声明点与派发点核验埋点前置依赖（prerequisite）：关注点分离是视图与视角划分的基础组合（combination）：视图记录边界与接口的外部可见属性依据推导（derives_from）：决策记录依架构即权衡，留存取舍与理由依据推导（derives_from）：ATAM 以架构权衡为根本前提依据推导（derives_from）：风格选择依质量属性权衡而非对错前置依赖（prerequisite）：识别敏感点与权衡点是记录架构决策的前提前置依赖（prerequisite）：质量属性场景与评估是风格权衡选型的前置分析组合（combination）：风格选型结果以 ADR 记录理由与被否决项架构文档化方法架构文档化方法（MTH-G-05）去中心化聊天架构逆向去中心化聊天架构逆向（CAS-X-01）harness 源码架构…harness 源码架构解析（CAS-X-09）dsh 插件依赖增量定位dsh 插件依赖增量定位（CAS-X-10）Claude Code …Claude Code 架构逆向（CAS-X-13）Open Code Re…Open Code Review 图谱（CAS-X-15）视图与视角视图与视角（ESS-G-06）架构描述与对应关系架构描述与对应关系（ESS-G-07）架构决策记录架构决策记录（MTH-G-01）质量属性场景与ATAM质量属性场景与ATAM（MTH-G-02）架构即权衡架构即权衡（ESS-O-02）边界与接口隔离边界与接口隔离（ESS-G-03）本质复杂度与偶然复杂度本质复杂度与偶然复杂度（ESS-O-01）关注点分离关注点分离（ESS-G-01）SonarQube 静态…SonarQube 静态分析平台（TEC-H-01）质量门控与持续集成质量门控与持续集成（MTH-I-06）可观测性信号采集可观测性信号采集（TEC-K-02）架构适应度函数工具化架构适应度函数工具化（TEC-L-01）架构风格选择方法架构风格选择方法（MTH-G-03）代码复审与可读性治理代码复审与可读性治理（MTH-H-04）依赖倒置与依赖规则依赖倒置与依赖规则（ESS-G-02）效用树与敏感点权衡点分析效用树与敏感点权衡点分析（MTH-G-06）粒度与边界设定粒度与边界设定（MTH-O-06）需求技术债识别与度量需求技术债识别与度量（TEC-F-02）
前置依赖实现依据推导案例印证对比冲突
以本节点为中心，静态内联 1–2 跳邻域：内环 9 个直接邻接、外环 14 个二跳节点，共 24 个节点；连线按边类型着色（六类配色见下）。构建期计算，无运行期脚本。

§3原理 · 为什么

架构文档化不是设计完成之后的独立步骤，而应是架构决策过程的产物：与设计分离得越远，文档越可能根本不被写、写了也迅速过期，因为文档一旦被当作额外负担，就会在进度压力下最先被牺牲。其核心难点不在「画多少图」，而在于面对众多潜在视图如何取舍。视图太多会造成文档过载，读者淹没在细节里，反而找不到自己关心的信息；太少则无法回应关键干系人的关注，留下理解盲区。因此文档化方法把「选择视图」确立为第一动作：依据架构本身的固有结构与干系人需求，决定需要哪些视图、如何组合这些视图，并让视图之间保持有意识的互补而非简单叠加。对每个入选视图，还要说明它回应了谁的什么关注、预期用途是什么；对未入选的关注，说明将如何被覆盖。文档化的内容可归纳为三层——如何组织、架构是什么、为何如此（理由），其中理由与决策语境最容易被忽略，却对长期维护最具价值。

§4机制 · 如何运作

文档化以视图为基本组织单位，并把视图归入三类：实现单元的模块视图（分解、使用、分层、泛化、数据模型等）、运行期组件与连接件视图（管道-过滤器、客户端-服务器、发布-订阅、并发进程等），以及软件元素到开发、部署与组织环境的分配视图。这三类视图回答的是不同的问题，因而不能互相替代。选定视图后，逐一文档化视图内信息，再补充适用于多个视图的跨视图信息与理由；结构之外还需文档化接口与行为，否则读者无法判断元素之间如何交互。为承接大量信息，可先用视图分类作为组织骨架，再对每个视图给出必要的元素、关系与关键场景。为避免视图各自漂移，应建立跨视图的一致性校验，并在文档包层面做「选择视图、构建文档包、评审文档」的组织。整个方法不依赖特定记号、语言、领域与技术，因而可与其它表达框架配合使用。

§5工程 · 怎么落地

实践中先列出关键干系人及其关注点，再把这些关注点映射到一组能满足它们的视图，并说明每个视图的预期用途与阅读顺序，避免只画自己熟悉的视图。文档包宜采用统一模板，把视图内信息与跨视图信息分区；理由与决策单独沉淀，并与决策记录联动；接口的语法、语义与行为约定应集中文档化，减少逐处重复，也避免同一接口在不同视图里出现互相矛盾的描述。构建文档包时控制规模，用导航与视图组合帮助读者按需深入，而不是把全部信息塞进单一叙述；对稳定部分可引用既有材料，把篇幅留给真正需要解释的设计决策。评审时以「预期用途是否被满足、跨视图是否一致、是否与实现同步」为判据，并把文档化与变更流程绑定：架构变更时同步更新受影响视图与对应关系，防止文档在演进中悄然过期。

§6权衡卡

代价 · 风险

为每个关注点各开一个视图而不做取舍，会使读者在大量视图间往返，理解成本反超单一叙述；跨视图一致性的维护成本随元素与视图数量增长，一旦与实现脱节，文档会从资产变成负担，甚至以权威姿态提供过时信息，误导后来者。

原文要点
  • 文档化以投入换可理解，但并非越多越好。
  • 另一类失效是把文档化当作独立仪式，在架构决策之外集中补写，产物看似完整却无决策支撑、无人维护，最终无人查阅。
  • 还有一种偏差是用文档数量或篇幅衡量产出，诱使团队重复叙述、堆砌图表，而真正需要解释的理由与取舍仍未说清。
  • 因此视图选择应服务预期用途与干系人关注，而非穷举或形式完整；文档化的深度应与系统寿命、团队更替与变更频率相称。
  • 判断文档化是否成功，不看篇幅与图表数量，而看新成员能否据此理解系统、变更时是否真的被查阅；对稳定且人员熟悉的系统，可只保留少数关键视图，而不必追求覆盖所有可能视角。
  • 归根结底，文档化是手段而非目的，其尺度应由读者能否据此安全地理解系统并完成修改来决定，而非由图表数量或模板完整度决定。

权衡原文仅按显式标记词归栏引用（收益 / 代价 / 反例），其余句子按原序列为「原文要点」；内容逐字引用未改写。

§7案例带

CAS-X-01 · 经 direct

去中心化聊天架构逆向

对一个仅有 58 份设计文档、尚未实现的开源去中心化聊天项目做架构逆向：从设计文本提炼 18 个模块及其依赖关系，重建模块依赖 DAG 与三条核心数据流 DAG，并输出全景理解与深度需求分析。

CAS-X-09 · 经 direct

harness 源码架构解析

对 deepseek-harness 官方源码做分层解析：镜像官方架构文档，按九个层与九十余模块建立文档集群，产出跨层联动矩阵与七条关键路径，并钉住「模型可见即已记录」、能力缝三角等设计不变量。

CAS-X-10 · 经 direct

dsh 插件依赖增量定位

以官方插件 DAG 为蓝本，对一个官方清单之外的全新社区插件做功能定位与依赖位置增量分析，产出可下钻交互依赖图与多形态文档的源码级架构逆向案例。

CAS-X-13 · 经 direct

Claude Code 架构逆向

以社区逆向源码、系统提示词与官方文档三源交叉验证，还原一个商业 Agent 的查询引擎、子Agent、工具与权限体系的逆向分析案例。

CAS-X-15 · 经 direct

Open Code Review 图谱

对阿里开源 AI 代码审查 CLI 做源码级解析并构建「知识 + 实践资产 + AI 索引」三合一知识图谱的工程案例。

CAS-X-02 · 2 跳派生：当前节点 → ESS-G-06 → ESS-G-03

网申填写扩展逆向架构

对 Chrome MV3 网申自动填写扩展的逆向架构分析：梳理 popup、content、background、options 四模块职责，解剖 12 个站点适配器、双通道消息协议与隐私脱敏机制，并评估其零依赖零构建选型。

CAS-X-03 · 2 跳派生：当前节点 → CAS-X-10 → ESS-G-02

网申 v3 多模块解耦

一套面向高可扩展性的网申信息速查扩展架构：以 schema.js 为唯一数据驱动源，把数据模型、存储、纯函数与渲染组织为严格单向依赖的共享层，供 popup 与页面浮层双容器复用，并先立跨模块接口契约。

CAS-X-05 · 2 跳派生：当前节点 → ESS-G-06 → ESS-G-03

preset 通道耦合分析

对 harness「委派工具层→续用管理器→preset 服务→MCP 服务器」这条通道做耦合分析：识别契约、服务定位、数据契约、组合语义、路径与装配一致性六类耦合点，定位「静默丢弃特化」与「装配漂移」两处实质缝隙。

CAS-X-06 · 2 跳派生：当前节点 → CAS-X-15 → TEC-L-01

插件 DAG RC5→RC7 升级

一次知识库随上游源码版本升级的级联维护：以三层差异分析把 219 个包收敛为 26 个实质变更包，经编译、运行时、组合三类依赖判定更新 DAG 数据后全量重生成页面，并以静态门控加渲染验证收口。

CAS-X-08 · 2 跳派生：当前节点 → ESS-G-06 → ESS-G-03

dsh-manager 插件深度分析

以「编译依赖、运行时注入、组合装配」三硬依据加源码行号，对第三方插件做依赖、功能、需求溯源与设计问题裁决，并复用上游 DAG 知识库节点标识，使分析结果可与主图互查。

CAS-X-12 · 2 跳派生：当前节点 → CAS-X-01 → ESS-O-02

MCP 四件套选型对比

对四个同类 MCP 服务器做源码级能力与成本对比，并以常驻 token 预算为轴给出分级接入策略的技术选型实战案例。

CAS-X-18 · 2 跳派生：当前节点 → CAS-X-15 → MTH-I-06

AI Agent 架构 DAG 复盘

对四个工作日内独立完成三个异构对象 DAG 分析的方法论复盘，总结「采集→建模→生成→门控→交付」可复用管线与关键教训。

§8信源与核验

核验状态True（verified）
置信度high
复核日期2026-10-12
生命周期active
规范信源OFF-015、OFF-016、BK-013、STD-001
书证核验BK-013 Ch6.2 Descriptive Completeness（direct），Ch10.1.1 A Standard Organization for Documenting a View（direct），Ch10.2.1 A Standard Organization for Documenting Information（direct），ChYou can use the templates in this chapter to create architecture（direct）
入口链接https://www.sei.cmu.edu/library/documenting-software-architectures-views-and-beyond-second-edition/　https://web.archive.org/web/20110807114506/http://www.sei.cmu.edu/architecture/tools/document/viewsandbeyond.cfm
勘误
常见误解：架构文档化是设计完成后的独立收尾步骤
核验结论：文档化应是架构决策过程的产物；与设计分离得越重，越可能根本不落下文档，或文档迅速与实现脱节　[OFF-015]
勘误
常见误解：视图越多越完整，文档质量越高
核验结论：应有意识地选择并组合视图以避免文档过载；视图数量与跨视图一致性维护成本正相关，应服务预期用途而非穷举　[OFF-016]

§9原始关系清单

展开：本节点的全部原始关系边（9 条，含边 ID 与方向）
关系方向对端节点说明
案例印证← CAS-X-01去中心化聊天架构逆向
E-939		印证：以视图与依赖图文档化架构，支撑无源码理解
案例印证← CAS-X-09harness 源码架构解析
E-962		印证：以分层文档组织视图，再补跨视图信息
案例印证← CAS-X-10dsh 插件依赖增量定位
E-970		印证：以蓝本为参照的多视图文档与深链互引
案例印证← CAS-X-13Claude Code 架构逆向
E-979		印证：多源交叉验证与分章文档化
案例印证← CAS-X-15Open Code Review 图谱
E-985		印证：五段式节点页与图谱化文档
组合← MTH-G-01架构决策记录
E-726		决策记录与文档化方法共同承载架构决策与理由
依据推导→ ESS-G-06视图与视角
E-722		文档化依视图与视角约定组织架构信息
依据推导→ ESS-G-07架构描述与对应关系
E-721		文档化方法以架构描述为对象组织视图与对应关系
促成→ MTH-G-02质量属性场景与ATAM
E-727		架构文档是架构评估流程的输入

附对照资源 · 12factor 子库

12factor 节点关系对照说明
12factor.net 站点源码 tool-app-site案例印证12factor.net 站点自身是 App 原则的参考实现（不可变静态构建）与文档化载体