轻量级架构决策记录（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) |
|---|
