实践指南：ADR——轻量级架构决策记录机制
在快速迭代的软件开发中，架构不是“设计出来”的，而是“演化出来”的。架构决策记录 (Architecture Decision Record, ADR)是一种将这些演化过程文档化的轻量级实践，它记录了某个决策及其产生的背景和后续影响。
1. 团队面临的架构困境：为什么需要 ADR？
架构决策如果只存在于会议纪要或人的脑子里，团队将面临以下难题：
- 知识断层：“为什么当时选了 MongoDB 而不是 PostgreSQL？”——核心成员离职后，答案往往石沉大海。
- 重复“造轮子”：相似的问题反复讨论，却因为缺乏历史记录，每次都要从零开始评估。
- 盲目遵循与质疑：新人入场要么盲从过时的设计，要么在不了解历史约束的情况下发起无意义的重构。
- 决策成本比对：。修复一个架构错误的成本，远高于记录它的时间成本。
2. ADR 核心结构（模板化建议）
一个标准的 ADR 应该是自解释的。
核心要素速查表
| 模块 | 要求 | 说明 |
|---|---|---|
| 标题 | 编号 + 简短描述 | 如：ADR-005: 引入 Redis 作为二级缓存 |
| 状态 | 状态机管理 | Proposed(提议),Accepted(通过),Superseded(已取代) |
| 背景 | 解释“为什么” | 描述当时面临的需求、技术约束或环境痛点。 |
| 决策 | 明确“是什么” | 核心结论，采用肯定句式，减少模糊空间。 |
| 影响 | 评估“代价” | 这是灵魂。记录决策带来的正面收益和必须忍受的负面代价。 |
| 一致性 | 如何“落地” | 明确是通过代码 Review 还是自动化 Lint 来确保决策被执行。 |
3. ADR 的生命周期管理
ADR 不仅仅是记录，更是一个状态流转过程。
- 提议 (Proposed)：针对待解决的问题，由负责人发起 ADR 初稿。
- 评审 (Reviewing)：在技术方案评审会上进行讨论，根据反馈修改。
- 通过 (Accepted)：达成共识后，将 ADR 合并入文档库。
- 已取代 (Superseded)：当技术演进导致旧决策不再适用，不要删除旧 ADR，而是新建一个 ADR 并通过链接指向旧纪录，标记其为“已取代”。
4. 存储与管理策略：Code vs Wiki
| 方案 | VCS 存储 (推荐) | 协同平台 (如 Confluence/Notion) |
|---|---|---|
| 位置 | /docs/adr/*.md(代码仓库) | 企业知识库 |
| 优势 | 原子性：架构决策与代码变更同步提交。 | 易于非技术干系人（如 PM）查阅。 |
| 工作流 | 通过 Git Pull Request 进行异步评审。 | 通过评论或实时协作编辑。 |
| 建议 | 强推技术团队使用。架构决策应作为代码的一部分被维护。 | 适合跨部门、非纯技术的宏观决策。 |
5. 避坑指南：如何让 ADR 真正跑起来？
💡 核心差异：ADR vs. 技术设计文档 (Design Doc)
- 设计文档：是关于“怎么做”的详细图纸（包含类图、时序图、API 细节）。
- ADR：是关于“为什么这么做”的战略取舍。ADR 应该是设计文档的“摘要”或“前言”。
❌ 常见误区
- 流水账：背景描述过于琐碎，没有抓准核心矛盾。
- 报喜不报忧：只写收益，不写负面影响（没有完美的架构，只有折中的选择）。
- 事后补课：把 ADR 当成任务去完成，而不是决策的工具。
✅ 落地建议
- 工具化：引入
adr-tools等命令行工具，快速生成模板。 - 文化先行：将“查看 ADR”作为新人入职（Onboarding）的必修课。
- 循序渐进：先从“引入了什么库/中间件”这种大决策开始记录，不要事无巨细。
6. 总结
ADR 是团队“架构集体记忆”的载体。它不仅能让当下的决策更理性，更能让未来的维护者理解当年的苦衷。
架构师的金句：如果一个决策没有被记录下来，那么这个决策在未来就相当于不存在。
技术白皮书（上篇）)
技术白皮书（下篇）)
_kaic)