architecture-decision-records

Architecture Decision Records 技能详情

技能概述

Architecture Decision Records (ADR) 是一种用于记录重要技术决策上下文、理由和后果的轻量级文档模式，帮助技术团队建立透明的决策流程，实现架构决策的可追溯性和可审查性。

适用场景

1. 制定重要架构决策

当团队需要做出对系统有长期影响的技术选择时，如新框架选型、数据库技术选择、API 设计模式等，使用 ADR 捕获决策的上下文、考虑的选项及权衡取舍，确保决策过程透明可追溯。

2. 文档化技术选型

在评估和选择技术方案时，通过 ADR 记录各个选项的优缺点、决策理由和预期后果，帮助团队成员理解"为什么选择这个方案而不是那个"，为未来的技术复盘提供依据。

3. 建立团队决策流程

为技术团队建立标准化的决策记录流程，包括 ADR 目录结构、审查流程、状态管理等，使新成员能快速了解历史决策，促进知识传承和团队协作。

核心功能

1. 多模板支持

提供多种 ADR 模板以适应不同场景：标准 MADR 格式适用于完整的架构决策；轻量级模板用于快速记录；Y-Statement 格式适合简洁表达；RFC 风格用于需要广泛讨论的复杂决策；弃用模板用于记录技术演进路径。

2. ADR 生命周期管理

完整的决策状态流转：从 Proposed（提议）到 Accepted（接受），再到 Deprecated（弃用）或 Superseded（被替代），清晰记录每个决策的演进历程，支持使用 adr-tools 工具进行自动化管理。

3. 集成式决策文档

不仅记录决策本身，还包含决策上下文、驱动因素、考虑选项、正反面后果、实施计划、相关决策链接等完整信息，形成相互关联的决策知识网络。

常见问题

什么是 Architecture Decision Records (ADR)？

ADR 是一种轻量级文档模式，用于记录重要的架构和技术决策。每个 ADR 捕获三个核心要素：Context（为什么需要做决策）、Decision（做了什么决定）、Consequences（决定带来的后果）。ADR 不可修改，如需变更则创建新记录替代旧记录，从而保留完整的决策历史。

什么时候需要写 ADR，什么时候不需要？

需要进行 ADR 记录的场景包括：新框架采用、数据库技术选择、API 设计模式、安全架构、集成模式等对系统有长期影响的决策。不需要写 ADR 的场景包括：小版本升级、Bug 修复、实现细节、常规维护、配置变更等。判断标准是：这个决策是否影响未来一年或更长时间的架构方向。

如何让团队接受写 ADR 的流程？

从真实需求开始：先选择一个正在讨论的重要决策，用 ADR 模板记录下来，展示它如何帮助讨论更聚焦。设置合理的门槛：不是所有实现细节都需要 ADR，只在确实重要时使用。利用工具支持：使用 adr-tools 简化创建和管理。定期回顾：在站会或架构评审中讨论 ADR，建立阅读和引用的习惯。