架构决策记录 ADR 是什么
ADR（Architecture Decision Record）用轻量文档记录重要架构决策：背景、决策内容、后果与当前状态。它与代码同库管理，让后来者理解为什么这样设计，避免人员流动后重复争论同一个问题。判断是否该写 ADR 的标准很简单：这个选择会影响后续多个模块或团队，且存在被推翻的可能。
基本信息
| 核心要素 | 标题、状态、背景、决策、后果 |
|---|---|
| 状态取值 | 提议、接受、弃用、被取代 |
| 载体 | 与代码仓库一起的 markdown 文件，按序号编号 |
| 更新方式 | 原记录不篡改，被取代时新增记录并互相引用 |
| 适用判断 | 跨模块影响、难以逆转、存在多个备选方案 |
典型使用场景
- 引入中间件或数据库选型时记录备选方案与取舍理由
- 跨团队接口约定变更，需要留下对齐依据
- 被否决的方案也要记录，避免半年后重复评估
- 新人入职理解既有架构，从决策背景而不是代码猜测意图
- 技术债治理时追溯某项设计的原始约束是否已消失
ADR 模板示例
ADR 模板示例
# 标题用结论式表达，一眼能看出决定了什么
# ADR-012 采用消息队列解耦订单与库存
状态：接受（2026-09-12）
# 背景写约束与问题，不写解决方案，避免因果倒置
背景：峰值下单导致库存服务同步阻塞，接口超时率上升
# 决策要写清选择与放弃，以及放弃的理由
决策：引入 Kafka，订单事件异步消费；暂不自研队列
# 后果如实记录代价，包括运维复杂度与新增风险
后果：运维复杂度上升；需要监控积压与消费延迟记录要素与要求
| 要素 | 要求 | 常见写法问题 |
|---|---|---|
| 背景 | 描述问题与约束条件 | 直接写方案，读者不知为何要做 |
| 决策 | 明确选择与放弃项 | 只写采用什么，不写否决什么 |
| 后果 | 包含代价与新增风险 | 只写收益，掩盖后续成本 |
| 状态 | 反映当前是否仍有效 | 长期停留在提议或已失效未更新 |
ADR 贵在轻量：一页以内、与代码同库、提交时一并评审，才能持续维护；写成完整设计文档通常几周后就无人更新。