arc42 决策记录模板详解:用 11 个视角为架构决策建立完整档案
arc42 决策记录模板详解:用 11 个视角为架构决策建立完整档案
导读
arc42 是软件架构领域著名的架构文档化模板体系,而 architecture-decision-record 仓库将其中的"决策记录模板"(Decision record template by arc42)完整收录,并提供了包括简体中文、英文、孟加拉语在内的多语言译本。本文以孟加拉语版 arc42 决策记录模板(与 英文原版 内容一一对应)为主体,逐章拆解其 11 个章节的结构、写作动机与推荐格式,并说明架构决策记录(ADR)在该模板中的落位方式。读完本文,你将能直接套用该模板为项目撰写一份体系完整、可评审、可追溯的架构文档,并理解它与 Nygard、MADR 等轻量 ADR 模板的定位差异。
模板定位:arc42 决策记录在 ADR 生态中的角色
arc42 模板与仓库内其他模板最大的区别在于:它不是一份单页 ADR,而是一整套完整架构文档的骨架。仓库中随附的 Claude Code 技能文档 templates.md 对此有明确说明:arc42 适用于"用户想要完整的架构文档而非独立 ADR"的场景,此时架构决策记录位于其第 9 部分(§9 Architectural Decisions),并引用第 4 部分(Solution Strategy)中已概括的核心决策。
仓库 README.md 将 arc42 定位为 ADR 生态中的"next step"级概念:它实用地回答了"应该为架构文档记录/沟通什么"以及"如何记录/沟通"两个问题,且可针对具体需求裁剪。与之并列的还有:
- Michael Nygard 决策记录模板——最简单、最流行,适合大多数团队;
- MADR 项目决策记录模板——强调选项及其利弊;
- Jeff Tyree 与 Art Akerman 决策记录模板——面向企业级可追溯性。
仓库将该模板的许可证声明为 CC BY-SA 4.0(见 LICENSE.md),使用时需保留出处与相同方式共享。
说明:本仓库收录的 arc42 决策记录模板包含 11 个章节;完整 arc42 体系另含词汇表(Glossary)等章节,可按需补充。
第 1 部分:引言与目标(Introduction and Goals)
这是架构文档的开篇,目标是在一页之内交代三件事:需求是什么、架构的质量目标是什么、谁是干系人。模板给出了"内容 / 动机 / 形式"三段式写法,以下逐一展开。
1.1 需求概览(Requirements Overview)
- 内容:对功能需求、驱动力、需求摘要(或抽象)的简短描述,并链接到(如果存在的)需求文档及其查找位置。
- 动机:从最终用户视角看,创建或修改系统是为了更好地支撑业务活动、提升质量。
- 形式:简短的文字描述,最好采用表格化的用例格式;若已有需求文档,本概览应引用这些文档,尽量压缩摘录篇幅,在"文档可读性"与"相对需求文档的重复"之间取得平衡。
1.2 质量目标(Quality goals)
- 内容:架构的前三个(最多五个)质量目标,这些目标对主要干系人优先级最高。模板特别强调:这里指的是架构的质量目标,不要与项目目标混淆,两者未必一致;ISO 25010 标准提供了潜在关注点的良好概览。
- 动机:最重要干系人的质量目标会直接影响基础性架构决策,因此必须对这些质量属性非常具体,避免空洞的流行词——如果架构师自己都不知道工作质量将如何被评判……
- 形式:一张按优先级排序的表格,列出最重要的质量目标与具体场景。
| 优先级 | 质量目标 | 具体场景 |
|---|---|---|
| 1 | 性能 | 系统在 95% 的请求下 1 秒内返回响应 |
| 2 | 可用性 | 月可用性 ≥ 99.9%,支持滚动发布 |
| 3 | 可维护性 | 新功能从需求到上线不超过 2 周 |
1.3 干系人(Stakeholder)
- 内容:系统干系人的明确概览,即所有满足以下条件之一的个人、角色或组织:应当了解架构;需要被说服接受架构;需要基于架构或代码开展工作;工作需要架构文档;需要对系统或其开发做出决策。
- 动机:必须了解所有参与开发或受系统影响的各方,否则开发后期可能遭遇不愉快的意外;这些干系人决定了工作的范围与详细程度。
- 形式:包含角色名、人员姓名、以及他们对架构及其文档期望的表格。
| 角色 | 姓名 | 对架构及其文档的期望 |
|---|---|---|
| 产品负责人 | — | 了解架构如何支撑业务目标与发布时间线 |
| 架构师 | — | 掌握全局结构、关键决策与权衡 |
| 开发团队 | — | 知道实现时需遵循的约束与构建块 |
| 运维 | — | 了解部署视图、运行时行为与监控点 |
第 2 部分:约束(Constraints)
约束指限制团队在设计、实现或相关流程决策上自由度的任何要求,其效力有时超出单个系统,适用于整个组织甚至公司。
- 动机:架构师必须清楚自己在设计决策中哪里自由、哪里必须遵守约束。约束总是要处理的,不过它们可能是可协商的。
- 形式:带说明的约束表格。必要时可将约束细分为三类:
| 约束类型 | 说明与示例 |
|---|---|
| 技术约束 | 必须运行在指定云平台、必须兼容某数据库版本、固定编程语言 |
| 组织与政治约束 | 外包范围、预算上限、合规审计要求 |
| 惯例(Conventions) | 编程或版本管理指南、文档化或命名规范 |
第 3 部分:上下文与范围(Context and Scope)
本部分将系统与其(外部)通信伙伴(相邻系统与用户)区分开,并指明外部接口,始终从业务/领域视角呈现,技术视角可选。
- 内容:系统范围与上下文——将你的系统(你的范围)与其所有通信伙伴(系统的上下文)区分开,由此定义外部接口;必要时区分业务上下文(领域特定的输入/输出)与技术上下文(通道、协议、硬件)。
- 动机:与通信伙伴之间的领域接口和技术接口是系统最关键的方面之一,必须彻底理解。
- 形式:多种上下文图,以及通信伙伴及其接口的清单。
3.1 业务上下文(Business context)
- 内容:所有通信伙伴(用户、IT 系统等)的说明,解释领域特定的输入、输出或接口;可选地补充领域特定的格式或通信协议。
- 动机:所有干系人应理解系统与环境之间交换了哪些数据。
- 形式:任何能将系统画成黑盒并指明与通信伙伴领域接口的图表。备选(或补充)方案是使用表格——表头为系统名,三列分别为通信伙伴名称、输入、输出。
| 通信伙伴 | 输入 | 输出 |
|---|---|---|
| 用户 App | 查询请求 | 查询结果 |
| 计费系统 | 账单明细 | 对账确认 |
3.2 技术上下文(Technical context)
- 内容:连接系统与环境的通道与传输介质等技术接口,外加领域特定输入/输出到通道的映射(即哪个 I/O 走哪个通道)。
- 动机:许多干系人基于系统与其上下文之间的技术接口做架构决策,尤其是基础设施或硬件设计者。
- 形式:例如描述到相邻系统通道的 UML 部署图,配一张展示通道与输入/输出关系的映射表。
第 4 部分:解决方案策略(Solution Strategy)
本部分概括塑造架构的基础性决策与解决方案策略。
- 内容:包括技术决策;系统顶层分解决策(如使用某种架构模式或设计模式);如何达成关键质量目标的决策;相关组织决策(如选择开发流程、将特定任务外包给第三方)。
- 动机:这些决策是架构的基石,是许多更细粒度决策与实现规则的依据。
- 形式:保持简洁,基于问题陈述、质量目标与关键约束说明"你决策了什么、为什么这样决策",并指向后续章节的细节(结构细节看第 5 部分,横切概念看第 8 部分);可使用方案列表或表格。
第 5 部分:构建块视图(Building Block View)
展示系统的静态分解、源码的抽象,以"白盒(内含黑盒)"的层级呈现到适当的细节程度。
- 内容:将系统静态分解为构建块(模块、组件、子系统、类、接口、包、库、框架、层、分区、层叠、函数、宏、操作、数据结构等)及其依赖关系。该视图对每份架构文档都是强制性的——类比一栋房子,这就是设计图纸。
- 动机:通过抽象让源码结构可理解,从而在不暴露实现细节的前提下与干系人在抽象层面沟通。
- 形式:黑盒与白盒(见下)的层级集合及其描述。
5.1 白盒:整体系统(Whitebox Overall System)
使用白盒模板描述整体系统分解,包含:
- 概览图;
- 分解的动机;
- 所含构建块的黑盒描述——模板给出两种可选:用一张表给出所有构建块及其接口的简短务实概览;或按黑盒模板逐个列出构建块描述(依据工具偏好,可组织为文本文件的子章节、Wiki 的子页面或建模工具的嵌套元素);可选地补充对理解白盒至关重要的关键接口。
由于指定接口的方式太多,模板不提供专门接口模板,多数情况用示例或简单签名即可。
5.2 第 2 层(Level 2)
在此可将第 1 层(某些)构建块的内部结构指定为白盒。需要自行判断哪些构建块重要到值得如此详细描述,以相关性优先于完整性:指定重要、意外、高风险、复杂或易变的构建块,跳过普通、简单、平淡或标准化的部分。
第 6 部分:运行时视图(Runtime View)
以场景形式描述构建块的行为,覆盖重要用例或特性、关键外部接口上的交互、运维与管理、以及错误与异常行为。
- 内容:从以下领域以场景形式描述构建块的具体行为与交互:重要用例或特性(构建块如何执行它们);关键外部接口上的交互(构建块如何与用户、相邻系统协作);运维与管理(启动、初始化、停止);错误与异常场景。
- 要点:选择场景(序列、工作流)的主要标准是架构相关性,不必描述大量场景,而应记录有代表性的选择。
- 动机:运行时视图主要用于把架构传达给不情愿或没能力阅读静态模型(构建块视图、部署视图)的干系人。
- 形式:场景描述有众多表示法可选——带编号的自然语言步骤列表、活动图或流程图、时序图、BPMN 或 EPC(事件过程链)、状态机等。
第 7 部分:部署视图(Deployment View)
描述技术基础设施(环境、计算机、处理器、拓扑)以及(软件)构建块到基础设施元素的映射。
- 内容:系统运行所需的技术基础设施(地理位置、环境、计算机、处理器、通道与网络拓扑等),以及软件构建块到基础设施元素的映射。系统常在多个环境运行(开发、测试、生产),此时应记录所有相关环境;当软件作为多计算机/多处理器/多服务器/多容器的分布式系统运行时,或自行设计制造硬件处理器与芯片时,尤其需要记录部署视图。从软件视角只需记录展示构建块部署所需的元素,硬件架构师则可深入到任意细节。
- 动机:没有硬件软件就无法运行,底层基础设施会影响系统与若干横切概念,因此必须了解基础设施。
- 形式:最高层部署图可能已作为第 3.2 部分的技术上下文出现(自有基础设施是一个黑盒),本节用更多部署图放大该黑盒;复杂基础设施可用 UML 部署图(含嵌套图);若硬件干系人偏好其他图型,可使用任何能展示基础设施节点与通道的图。
7.1 基础设施第 1 层
通常以图、表与文字组合描述:系统到多位置/环境/计算机/处理器的分布及其物理连接;该部署结构的重要理由或动机;基础设施的质量与/或性能特征;软件构件(构建块)到基础设施元素的映射。多环境或备选部署时,为所有相关环境复制本节。
7.2 基础设施第 2 层
在此可包含基础设施第 1 层(某些)元素的内部结构,为每个选中元素复制第 1 层结构。
第 8 部分:横切概念(Crosscutting Concepts)
记录在系统多个部分都相关(横切)的总体原则、规则与解决方案方法。
- 内容:横切概念(实践、模式、规则或解决方案思路),如领域模型、架构模式与风格、特定技术的使用规则、实现规则等。
- 动机:概念是架构"概念完整性(一致性、同质性)"的基础,对达成系统内部质量有重要贡献;模板专门为此提供了集中描述的位置。
- 形式:形式多样——任意结构的概念文档;示例实现(尤其技术类概念);用架构视图表示法绘制的横切模型摘录或场景。
- 结构建议:只为系统挑选最必要的主题,每个主题给一个二级标题(如 8.1、8.2 等),不要试图覆盖上述所有主题。有些概念涉及系统全部元素,有些只与少数元素相关;集中记录可避免在相关构建块、硬件元素或开发流程描述中重复。
第 9 部分:架构决策(Architectural Decisions)—— ADR 的落位之处
这是 arc42 模板与 ADR 实践交汇的核心章节,记录重要、昂贵、关键、大规模或高风险的架构决策及其理由。
- 内容:重要、昂贵、大规模或高风险的架构决策及其理由。"决策"指基于给定标准选择某个备选方案。需要运用判断力决定某个架构决策是记录在本中心章节,还是更适合局部记录(如某构建块的白盒模板内),避免重复文本;并引用第 4 部分中已记录的最重要决策。
- 动机:系统干系人应能理解并回溯你的决策。
- 形式(三种任选):
- 为每个重要决策写一份 ADR(架构决策记录);
- 按重要性与后果排序的列表或表格;
- 每个决策单独成节、更详细的展开。
ADR 背景:为什么需要记录"理由"
模板指出:更小的文档片段更容易阅读、创建与维护。谈到架构决策时,开发团队常常"知道决策本身(它在源码中可见),却不知道决策背后的动机"(参见 Nygard 2011)。因此应记录少数重要决策连同其动机与推理。
模板的建议是:维护一份架构上重要的决策集合——即影响结构、质量特性、重要(尤其外部)依赖与接口、或构建技术的决策(该建议致谢 Michael Nygard)。仓库中 Michael Nygard 模板 即为此类轻量 ADR 的经典形态(Title / Status / Context / Decision / Consequences 五段式),可作为本节的单决策记录单元。
结合仓库的 ADR 写作规范
仓库 README.md 收录的《Suggestions for writing good ADRs》为第 9 部分提供了可落地的写作准则:
- Rationale(理由):解释做该决策的原因,可包含上下文、各候选方案的利弊、特性对比、成本/收益讨论等;
- Specific(具体):每份 ADR 只针对一个架构决策;
- Timestamps(时间戳):标识 ADR 中每项内容的写作时间,尤其对成本、进度、扩展性等随时间变化的内容;
- Immutable(不可变):不修改 ADR 既有信息,而是通过追加新信息修正,或用新 ADR 取代旧 ADR。
上下文(Context)部分应说明组织处境与业务优先级、团队构成带来的考量;后果(Consequences)部分应说明决策带来的影响、输出、后续动作,以及由本 ADR 触发的新 ADR(大决策常衍生多个小决策)。
第 10 部分:质量需求(Quality Requirements)
以场景形式呈现质量需求,并用质量树给出高层概览;最重要的质量目标应在第 1.2 部分描述过。
- 内容:本节包含所有相关质量需求。最重要的已在前文描述,此处仅需引用;本节还应记录次要质量需求(未完全达成不会造成高风险,但属 nice-to-have)。
- 动机:质量需求对架构决策影响巨大,因此应以具体、可测量的方式了解干系人真正看重的质量。
- 形式:参考 arc42 的 Q42 质量模型。
10.1 质量需求概览(Quality Requirements Overview)
面对几十甚至上百条细粒度质量需求,本节先做摘要:按类别或主题概括(如 ISO 25010:2023 或 Q42 所建议)。若摘要已足够精确、具体、可测量,可跳过 10.2 节。形式上可用简单表格(每行一个类别/主题 + 质量需求简述),或用思维导图组织;文献中亦有"质量属性树"概念——以通用词"质量"为根、树状细化([Bass+21] 称之为 Quality Attribute Utility Tree)。
10.2 质量场景(Quality Scenarios)
质量场景让质量需求具体化,并允许判断其是否达成(验收标准意义)。要确保场景具体、可测量。两类场景尤其有用:
- 使用场景(应用场景/用例场景):描述系统对特定刺激的运行时反应,含描述效率或性能的场景。示例:系统在 1 秒内响应用户请求。
- 变更场景:描述系统或其直接环境的修改/扩展的预期效果。示例:实现额外功能或质量属性需求变化时,测量变更的工作量与时长。
短格式(Q42 模型偏好)三要素:
| 要素 | 说明 |
|---|---|
| 上下文/背景 | 系统或组件类型、环境或情境 |
| 来源/刺激 | 谁或什么发起/触发行为、反应或动作 |
| 度量/验收标准 | 含度量或指标的响应 |
长格式(SEI 与 [Bass+21] 偏好)八要素:场景 ID(唯一标识)、场景名称、来源(发起场景的实体:用户/系统/事件)、刺激(系统必须处理的触发事件或条件)、环境(系统遭遇刺激时的运行上下文或条件)、构件(受刺激影响的构建块或其他元素)、响应(系统对刺激展现的结果或行为)、响应度量(评估系统响应的标准或指标)。
延伸参考:自 2023 年 1 月起,arc42 提供一个务实质量模型,建议用标签为质量需求打标,例如 #flexible、#efficient、#usable、#operable、#testable、#secure、#safe、#reliable。
第 11 部分:风险与技术债务(Risks and Technical Debt)
记录已知技术风险或技术债务:系统内部或周边存在哪些潜在问题?开发团队在哪些方面感到棘手?
- 内容:按优先级排序的已识别技术风险或技术债务清单。
- 动机:模板引用 Tim Lister(Atlantic Systems Guild)的名言——"风险管理是成年人的项目管理"。这应成为系统化识别与评估架构风险与技术债务的座右铭;管理干系人(项目经理、产品负责人)需要在整体风险分析与度量计划中使用这些信息。
- 形式:风险与/或技术债务清单,尽量附上降低、缓解或规避风险、减少技术债务的建议措施。
在项目中实际使用该模板
结合仓库的配套资源,可按下述流程落地:
- 判断是否需要完整架构文档:arc42 模板适合"需要完整架构文档、ADR 是其中一部分"的场景(见 templates.md 中 arc42 条目);若只是单个决策,优先选择 Nygard 等轻量模板。
- 创建文件:参照 孟加拉语版模板 或 英文原版模板,将 11 个章节骨架复制到项目文档中,逐节填写。
- 命名规范:仓库推荐使用"现在时祈使动词短语 + 小写 + 连字符 + .md"的文件命名,如
choose-database.md、format-timestamps.md(详见 孟加拉语版 README 索引)。 - 配合 git 管理:为 ADR 建立
adr/或decisions/目录,每份 ADR 一个 Markdown 文件并提交到版本库。 - 参考仓库示例:孟加拉语示例目录 与 英文示例目录 提供了 CSS 框架、环境变量配置、容器编排(如 Kubernetes 编排示例)等真实决策记录,可作为填写各章节的对照样本。
要点回顾
- arc42 决策记录模板是完整架构文档骨架,11 个章节依次覆盖:引言与目标、约束、上下文与范围、解决方案策略、构建块视图、运行时视图、部署视图、横切概念、架构决策、质量需求、风险与技术债务。
- 每节统一采用"内容 / 动机 / 形式"的写法,既说明该写什么,也解释为什么写、用什么形式呈现。
- ADR 落位于第 9 部分,与第 4 部分的核心决策摘要相互引用,避免重复文本;写作准则可参考仓库 README 中的 Rationale / Specific / Timestamps / Immutable 四项原则。
- 质量需求(第 10 部分)与质量目标(第 1.2 部分)前后呼应,场景化、可测量是共同底线。
- 本仓库同时提供 11 种 ADR 模板与多语言译本,可按决策复杂度在"单页 ADR"与"完整架构文档"之间选择合适的记录深度。