Proposed（提议中）——ADR已被提出但尚未被接受，正在团队评审阶段。Accepted（已接受）——ADR已被团队评审通过，成为当前有效决策。Superseded by ADR-NNNN（已被替代）——该决策已被新的ADR取代，需引用新ADR的编号。Deprecated（已弃用）——该决策已被主动废弃，但未被新的ADR替代。Amended by ADR-NNNN（已被修订）——该决策的基本框架仍然有效，但部分内容已被修订。

3.4 决策（Decision）

这是ADR的正文部分，清晰明确地陈述我们决定做什么。好的决策描述应该是确定性的动词。避免模糊的表述，如"我们考虑使用"或"我们倾向于"。

3.5 后果（Consequences）

这是ADR中最具价值的部分，记录决策实施后带来的正面和负面后果。它帮助未来的读者理解决策的完整影响。

四、轻量化ADR模板

以下是一个经过工程实践验证的轻量化ADR模板，适用于大多数团队场景：

# ADR-0012: 采用RabbitMQ作为异步消息中间件

## 状态
已接受（2024-06-15）

## 背景
订单处理模块需要实现异步削峰填谷，当前直接在请求流程中调用库存扣减、优惠券核销和通知发送，导致P99延迟超出SLA要求（1.2s）。经评估需要引入消息中间件将同步流程异步化。

## 约束条件
- 运维团队规模有限，需要中间件具备成熟的运维工具链
- 预算限制，排除商业中间件许可费用
- 团队已有Erlang/OTP运维经验

## 已评估方案
| 方案 | 优势 | 劣势 |
|------|------|------|
| RabbitMQ | 轻量、运维成熟、团队熟悉 | 吞吐量中等、大规模集群需要Erlang调优 |
| Apache Kafka | 高吞吐、持久化强、生态丰富 | 运维复杂度高、团队无经验 |
| Redis Stream | 极简部署、已有Redis基础 | 功能偏轻、不保证严格顺序 |
| AWS SQS | 全托管、零运维 | 供应商锁定、成本随量增长 |

## 决策
我们决定采用RabbitMQ作为系统的异步消息中间件，用于订单异步处理场景。

## 后果
**正面：**
- 订单处理P99延迟从1.2s降至180ms
- 利用现有Erlang运维经验，部署周期缩短50%
- 支持灵活的路由拓扑，便于后续业务扩展

**负面：**
- 峰值吞吐量受限于RabbitMQ单节点性能，需提前规划集群扩容
- 需引入额外的消息幂等性处理逻辑
- 丢失了Kafka生态带来的流处理能力，后续如需实时计算需额外引入Flink

五、工具链与自动化

要让ADR真正融入团队工程实践而非沦为形式主义的文档工作，合适的工具链至关重要。

5.1 adr-tools（命令行工具集）

由Nat Pryce维护的adr-tools是最早的ADR命令行工具集，提供初始化ADR仓库、创建新ADR、查看ADR列表等基础功能。它支持Bash和Windows PowerShell，适合个人或小团队使用。其核心命令包括：adr init docs/architecture/decisions 初始化仓库，adr new "选择PostgreSQL作为主数据库" 创建新ADR。

5.2 log4brains（可视化发布工具）

log4brains在adr-tools的基础上更进一步，提供静态网站形式的ADR展示，支持按状态筛选、全文搜索和Markdown渲染。它的publish命令可以将ADR仓库生成一个独立的静态站点，适合作为团队内部知识库使用。

5.3 Architecture Decision Records in DevOps

在DevOps流水线中集成ADR检查是一种进阶实践。可以通过CI/CD Pipeline的预提交钩子（Pre-commit hook）或Pull Request模板，确保每次涉及架构变更的代码提交都附带相应的ADR文件。例如，配置一个Git钩子规则：当提交消息包含[arch-change]标签时，检查是否同时提交了docs/adr目录下的ADR文件。

六、反模式与常见陷阱

6.1 文档形式主义

