Tyree & Akerman 架构决策记录模板实战指南:用 architecture-decision-record 项目构建可追溯的企业级 ADR
Tyree & Akerman 架构决策记录模板实战指南:用 architecture-decision-record 项目构建可追溯的企业级 ADR
本指南以开源仓库 architecture-decision-record 中收录的 Jeff Tyree 与 Art Akerman 决策记录模板(源自 Capital One 的论文《Architecture Decisions: Demystifying Architecture》)为骨架,系统讲解其 14 个字段的设计意图、填写要点与完整 Markdown 骨架。读完本文,你将能够在大型组织或受治理项目中写出与需求、原则、其他决策及架构产物显式可追溯的 ADR,并学会结合本仓库的示例与技能文件快速落地。
一、模板背景与定位:为什么选择 Tyree & Akerman
架构决策记录(Architecture Decision Record,ADR)是一份记录重要架构决策及其上下文与后果的文档,是架构知识管理(Architecture Knowledge Management,AKM)的核心载体。在 ADR 生态中,模板的复杂度差异很大:
- Michael Nygard 模板(Title / Status / Context / Decision / Consequences)简单易上手,适合大多数团队;
- Tyree & Akerman 模板则更复杂、更正式。仓库 README 在模板列表中明确将其标注为 more sophisticated(更精细),本仓库自带的 architecture-decision-record-skill 在选择模板时也给出了清晰定位:当团队处于企业环境、需要对需求与原则做可追溯(traceability)管理时,选用 Tyree & Akerman 模板。
该模板出自 Jeff Tyree 与 Art Akerman 在 Capital One Financial 发表的论文,其核心思想是:架构决策不是孤立的即兴选择,而是一组需要被组织、被论证、被追溯、被记录过程的完整证据链。因此它比"Context/Decision/Consequences"三段式多出大量"关系型"字段(Related decisions、Related requirements、Related artifacts、Related principles),适合决策需要接受评审、审计、跨系统对齐的场景。
二、14 个字段逐项详解:从 Issue 到 Notes
以下逐一解读模板的每个字段,括号内为字段的英文原名。请对照仓库中的阿拉伯语原文 قالب سجل القرار من Jeff Tyree وArt Akerman 与英文原版 decision record template by Jeff Tyree and Art Akerman。
1. 议题(Issue)
描述你正在处理的架构设计议题,要做到不留任何疑问——读者必须能清楚看出"为什么现在处理这个议题"。
- 采用极简主义(minimalist)思路:只处理并记录生命周期各节点上确实需要处理的议题,不要为记录而记录;
- 好的 Issue 应该让未来的读者理解触发条件与紧迫性,而不是一个宽泛的技术话题。
2. 决策(Decision)
清晰陈述架构的方向——也就是你所选定的立场(position)。
- 决策是行动导向的,应明确、不含糊;
- 写法上应直接给出结论,而不是复述议题或列举可能性。
3. 状态(Status)
记录决策当前的状态,模板给出的典型取值包括:
| 状态值 | 含义 |
|---|---|
| pending(待定) | 决策仍在讨论或等待中 |
| decided(已决定) | 方向已选定 |
| approved(已批准) | 决策已获得批准生效 |
状态字段让 ADR 集合可被"扫描":评审者一眼就能看出哪些决策已经生效、哪些还在路上。结合仓库技能文件的建议,也可以扩展为 proposed | accepted | rejected | deprecated | superseded by <link> 等更细的取值,并在状态变更时链接到替代它的新 ADR。
4. 分组(Group)
用简单分组来组织整套决策,例如:
- 集成(integration)
- 展示(presentation)
- 数据(data)
模板也给出更进阶的选择:采用更成熟的架构本体(architecture ontology),例如 John Kyaruzi 与 Jan van Katwijk 提出的本体,其中包含更抽象的类别,如事件(event)、日历(calendar)、位置(location)。例如按该本体,凡是"系统在某种发生场景下需要信息"的决策,都可以归入 event 分组。分组的意义在于让决策日志(ADL)可导航、可检索。
5. 假设(Assumptions)
清晰描述做决策时所处环境中的底层假设,包括但不限于:
- 成本(cost)
- 时间表(schedule)
- 技术(technology)
模板特别提醒:环境约束会限制你考虑的备选方案——例如已被组织接受的技术标准、企业架构(enterprise architecture)、团队惯用的模式等。把假设写清楚,是日后决策失效时做复盘的重要依据。
6. 约束(Constraints)
记录被选中的方案(决策)可能给环境带来的额外约束。注意它与"Assumptions"的区别:
- Assumptions 描述决策前环境既有的假设;
- Constraints 描述决策生效后新产生的限制。
例如在仓库示例 CSS framework 中,约束被表述为条件句:"如果我们选择依赖 jQuery 的 CSS 框架,就会被困在引入 jQuery 上;如果我们选择极简框架,就要放弃现在或不久后可能需要的组件。"
7. 立场(Positions)
列出你考虑过的立场(可行选项或备选方案)。这是模板中最需要笔墨的部分:
- 通常需要较长的说明,有时甚至需要模型与图表(models and diagrams);
- 这不是穷尽式列表(not an exhaustive list);
- 但它的存在有双重目的:
- 避免信任危机——如果在最终评审时被问"你想过……吗?",会导致公信力流失,并连累其他架构决策被质疑;
- 让参与者有归属感——显式列出并承认其他人的意见,有助于把反对者的支持者"拉拢"进你的决策。
仓库示例 CSS framework 的 Positions 段落是很好的范本:先说明"考虑过不用框架",再说明用快速初筛法考察了 Bootstrap、Bulma、Foundation、Materialize、Semantic UI、Tachyons 等多个框架,最终深入评估 Semantic UI(语义化最强)与 Bulma(最轻量且具备所需组件)两个候选,并分别给出试点结论和 HTML 代码片段。
8. 论证(Argument)
概括你为什么选择某一立场,内容包括:
- 实施成本(implementation cost)
- 总拥有成本(total ownership cost)
- 上市时间(time to market)
- 所需开发资源的可用性(required development resources' availability)
模板强调:这段论证的重要性可能与决策本身相当(probably as important as the decision itself)。没有论证的决策只是结论,有了论证的决策才是可辩护、可传承的知识。在 CSS 框架示例中,Argument 明确写到 Semantic UI 存在技术与领导力两方面的警示信号(jQuery 触点过多、官方对 jQuery-free 版本长期持拒绝态度)。
9. 影响(Implications)
模板援引 REMAP 元模型(Representation and Maintenance of Process Knowledge)指出:一个决策会带来大量连锁影响,例如:
- 引发需要做出其他决策;
- 产生新需求,或修改既有需求;
- 给环境施加额外约束;
- 需要与客户重新谈判范围或时间表;
- 需要对员工进行额外培训。
清晰理解并陈述影响,是**获得支持(buy-in)和制定架构执行路线图(roadmap)**的高效手段。例如"选择某框架"这类决策,往往随后触发"配套组件库选型""构建工具升级"等一连串下游决策。
10. 相关决策(Related decisions)
许多决策显然相互关联,可以在此列出。但模板给出了实践经验:在实践中,追溯矩阵(traceability matrix)、决策树(decision trees)或元模型(metamodels)比简单列举更有用;元模型尤其适合用图(如 Rose 模型)展示复杂关系。
11. 相关需求(Related requirements)
决策应当由业务驱动。为体现问责制(accountability),要把决策显式映射到目标或需求:
- 可以在此枚举相关需求;
- 但实践中更方便的做法是引用追溯矩阵;
- 可以评估每个架构决策对满足每个需求的贡献,再评估该需求在所有决策下被满足的程度;
- 模板给出了一条硬性原则:如果一个决策对满足任何需求都没有贡献,就不要做这个决策(If a decision doesn't contribute to meeting a requirement, don't make that decision)。
这是本模板"企业级可追溯"定位的核心体现,也是它与轻量模板最大的区别。
12. 相关产物(Related artifacts)
列出受此决策影响的相关架构、设计或范围文档。例如 CSS 框架决策会"影响所有将使用该 CSS 的典型 HTML"(见仓库示例的 Related artifacts 段)。
13. 相关原则(Related principles)
如果组织有一套已达成共识的原则集,请确保决策与其中一条或多条一致。这有助于保证跨领域或跨系统的对齐(alignment)。仓库示例 CSS framework 给出的原则是 Easily reversible(易于逆转)与 Need for speed(追求速度),简洁而有代表性。
14. 备注(Notes)
由于决策过程可能持续数周,模板建议记录团队在决策发布与协商(socialization)过程中讨论的备注和议题。这些过程性信息不会进入正式论证,但对后续修订、复盘和理解决策背景极有价值。
三、可直接复制的 Markdown 骨架
将下面的骨架复制到你的 ADR 文件中,替换方括号内容即可。本仓库的 architecture-decision-record-skill 中同样收录了这一骨架(见 reference/templates.md):
* **Issue**: 正在处理的架构设计议题,不留任何"为何现在处理"的疑问。
* **Decision**: 架构的方向——所选定的立场。
* **Status**: pending | decided | approved
* **Group**: 简单分组(integration、presentation、data……)以组织决策集合。
* **Assumptions**: 决策环境中的底层假设——成本、时间表、技术等。
* **Constraints**: 被选方案给环境带来的额外约束。
* **Positions**: 考虑过的立场(可行选项/备选方案)。
* **Argument**: 为何选择该立场——成本、上市时间、资源可用性等。
* **Implications**: 该决策接下来要求什么——新需求、重谈范围、员工培训、触发的其他决策。
* **Related decisions**: 与此决策相关的其他决策。
* **Related requirements**: 此决策映射到的需求/目标。
* **Related artifacts**: 受影响的架构、设计或范围文档。
* **Related principles**: 与之对齐的组织既定原则。
* **Notes**: 协商过程中产生的备注与议题。
四、实战演示:以仓库的 CSS Framework 示例为范本
仓库中现成采用该模板结构书写的完整实例是 CSS framework 决策记录,其目录结构本身就是模板的分层:
Summary(Issue / Decision / Status)
Details(Assumptions / Constraints / Positions / Argument / Implications)
Related(Related decisions / Related requirements / Related artifacts / Related principles)
Notes
从该示例可以提炼出几条可复用的写法:
- Issue 用"我们想要……"开头,并列列出多条动机(快而可靠的体验、快速迭代设计、响应式适配等),让"为什么现在做"不言自明;
- Decision 与 Status 分开写:Decision 直接给结论("Decided on Bulma"),Status 补充开放条件("Open to new CSS framework choices as they arrive");
- Positions 写入真实调研过程:包括"不用框架"选项、快速初筛的完整候选名单、两个深入候选的试点经历、甚至失败尝试的原因(jQuery 加载问题)与社区反馈——这正好呼应模板中"避免最终评审时被问'你想过吗'"的告诫;
- Related principles 用短语而非长句,如
Easily reversible、Need for speed,保持可扫描性。
其他同样采用该结构的仓库示例还包括 environment-variable-configuration、metrics-monitors-alerts、microsoft-azure-devops、monorepo-vs-multirepo、secrets-storage、timestamp-format 等,可作为不同技术领域的写法参考。
五、填写要点与常见误区
结合仓库的 writing-guide.md 与 SKILL.md,使用该模板时应注意:
- 一个 ADR 只写一个决策:不要把多个架构上相互独立的决策塞进同一份文件;
- 给易变信息打时间戳:成本、供应商定价、扩展规模数字等会过时,务必标注日期;
- 默认不可变(immutable):不要改写已接受 ADR 的原始内容,应通过追加带日期的补充信息来修订,或用新 ADR 取代旧 ADR,并在 Status 中写明
Superseded by new-adr及反向链接。若团队刻意选择"活文档(living document)"风格,也应在项目内保持一致并明示采用哪种约定; - Context/Assumptions 要写组织真实处境:包括业务优先级、团队构成、技能结构,而不是"我们需要一个数据库"式的套话;
- Consequences/Implications 要同时覆盖变容易和变困难的部分,并显式点出由此触发的后续 ADR——一个大的顶层决策常常引发一串更小的下游决策;
- 记录状态迁移:若采用正式生命周期(如 Initiating → Researching → Evaluating → Implementing → Maintaining → Sunsetting),可用"问题是否清晰、备选是否真正被考虑、权衡是否充分记录、相关利益方是否全部参与、反馈是否全部纳入"作为阶段门禁的验收标准。
六、与其他模板的选型对照
该模板并非唯一选择。仓库 README 与技能文件的选型表给出了完整对照,你可以按决策形状选择:
| 场景 | 推荐模板 |
|---|---|
| 默认 / 大多数团队 / 不确定 | Nygard(最简) |
| 需要轻量"选项+优缺点" | MADR |
| 企业环境、需求/原则可追溯 | Tyree & Akerman |
| 快速的高管审批(库、模型、CI 策略) | ITD |
| 供应商/工具选型、成本与 SWOT | Business case |
| 一句话 Y-statement 摘要加叙述 | Alexandrian pattern |
| 正式的、可测试的非功能需求语言 | Planguage |
| 完整架构文档(ADR 为其一部分) | arc42(§9) |
可见,当你的组织存在正式治理流程、需要把架构决策显式挂接到需求与原则上时,Tyree & Akerman 模板是最契合的选择;而若只需轻量记录,Nygard 更省力。
七、总结
Tyree & Akerman 模板把 ADR 从"一段备忘"升级为"一条可追溯的证据链":Issue 说明触发原因,Decision/Status 固化结论,Group/Assumptions/Constraints 交代上下文,Positions/Argument 记录论证过程,Implications 预警连锁后果,而四个 Related 字段(decisions / requirements / artifacts / principles)把单个决策织入组织整体的决策网络、需求矩阵与原则体系。在 architecture-decision-record 仓库中,你可以直接阅读阿拉伯语与英语双语原版模板、复制技能文件中的 Markdown 骨架,并以 CSS framework 示例 等十余个真实决策记录为参照,在自己的受治理项目中立即投入使用。