架构决策记录 ADR：别让方案只活在会议里

架构决策记录 ADR别让方案只活在会议里一、架构评审结束不代表决策被保存很多架构方案在评审会上讨论得很充分最后口头决定采用某个方案。但几个月后团队只记得“当时好像这么定了”却忘了为什么放弃另一个方案、哪些风险被接受、哪些前提条件成立。新成员加入后更是只能从代码里反推历史。ADR也就是 Architecture Decision Record可以把关键架构决策保存下来。它不需要写成长篇论文但要记录背景、选项、决策、取舍和后续影响。方案不能只活在会议里。二、ADR 记录的是决策不是宣传稿一份 ADR 应该能回答当时为什么这样选。flowchart TD A[业务背景] -- B[约束条件] B -- C[候选方案] C -- D[取舍分析] D -- E[最终决策] E -- F[后续影响]重点不是证明方案完美而是诚实记录取舍。好架构不是没有代价而是知道自己接受了什么代价。三、模板要简单团队才会写下面是一个简化 ADR 模板。# ADR-001: 选择消息队列方案 ## 背景 ## 候选方案 ## 决策 ## 影响 ## 回看时间模板太复杂会没人维护。ADR 应该短小、可检索、能持续更新。一次决策一篇不要把所有历史塞进一个大文档。四、ADR 要和代码、评审、运行数据连接ADR 最好放在仓库里跟随代码版本管理。相关 PR、设计文档、压测报告、监控面板都可以链接进去。这样后续看决策时不只看到文字还能看到证据。状态也要管理。一个 ADR 可以是 proposed、accepted、deprecated、superseded。架构会演进旧决策不一定永远正确但不能悄悄消失。废弃原因同样值得记录。复盘时要回看 ADR。当初接受的风险是否真的发生预估的收益是否兑现如果没有回看ADR 就只是更正式的会议纪要。最后ADR 能降低重复争论。团队换人、需求变化、技术栈升级时大家可以基于历史证据讨论而不是重新打一遍旧仗。ADR 还要记录“不做什么”。很多架构风险来自默认选项比如暂时不拆服务、暂时不引入消息队列、暂时不用某个中间件。如果只记录最终采用方案不记录被放弃方案后人很容易重复探索旧路。决策也要设置回看时间。比如三个月后观察性能指标半年后评估成本一年后确认团队维护能力。架构决策不是一锤子买卖前提条件变化时原来的结论也需要重新评估。最后ADR 不是替代沟通而是降低沟通成本。写下来以后会议可以少花时间回忆历史多花时间讨论新的证据和变化。这对长期维护的企业系统尤其重要。ADR 还可以帮助新人理解系统边界。新人看到某个模块为什么没有拆、为什么选同步调用、为什么不用某个热门框架就能少走很多弯路。架构知识如果只在少数人脑子里团队规模一变就会丢失。写 ADR 时要避免事后美化。真实决策往往有时间压力、组织约束、历史包袱和资源限制。把这些条件写清楚后人才能理解当时的合理性也能在条件变化后判断是否应该推翻旧决策。最后ADR 要有索引。按领域、状态、时间和系统模块建立目录才能被找到。找不到的文档等于不存在架构记录也一样。ADR 的粒度也要控制。太小会变成流水账每个配置选择都写一篇团队很快失去耐心太大又会把多个决策混在一起后续很难更新。比较合适的边界是这个决定会影响多个模块、长期维护成本或团队协作方式就值得记录。还要鼓励在 ADR 里写风险接受。比如短期为了交付选择单体实现接受未来拆分成本为了降低复杂度不用某个中间件接受部分能力需要手工处理。把风险写清楚不是暴露缺点而是让团队知道未来要观察什么。最后ADR 可以和技术雷达配合。某项技术从试验、采用、保留到淘汰每一步都能关联对应决策记录。这样架构治理不是一堆散文档而是一条能追溯的演进路径。五、总结ADR 的价值是保存架构决策背后的上下文和取舍。它不追求华丽追求可追溯、可回看、可更新。把关键方案写进 ADR团队才能在长期演进中保留判断力。