架构决策记录(ADR)实战:以 architecture-decision-record 仓库的"采纳 Go 编程语言"决策为例
架构决策记录(ADR)实战:以 architecture-decision-record 仓库的"采纳 Go 编程语言"决策为例
导读
本文以 architecture-decision-record 开源仓库中收录的丹麦语示例文档《Arkitekturbeslutningspost: programmeringssproget Go》(对应英文版《Architecture Decision Record: Go programming language》)为核心,逐段拆解一份标准 ADR 的完整写法:从"背景(Context)—决策(Decision)—理由(Rationale)—影响(Implications)—结论(Conclusion)"的骨架结构,到如何在真实项目中落笔、命名文件、确定状态与后续维护。读完本文,你将掌握直接可复用的 ADR 撰写范式,并理解本仓库为这一范式提供的模板、多语言示例与 Claude Code Skill 等配套资源。
一、先理解什么是 ADR
在进入示例之前,先明确 ADR 的定义。仓库 README 及丹麦语文档 hvad-er-en-arkitekturbeslutningspost 给出了一套严谨的术语体系:
- 架构决策记录(Architecture Decision Record,ADR):记录一项重要架构决策及其背景与后果的文档;
- 架构决策(Architecture Decision,AD):一项针对重大需求做出的软件设计选择;
- 架构决策日志(Architecture Decision Log,ADL):为一个项目(或组织)创建并维护的全部 ADR 的集合;
- 架构性重要需求(Architecturally-Significant Requirement,ASR):对软件系统架构产生可度量影响的需求;
- 上述内容统属于**架构知识管理(Architecture Knowledge Management,AKM)**的范畴。
本仓库的定位正是"软件规划、CTO/CIO 领导力团队协作与项目管理文档"的 ADR 资源库(见 README.md),其中 locales/ 下存放了多语言版本的模板、文档与示例,而本文剖析的 Go 语言示例正是其中一份典型的"具体编程语言选择"型 ADR。
二、示例文档的整体骨架
仓库中的原始示例文档位于 locales/da-001/eksempler/programmeringssproget-go/README.md,同目录还包含站点渲染用的 index.md,二者内容一致。其英文原版位于 locales/en-001/examples/go-programming-language/README.md,中文版本位于 locales/zh-cn/示例/go编程语言/README.md。
整份文档以五段式结构展开,这正是本仓库所推崇的、源自 Michael Nygard 的经典 ADR 模板骨架(仓库 skills/architecture-decision-record-skill/SKILL.md 将其归纳为 Title、Status、Context、Decision、Consequences 五个部分):
标题(Title):采纳 Go 编程语言
状态(Status):已接受(Accepted)
背景(Context)
决策(Decision)
理由(Rationale)
影响(Implications)
结论(Conclusion)
下面逐节还原该示例的核心内容,并补充深入解读。
三、背景(Context):如实交代组织现状与痛点
原文背景部分的核心事实是:该组织此前主要使用 Java 构建 Web 应用,但遇到了两类问题——一是 Java 语言本身的冗长(verbosity),二是某些框架的复杂性;同时团队对探索现代编程语言抱有浓厚兴趣。经过调研,团队将 Go 锁定为候选方案。
从 ADR 写作规范看,这段背景之所以合格,是因为它交代了三样关键信息(依据 forslag-til-at-skrive-gode-adr-er 中"好 Context 的特征"):
- 组织的处境与业务优先级:Java 是现状,但维护成本开始显现;
- 团队的构成与意愿:开发者有探索新语言的动力,这决定了后续"培训"是一项可落地的影响项;
- 选择的范围约束:Go 只是"潜在解决方案"之一,意味着决策前已有调研动作。
写好 Context 的关键不是罗列需求,而是讲清楚"我们当时站在什么位置、被什么力量拉扯"——这也是仓库写作指南反复强调的"forces in tension"。
四、决策(Decision):一句话说清方向
示例的决策陈述极为简洁:
今后我们将采用 Go 编程语言构建 Web 应用。
这正是 ADR 决策段应有的姿态:明确、不含糊、不设条件。仓库 skills/architecture-decision-record-skill/SKILL.md 第 5 节明确要求"Decision 应当平实地陈述所选方向,而非模棱两可(should state the chosen direction plainly, not hedge)"。同时,"一份 ADR 只对应一项架构决策"(Specific 原则)——本例只解决"语言选型"这一个问题,不把数据库、部署方式等一并塞入。
五、理由(Rationale):四条论据逐条展开
示例给出了四条理由,每一条都指向一个具体的架构关注点:
- 简单与可读(Simplicity and readability):Go 以简洁、紧凑的语法著称,降低代码阅读与编写成本,从而降低开发流程的整体复杂度;
- 高性能与可扩展性(High performance and scalability):Go 被编译为在服务器上原生运行的机器码,相比解释型语言执行更快;同时其并发模型(goroutine 与 channel 所支撑的 CSP 风格并发)能同时处理大量请求,具备高可扩展性;
- 强大的社区支持(Strong community support):Go 拥有活跃的开发者社区与丰富的库、框架资源,可降低团队上手与构建稳健应用的难度;
- 灵活性(Flexibility):Go 既可用于后端,也可用于前端(如通过 WASM 或各类工具链),组织可在两类项目中复用其优势。
需要留意一处原文的表述差异:丹麦语版理由 2 将 Java 描述为"解释型语言(fortolkede sprog)",而实际上 Java 是编译为字节码再由 JVM 解释/即时编译的语言。从技术准确性出发,更严谨的表述是"与运行在虚拟机上的语言相比,Go 编译为本地机器码、无虚拟机层开销"。这一点体现了阅读外部示例时仍需自行核实(README 顶部也以 IMPORTANT 提示:"在使用这些资源前请自行尽职调查")。
六、影响(Implications):把代价写清楚
ADR 的价值很大程度体现在"后果"部分。示例列出四项影响,正反两面都有:
- 培训(Training):开发者需要系统学习 Go 语言及其细微之处;
- 经验(Experience):从 Java 迁移到 Go 存在学习曲线,开发者熟练掌握新语言需要时间——这是切换期的显性成本;
- 工具(Tooling):需要引入 Go 专属工具链与框架(如
go build、go test、go vet、go mod等),但可复用既有基础设施以降低变更冲击; - 供应商锁定(Vendor lock-in):Go 是开源语言,组织不会被绑定到任何特定供应商或服务商——这是正向影响。
仓库写作规范(forslag-til-at-skrive-gode-adr-er)指出,好的 Consequences 段应包含:决策带来的效果与后续动作、以及由此衍生出的后续 ADR——比如本例落地后,可能还会触发"Go Web 框架选型""Go 项目目录结构规范"等更小的决策。同时建议团队在决策后一个月左右进行一次复盘(after-action review),将 ADR 中的预判与实际结果对照,形成学习闭环。
七、结论(Conclusion):给出最终判断
示例以一句总结收束:采纳 Go 将改进开发流程并帮助构建稳健应用;虽然需要投入培训与工具成本,但收益大于成本。
结论段的作用是为整个记录画上句号,便于后续读者快速判断"这份决策是否仍然成立"。配合文档顶部的 Status: Accepteret(已接受),一条 ADR 的完整生命周期状态就清晰可见了。仓库 skills/architecture-decision-record-skill/SKILL.md 给出了标准的五种状态:proposed | accepted | rejected | deprecated | superseded by <link>,当旧决策被新决策取代时,应新建 ADR 并在旧文档状态中标注"已被某 ADR 取代",而不是静默修改原文。
八、从示例到实战:在自己的项目中写一份 Go 语言 ADR
参照该示例,你可以按以下步骤在自己的代码仓库中落地(依据 how-to-start-using-adrs-with-git 相关流程 与 file-name-conventions-for-adrs):
1. 创建目录
$ mkdir adr
2. 按命名规范创建文件
文件名采用现在时祈使短语 + 小写 + 连字符 + .md 扩展名的约定,例如:
$ vi adopt-go-programming-language.md
仓库推荐的命名示例还包括 choose-database.md、format-timestamps.md、manage-passwords.md、handle-exceptions.md;如果项目需要编号,可加零填充前缀,如 0007-choose-database.md。
3. 套用模板填写
最简做法是直接套用 Nygard 五段模板:
# 标题:采纳 Go 编程语言
状态:已接受
## 背景
(组织现状、痛点、调研过程)
## 决策
(一句话陈述最终选择)
## 理由
(逐条列出论据:可读性、性能、社区、灵活性等)
## 影响
(培训、经验曲线、工具链、供应商锁定等正反两面代价)
## 结论
(收益与成本的权衡总结)
4. 提交进版本控制
$ git add adopt-go-programming-language.md
$ git commit -m "adopt go programming language"
文件名采用祈使短语的另一个好处就是与提交信息天然对齐。
九、仓库提供的配套资源
如果你希望更系统地掌握 ADR 写作,本仓库提供了完整配套:
- 多语言示例矩阵:同一份 Go 语言 ADR 在
locales/下提供了英语(en-001)、中文(zh-cn)、丹麦语等多个版本,可用于对照学习或直接引用; - 写作规范文档:forslag-til-at-skrive-gode-adr-er 系统总结了好 ADR 的四个特征——有理由(Rationale)、聚焦单一决策(Specific)、带时间戳(Timestamps)、不可变(Immutable),以及好 Context 与好 Consequences 的具体标准;
- 模板库:
locales/en-001/templates/收录了 Nygard、MADR、Tyree & Akerman、arc42、Planguage 等十余种模板,可按决策形态选用(详见 skills/architecture-decision-record-skill/SKILL.md 第 4 节的模板速查表); - Claude Code Skill:architecture-decision-record-skill 可直接指导 AI 编码代理完成"判断是否需要 ADR → 建目录 → 命名 → 选模板 → 撰写 → 处理取代关系"的全流程。
总结
这份"采纳 Go 编程语言"的 ADR 示例虽短,却完整示范了架构决策记录的核心方法论:用背景交代处境、用决策锁定方向、用理由支撑判断、用影响管理预期、用结论完成闭环。它既是一份可直接套用的语言选型决策模板,也是理解整个 architecture-decision-record 仓库(模板、多语言示例、写作规范、Agent Skill)的最佳入口。当你的团队下一次面临"换语言、换框架、选数据库"等架构决策时,不妨照此格式写下第一份 ADR——让"为什么"成为团队可继承的资产。