轻量级架构决策记录（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 是团队'架构集体记忆'的载体。它不仅能让当下的决策更理性，更能让未来的维护者理解当年的苦衷。
架构师的金句： 如果一个决策没有被记录下来，那么这个决策在未来就相当于不存在。
