ADR 架构决策记录实战：让技术选型可追溯可复盘

2026年9月11日技术杂谈 suzhe

当团队问起”当年为什么选 RabbitMQ 而不是 Kafka”，往往没人答得上来——当事人离职、聊天记录淹没、文档里只有结论没有理由。ADR（架构决策记录，Architecture Decision Record）就是为这个痛点而生的轻量实践：用一篇几百字的短文档，把”在什么背景下、面对哪些选项、最终选了什么、放弃了什么、会带来什么后果”固定下来。它不追求完美，只追求可追溯、可复盘。

一、ADR 解决什么痛点

技术决策最大的成本不是”选错”，而是”忘记为啥这么选”。没有记录，半年后的你会重提已经被否决的方案，新同事会重复踩坑，复盘时只能拍脑袋。ADR 把决策从散落的聊天记录和会议里抽出来，沉淀成仓库里可检索、可 diff、可评审的文档。

举个真实到扎心的例子：某团队两年前把单体拆微服务，却保留了一个所有服务共享的”大库”。后来新人想按服务分库，被老人一句”当初试过不行”挡了回去，但没人说得清”不行”具体指什么、当时的流量和数据量又是多少。如果当年留一篇 ADR 写明”共享库是过渡方案，待订单量过 X 即拆分”，今天的分库决策就有了依据，而不是一句模糊的”不行”。

它和技术选型决策实战里讲的”决策矩阵”是互补关系：决策矩阵帮你把选项摆清楚、量化打分；ADR 则负责把”最终拍板”这件事及其理由写进历史。两者配合，选型才既有过程又有结论。

二、一个能直接抄的 ADR 模板

ADR 的核心字段就五个：状态、背景、决策、后果、备选。下面是一份 MADR 风格的最小模板，一篇通常控制在 200–500 字，别写成设计文档。

# ADR-0012 订单服务引入本地缓存

## 状态
Accepted（已采纳）

## 背景
订单详情接口 P99 达 800ms，数据库 CPU 持续 70%+。
我们需要在"加缓存"和"加只读副本"之间做选择。

## 决策
引入 Redis 本地二级缓存（Cache-Aside 模式），
TTL 60s，热点 key 手动预热。

## 后果
- 好：P99 降到 120ms，DB CPU 降到 35%。
- 坏：出现短暂数据不一致窗口（≤60s），需在文档标注。
- 风险：大 key 风险，另见缓存治理规范。

## 备选（被否决）
- 只读副本：成本更高，且无法缓解热点行争用。
- 不缓存：性能不达标，已排除。

三、ADR 的生命周期：不是一次性的

ADR 是有寿命的。一个决策今天成立，明天可能因为技术债或业务变化被推翻。用状态字段管理它的生命周期，比删文档更诚实：

状态	含义	何时用
Proposed	提议中	刚起草，等评审
Accepted	已采纳	评审通过，开始执行
Deprecated	已弃用	仍有效但不推荐新场景用
Superseded	已被取代	被新 ADR 推翻，注明替代编号

关键规则：被推翻的 ADR 不要删除，而是把状态改成 Superseded，并在开头加一行”被 ADR-00XX 取代”。这样后人能完整看到演进链路，而不是只看到”现在的正确答案”。

一个典型的演进链路长这样：ADR-0003 在创业初期决定”单体 + 单库”以换速度（Accepted）；ADR-0019 业务增长后决定”订单服务独立分库”（Superseded 0003）；ADR-0041 又因合规要求把订单库迁到独立集群（Superseded 0019）。任何人翻开 0003，一眼就能顺藤摸到今天的架构，以及每一次转折的理由。这条链比任何口头传承都可靠。

四、把 ADR 接进你的工作流

ADR 最怕”建了目录没人写”。把它接进现有流程最稳：重大选型先写 Proposed 版，随技术方案评审实战的评审单一起过，评审通过即翻成 Accepted。下面这个小脚本能一键生成带编号和日期的骨架，降低书写门槛。

#!/usr/bin/env python3
# adr_new.py — 生成一篇 ADR 骨架
import datetime, pathlib, sys

seq = len(list(pathlib.Path("docs/adr").glob("adr-*.md"))) + 1
num = f"adr-{seq:04d}"
today = datetime.date.today().isoformat()
title = sys.argv[1] if len(sys.argv) > 1 else "待定决策"

tpl = f"""# {num} {title}

## 状态
Proposed

## 背景

## 决策

## 后果

## 备选（被否决）
"""
pathlib.Path(f"docs/adr/{num}.md").write_text(tpl, encoding="utf-8")
print(f"created docs/adr/{num}.md ({today})")