架构决策记录（ADR）实战指南：从概念到团队落地

最近在参与一个中大型项目的架构演进评审时团队内部对一个核心接口的改造方案争论不休。有人主张彻底重构有人建议小步迭代会议开了两小时最终结论却模糊不清只留下“再讨论”三个字。事后追溯发现类似的决策在项目历史上反复出现每次都要重新“考古”当时的上下文效率极低。这让我深刻意识到在软件工程中比写代码更难的是清晰地记录“为什么写这些代码”。决策记录Decision Records正是解决这一痛点的系统性方法。它不是简单的会议纪要而是一套用于捕获、沟通和追溯重要技术决策的结构化文档。本文将为你完整拆解决策记录的核心理念、标准模板ADR、实战创建流程并提供融入团队工作流的落地方案。无论你是团队TL、架构师还是核心开发者掌握这套方法都能让团队的技术债务更透明架构演进更有据可依。1. 决策记录的核心概念为什么它比代码更重要在开始动手之前我们必须先理解决策记录的“为什么”。很多团队有文档但文档散落在Confluence、GitHub Issue甚至聊天记录里最终沦为“最熟悉的陌生人”——大家都知道它存在但没人去看。1.1 什么是决策记录决策记录是一份活的文档它永久性地记录了一个已作出的、具有约束力的架构或技术决策。其核心在于记录“决策本身”以及做出该决策的上下文、权衡和理由而不仅仅是决策的结果。想象一下这个场景两年后一位新同事看到代码库中一个看似奇怪的实现比如为什么用A方案而不用更流行的B方案。如果有一份关联的决策记录他就能在几分钟内了解当时的技术背景、权衡比较和最终拍板的原因而不是靠猜测或发起又一轮漫长的讨论。1.2 决策记录 vs. 其他文档为了避免混淆我们明确一下边界与需求文档PRD的区别PRD描述“要做什么”What和“为谁做”Who。决策记录关注“怎么做”How和“为什么这么做”Why。与设计文档的区别设计文档通常描述系统的整体或局部设计可能包含多个决策。而一份决策记录通常只针对一个具体、离散的决策点。与代码注释的区别代码注释解释“这段代码在做什么”属于微观层面。决策记录解释“我们为什么选择这种架构/库/模式”属于宏观或中观层面。与会议纪要的区别会议纪要记录讨论过程包含各种观点和待办。决策记录是讨论的最终产出是达成共识的、具有行动指导意义的结论。1.3 哪些决策值得被记录并非所有决定都需要大张旗鼓地记录。一个实用的原则是记录那些如果被遗忘或误解会导致未来团队付出高昂代价的决策。通常包括技术选型为什么选择MySQL而不是PostgreSQL为什么用React而不是Vue架构模式为什么采用微服务而不是单体为什么事件驱动而不是同步调用接口设计为什么这个API的契约是这样定义的工具/流程引入为什么选择GitLab CI而不是Jenkins为什么引入Kubernetes重要的非功能性决策为什么将超时时间设置为5秒为什么数据库读写分离采用这种策略简单来说当团队为一个技术问题进行了实质性讨论并且该决策会影响后续开发、维护或系统扩展时它就值得被记录。2. 环境准备建立决策记录的文化与工具链决策记录的落地工具是载体文化与流程才是灵魂。在开始写第一份记录前需要做好以下准备。2.1 团队共识与文化这是最难也是最重要的一步。你需要让团队成员理解并认同决策记录的价值对个人减少重复解释保护自己的设计思路不被后续随意推翻。对团队形成组织记忆降低新人上手成本让技术讨论聚焦在未解决的问题上。对项目提供清晰的技术演进脉络便于审计、复盘和技术债务管理。建议在团队内部进行一次简短的分享用一两个“决策考古”的痛苦案例来引起共鸣。2.2 工具选择与代码共存亡决策记录必须与它描述的代码放在一起同时版本化。这是保证其“活性”和“可追溯性”的关键。首选方案在代码仓库的根目录或docs/目录下创建adr/Architecture Decision Record或decisions/目录。文件格式推荐使用纯文本标记语言如Markdown.md。它版本控制友好、易于阅读和编写。管理工具如果你使用Git那么决策记录自然地被Git管理。也有一些扩展工具可以帮助管理ADR比如adr-tools命令行工具但对于起步团队纯Markdown文件完全足够。2.3 目录结构示例一个清晰的结构有助于管理和查阅。建议采用如下方式your-project-repo/ ├── src/ ├── docs/ │ ├── adr/ # 存放所有决策记录 │ │ ├── 0001-record-architecture-decisions.md │ │ ├── 0002-use-markdown-for-adrs.md │ │ ├── 0003-choose-postgresql-over-mysql.md │ │ └── index.md # 决策记录索引/目录 │ └── other-docs/ └── README.md在README.md中可以添加一个指向docs/adr/index.md的链接方便所有人找到决策历史。3. 决策记录的核心模板ADR详解业界最广泛接受的决策记录形式是架构决策记录Architecture Decision Record, ADR由Michael Nygard在其文章 “记录架构决策” 中提出。一个标准的ADR模板包含以下部分3.1 ADR标准模板Markdown格式# [ADR-001] 使用Markdown编写决策记录 ## 状态 已提议 | 已通过 | 已弃用 | 已取代 ## 决策背景 * **问题陈述**我们需要一种一致、可版本控制的方式来记录项目中的重要技术决策。当前决策散落在会议纪要、聊天记录和邮件中难以查找和追溯。 * **决策驱动因素**团队规模扩大新人加入项目进入长期维护阶段需要清晰的技术债务台账。 ## 考虑过的方案 1. **Confluence/Wiki页面**易于编辑但与代码仓库分离容易过时且无法与代码变更关联。 2. **代码仓库中的纯文本文件**与代码共存可版本控制但缺乏结构可能内容杂乱。 3. **使用专门的ADR工具如adr-tools**提供命令行管理但引入了额外的依赖和学习成本。 4. **使用Markdown文件并遵循固定模板**结合了方案2和3的优点结构清晰、工具链简单、与Git无缝集成。 ## 决策结果 选择**方案4使用Markdown文件并遵循固定模板**。 * **积极影响** * 决策记录与代码一起版本化变更历史清晰。 * Markdown格式通用无需特殊工具即可阅读和编辑。 * 固定的模板确保了记录的一致性和完整性。 * **消极影响** * 需要团队成员遵守模板规范。 * 在代码评审中需要额外关注ADR文件的更新。 ## 遵循原则 * 所有ADR文件存放在 docs/adr/ 目录下。 * 文件名格式为 XXXX-short-title.md例如 0001-record-architecture-decisions.md。 * 使用本模板作为所有ADR的起点。 ## 相关决策 * 无此为第一份决策记录 * [ADR-002] 选择PostgreSQL作为主数据库 ## 备注 无。3.2 模板各部分精解标题与编号[ADR-001]格式提供了唯一标识便于引用。编号建议顺序增长。状态这是ADR的生命周期。一份ADR最初是“已提议”讨论通过后改为“已通过”。如果决策被推翻或技术过时状态可改为“已弃用”。如果被另一份ADR取代则改为“已取代”并应在“相关决策”中链接到新ADR。决策背景这是最重要的部分。必须清晰说明“当时我们面临什么问题”和“为什么要做这个决策驱动因素”。未来读者理解决策合理性的关键就在于此。考虑过的方案列出所有被认真评估过的选项。简要说明每个方案的优缺点。这体现了决策过程的严谨性也告诉后人“我们考虑过B方案但因为X原因没选”。决策结果明确选择哪个方案并阐述预期的积极和消极影响即权衡。诚实地记录负面影响技术债务、复杂度增加等能帮助未来团队理解当前系统的局限性。遵循原则记录决策所依赖或确立的通用规则、约定或原则。相关决策链接到受此决策影响或影响此决策的其他ADR。这形成了决策之间的网络便于梳理架构演进脉络。备注存放其他补充信息如讨论链接、实验数据、参考资料等。4. 完整实战创建并管理一份决策记录让我们以一个真实场景为例从头到尾演练如何创建和管理一份ADR。4.1 场景为新的用户服务选择数据库背景我们的单体应用正在拆分为微服务第一个要独立出来的是“用户服务”。需要为其选择一个持久化数据库。4.2 第一步识别决策点并创建ADR文件在项目根目录下执行# 进入决策记录目录 cd docs/adr # 查看已有记录确定新编号。假设最新是0002 ls # 0001-record-architecture-decisions.md # 0002-use-markdown-for-adrs.md # 创建新的ADR文件编号为0003 touch 0003-choose-postgresql-over-mysql.md4.3 第二步编写ADR内容打开0003-choose-postgresql-over-mysql.md填入以下内容# [ADR-0003] 为用户服务选择PostgreSQL作为主数据库 ## 状态 已通过 ## 决策背景 * **问题陈述**新的“用户服务”需要选择一个关系型数据库来存储用户核心数据如账号、档案、权限。该数据库需要支撑未来两年内预计百万级用户量并满足高可用、数据一致性和复杂查询的需求。 * **决策驱动因素** 1. 数据强一致性要求高用户账户信息不能出现脏读。 2. 业务需要支持JSON字段存储用户扩展属性并对此进行查询。 3. 团队对SQL和关系模型熟悉希望降低运维和学习成本。 4. 需要良好的开源生态和云托管支持如AWS RDS, Google Cloud SQL。 ## 考虑过的方案 1. **MySQL 8.0** * **优点**团队最熟悉历史项目广泛使用在简单读写场景下性能优异社区庞大。 * **缺点**对复杂查询如窗口函数的支持 historically 弱于PostgreSQLJSON支持是后期加入的功能和性能不如PostgreSQL原生。 2. **PostgreSQL 13** * **优点**标准SQL兼容性更好支持更丰富的SQL语法和数据类型如JSONB在复杂查询、地理空间数据和全文搜索方面有优势MVCC实现更彻底。 * **缺点**在高并发简单写入场景下默认配置可能需要进行更多优化部分国内云厂商的托管服务成熟度略低于MySQL。 3. **Amazon Aurora (PostgreSQL兼容版)** * **优点**云原生自动扩展、备份、高可用性能提升显著。 * **缺点**供应商锁定成本高于自建或标准RDS。 ## 决策结果 选择**方案2PostgreSQL 13**。 * **积极影响** * 更好地满足业务对JSON数据存储和查询的需求。 * 为未来可能涉及的复杂数据分析或地理信息服务提供了更好的基础。 * 遵循了公司技术栈向更开放、标准化的数据库靠拢的趋势。 * **消极影响** * 部分团队成员需要短暂学习PostgreSQL的特定优化技巧和配置项。 * 初期可能需要投入更多精力进行性能调优如连接池配置、索引优化。 ## 遵循原则 1. 新服务应优先考虑使用PostgreSQL除非有明确且压倒性的理由选择其他数据库。 2. 使用云托管的PostgreSQL服务如RDS以降低运维负担。 ## 相关决策 * [ADR-0002] 使用Markdown编写决策记录本文件格式遵循此决策 * 未来可能[ADR-XXXX] 用户服务数据分片策略 ## 备注 * 评估参考了2023年第三季度的技术基准测试报告《DB-Benchmark-2023Q3》。 * 决策在2023年10月26日的架构评审会上讨论并通过。4.4 第三步评审与状态更新发起评审将包含此ADR文件的Git分支提交并发起Pull RequestPR/MR。团队讨论在PR中团队成员可以就方案权衡、遗漏点等进行评论。讨论过程被记录在PR线程中。达成共识经过讨论修改后团队核心成员批准PR。合并与状态确认合并PR到主分支。此时该ADR的状态从“已提议”变为**“已通过”**并成为项目正式的技术约束。4.5 第四步关联与追溯在实现“用户服务”的代码中可以在README.md或相关配置文件中添加注释引用此ADR!-- 数据库选型依据见 ADR-0003 --。当未来需要评估数据库分片方案时新建的ADR如ADR-0004应在“相关决策”中链接到本ADRADR-0003说明当前决策是基于已选择的PostgreSQL。5. 常见问题与落地挑战引入决策记录初期团队可能会遇到一些阻力或困惑以下是典型的FAQ。5.1 “写这个太费时间耽误开发进度。”观点这是一种短视。写一份ADR通常需要30-60分钟但它节省的是未来数小时甚至数天的“决策考古”、重复讨论和纠正错误决策的成本。应对策略从最重要的、争议最大的决策开始写。用一两个成功案例快速帮新人理解系统、平息无谓争论向团队证明其长期ROI。5.2 “决策后来发现错了ADR不就打脸了吗”观点ADR不是用来证明决策永远正确的纪念碑而是记录技术演进的地图。应对策略ADR有“状态”字段。当决策被推翻时创建一份新的ADR来取代它。将旧ADR状态改为“已取代”并在新ADR中详细说明为什么旧决策不再适用例如出现了新技术、业务场景变化。这恰恰是知识积累的过程而不是“打脸”。5.3 “ADR写完了就没人看了。”观点如果ADR与流程脱节就会变成“死文档”。应对策略流程绑定在代码评审Code Review环节如果变更涉及架构改动要求作者关联或更新ADR。没有ADR先补上再评审。新人入职将阅读核心ADR列表作为新人入职任务的一部分。定期回顾在季度或版本复盘时快速回顾近期ADR评估决策结果是否符合预期。5.4 “模板太僵化有些简单决策不需要这么复杂。”观点模板是指导不是枷锁。应对策略对于非常明确、简单的决策例如“项目统一使用Prettier进行代码格式化”可以简化内容但必须保留“决策背景”和“决策结果”。背景解释了动机结果明确了行动方针。其他部分可以简写或省略。6. 最佳实践与工程建议要让决策记录真正产生价值而非流于形式需要遵循一些工程最佳实践。6.1 内容撰写原则为未来的陌生人而写假设读者是两年后的新同事他对项目历史一无所知。提供足够的上下文。保持客观中立在“考虑过的方案”中公平地列出各方案的优缺点即使你个人强烈偏好某一个。记录真正的权衡在“决策结果”中诚实地记录负面后果。例如“选择此框架会降低启动速度但提升了开发效率”。使用清晰的语言避免模糊的表述。不要说“性能更好”要说“在XX基准测试下QPS提升了20%”。6.2 流程集成实践轻量级评审ADR的评审不应像设计评审那样沉重。核心是确认背景清晰、方案考虑周全、结果明确。可以放在代码PR中一并评审。版本控制ADR的每次修改都必须通过Git提交并附上有意义的提交信息。这提供了完整的决策演变历史。维护索引在docs/adr/index.md中维护一个按状态和主题分类的ADR目录方便快速查阅。# 架构决策记录索引 ## 已通过 * [ADR-0001] 记录架构决策 * [ADR-0002] 使用Markdown编写ADR * [ADR-0003] 为用户服务选择PostgreSQL作为主数据库 ## 已取代/已弃用 * [ADR-0000] 初始原型方案已由ADR-0001取代6.3 工具与自动化利用Git Hooks可以设置pre-commit hook检查新创建的ADR文件是否遵循了基本的命名规范如NNNN-*.md格式。生成可视化图表有第三方工具如adr-viewer可以解析ADR目录生成决策之间的依赖关系图直观展示架构演进。与Issue/Bug关联当发现一个Bug源于过去的某个架构决策时可以在Bug描述中链接到对应的ADR这有助于定位根本原因。决策记录不是一份额外的官僚工作而是高效工程团队的“记忆外挂”和“决策保险”。它通过将关键的“为什么”固化下来让团队能够面向未来构建而不是反复陷入过去的迷雾中。从下一个有争议的技术讨论开始尝试推动大家“我们先写一份ADR草案吧。” 你会发现书写的过程本身就在强迫思考更全面、沟通更清晰。当ADR目录逐渐丰富它将成为项目最宝贵的技术资产之一无声地指引着每一次架构演进也让每一位后来者都能站在前人的肩膀上看得更远。