最常见的ADR反模式是"为了写ADR而写ADR"。团队花费大量时间打磨ADR的格式和措辞，而非关注决策本身的质量。这种情况下，ADR变成了一种官僚负担而非知识资产。

6.2 过度记录

不是所有决策都需要ADR。如果一个决策是可逆的、影响范围很小的或纯粹技术实现细节，写下ADR反而会增加不必要的认知负担。好的实践是：只有当一个决策是"有影响的、不可逆的或难以推翻的"时才值得用ADR记录。

6.3 写完即忘

ADR文件被创建后无人问津，从未被链接到实际代码或设计文档中也未在新成员入职时被推荐阅读，沦为知识仓库中的"僵尸文档"。

6.4 缺乏Ownership

没有明确指定每个ADR的负责人和有效期。当技术栈演进时，大量过时的ADR仍在仓库中保持"已接受"状态，导致团队成员无法判断哪些决策仍然有效。

七、如何在团队中推广ADR实践

推广ADR不是技术问题，而是团队文化变革问题。以下是经过验证的推广策略：

7.1 从小处着手——展示价值而非强推流程

7.2 与代码审查集成

将ADR评审融入代码审查流程。在Pull Request模板中增加"本次变更是否影响现有架构决策"的提示项，当勾选为"是"时，评审者要求提交者补充或更新ADR。

7.3 定期ADR审计

将ADR审计纳入Sprint回顾会议，每个季度花30分钟过一遍当前活跃的ADR。对已过时的ADR标记为"已弃用"或"已被替代"，确保知识库的时效性。

7.4 建立ADR文化

技术Leader以身作则，每次做架构决策时主动创建ADR并在团队会议中分享。当团队看到ADR真正帮助避免了"重复讨论"和"决策失忆"后，自然的采用动力会远强于行政命令。

八、ADR与架构治理的协同

在更成熟的技术组织中，ADR不是孤立存在的，而是与架构评审委员会（ARC）、技术雷达（Tech Radar）和架构知识图谱（Architecture Knowledge Graph）协同运作。

ADR驱动技术雷达更新：当某个ADR标记了一项技术为"已接受"或"已试用"的团队决策，技术雷达的更新便有了数据支撑，而非依赖主观印象。ARC则定期评审跨系统的ADR，确保决策之间的协同和一致性。

ADR形成架构知识图谱：当ADR积累到一定数量后，可以通过自然语言处理和图数据库技术，将ADR中的技术选性和约束条件抽取为知识图谱，实现团队决策知识的机器可读化和智能推荐。

九、实战案例：微服务拆分中的ADR应用

某电商团队在单体架构向微服务架构演进过程中，使用ADR记录了12个关键决策。其中包括：领域边界划分采用事件风暴工作坊方法、服务间通信以gRPC为主消息队列为辅、统一API Gateway选型Envoy而非Kong等。这套ADR体系帮助团队在6个月内完成了核心域的微服务拆分，且没有出现因决策反复导致的返工。更重要的是，当团队扩展到50人规模后，新成员通过阅读ADR序列即能理解系统架构的演进逻辑，平均入职熟悉时间从3周缩短至1周。

十、总结与行动建议

ADR本质上是一种将团队隐性知识显性化的工程实践。它不追求大而全的文档体系，而是抓住架构决策这个最核心的知识节点，以最低的成本实现最大的知识传承价值。

对于准备引入ADR的团队，建议的行动路径是：第一步，选择一个即将进行的技术选型，尝试用ADR模板记录决策过程并收集团队反馈。第二步，如果效果好，将ADR与代码仓库和Pull Request流程集成。第三步，建立定期ADR审计机制，确保知识库持续有效。第四步，探索ADR的高级应用场景，如与技术雷达和知识图谱集成。

记住，ADR的终极目标不是产出漂亮的文档，而是让团队的决策智慧得以积累、传承和进化。从今天开始，为你的下一个架构决策写一份ADR吧。