一句话导读
ADR（Architecture Decision Record）是轻量记录架构决策的实践：每条决策写清「背景、决策、后果、备选方案」。它不是标准，而是被广泛采用的最佳实践——解决「半年后没人记得当初为什么这么选」的经典问题。
ADR（Architecture Decision Record）是轻量记录架构决策的实践：每条决策写清「背景、决策、后果、备选方案」。它不是标准，而是被广泛采用的最佳实践——解决「半年后没人记得当初为什么这么选」的经典问题。
一、实践画像
| 项 | 内容 |
|---|---|
| 出处 | Michael Nygard 提出；MADR 模板社区流行（Markdown ADR） |
| 性质 | 最佳实践 / 工程文化（非认证标准） |
| 适用层级 | 架构级、技术选型、关键约定——凡是「影响长期、难以回退」的决定 |
| 文档形式 | 通常 Markdown，随代码库管理，编号递增 |
二、经典模板（MADR 精简版）
| 字段 | 写什么 |
|---|---|
| 状态 | 提议 / 接受 / 已替代 / 废弃 |
| 背景 | 为什么有这个决策（问题、约束、触发事件） |
| 决策 | 我们选了什么、为什么选它 |
| 后果 | 正面影响 + 负面影响 / 成本 / 权衡 |
| 备选方案 | 考虑过但没选的路，以及理由 |
三、什么时候该写
- 技术选型（框架 / 数据库 / 云 / 存储方案）；
- 架构模式取舍（微服务 vs 单体、实时 vs 批处理）；
- 安全与合规决策（认证方案、数据存储位置）；
- 有「备选但没选」时——备选理由比结论更有价值；
- 不写：琐碎实现细节、日常 bug 修复。
四、落地建议
- 一页纸原则：写不满一页就不用写，超过一页就说明决策没想清；
- 编号递增：ADR-001、ADR-002…，永不删除，可标记「已替代」；
- 随代码管理：和文档 / 规范放一起，版本受控（对应我们 docs/决策记录/）；
- 变更旧决策也要写：推翻一条 ADR = 新写一条 ADR 引用旧编号。
五、与我们的关联（直接命中）
我们在 8/20 早上把 ADR 机制落地为
我们在 8/20 早上把 ADR 机制落地为
docs/决策记录/（调研报告建议①）：
- 已补录 ADR-001~005：b64 登录编码 / 主站迁移轻量云 / cookie 认证 v5 / 规范版本注册表 / 双根同步；
- 《网站管理办法》§4 增加 ADR 条款并升版 v1.7.0；
- 模板即 MADR 精简版（背景 / 决策 / 后果 / 备选）。
⚠️ 本文为信息整理（🟢 基于公开资料：Nygard《Documenting Architecture Decisions》与 MADR 项目）。