架构决策记录ADR方法

可视化演示

动态演示架构决策记录ADR方法的核心机制，通过基础/核心/应用/扩展四种模式展示关键概念与交互流程。

什么是 ADR

探险队的旅行手账里，不会把每一块石头、每一棵草都记下来。它只记录岔路口：你面前有哪几条路、天气如何、体力还剩多少、最后选了哪条。ADR 就是技术世界里的“岔路口手账页”，全称 Architecture Decision Record，翻译过来是“架构决策记录”。它用一页轻量 Markdown 文档，把一次重要技术选型的来龙去脉固定下来。

很多人以为 ADR 是“写文档”，其实它更像“拍板时拍张照”。当团队决定“用 PostgreSQL 还是 MongoDB”“AI 推理用 TensorRT 还是 ONNX Runtime”，这些选择往往影响后续几个月甚至几年。ADO 不记录每一行代码怎么写，只记录“当时为什么做这个决定”，让后人不必把所有讨论重新经历一遍。

一条 ADR 通常由四个要素组成：背景、决策、状态、后果。背景是当时的约束和可选方案；决策是最终选择；状态表示这条记录目前是提议、已接受还是已废弃；后果是选择带来的收益和风险。这个结构保证了任何一个人拿起记录，都能在几分钟内复原当时的思考现场。

团队在写 ADR 时，不必追求长篇大论。手账的价值在于“当时有感而发”，而不是“事后补齐史诗”。只要站在未来三个月后的自己面前，问一句“能不能看懂”，就足够了。

ADR 的核心价值

探险队最怕的不是选错路，而是忘记当初为什么选。一个季度后，老队员走了，新队员问“为什么系统用了这个奇怪的队列”，所有人面面相觑。如果手账上写着“当时评估过 RabbitMQ，但团队没有运维 Erlang 的经验，所以选了 Kafka”，这个问题就不会再被翻来覆去地讨论。

ADR 的核心价值是“决策可追溯”。它把散落在聊天记录、会议纪要和大脑记忆中的信息，压缩成结构化的文字。任何时间点，团队都能通过一条 ADR 回答三个问题：当时要解决什么？为什么选这个方案？我们放弃了什么？这层可追溯性，是 AI 团队快速迭代时最容易忽略却最值钱的基础设施。

从成本角度看，写 ADR 的边际成本很低，但重复讨论的边际成本很高。一次五人的技术评审会可能消耗两小时，而一条 ADR 只需要十分钟阅读。ADR 越多，旧问题越不容易被反复翻出来，团队也越能把精力放在新问题上。

在 AI 项目中，模型选型、特征口径、推理部署等决策经常横跨算法、工程、产品多个角色。ADR 让这些角色不用每次都回到原始出发点争论，而是先看手账，再决定是否真的需要变。

ADR 模板结构

旅行手账有一种固定版式，你绝不会把封面和正文混在一起。ADR 也有一套约定俗成的模板，让团队扫一眼就知道该去哪里找信息。下面是常见的最小模板：标题、状态、背景、决策、后果。

• 标题：一句话说清“做了什么决策”，例如“采用向量数据库作为知识库检索后端”。

• 状态：当前是提议、已接受、已替代还是已废弃。

• 背景：解释为什么要做这个决策，包含触发器、约束和候选方案。

• 决策：写出最终选择以及为什么选它。

• 后果：写明正面收益、负面影响，以及未来需要重新评估的信号。

一个常见的写法是“背景 + 决策 + 后果”三段式。背景回答“为什么会走到这个路口”，决策回答“走了哪条路”，后果回答“这条路会带来什么”。状态字段放在标题下，像便签上的红章，提醒读者这条 ADR 是否还有效。

模板不是枷锁，而是“最低共识”。如果团队觉得三段不够，可以增加“备选方案”或“参考链接”；如果觉得太啰嗦，也可以压缩成几句话。关键是所有人都遵循同一套结构，这样跨项目检索时才不会迷路。

ADR 生命周期

手账里的每一页并不是永远有效。有的便签写着“初步计划”，后来被划掉；有的页面被新的一页取代，旧页被贴上一张“已废弃”的标签。ADR 的生命周期也是如此：它从“提议”开始，经过评审成为“已接受”，之后可能因为新决策而进入“已替代”或“已废弃”。

生命周期中的四种常见状态是：提议（Proposed）、已接受（Accepted）、已替代（Superseded）、已废弃（Deprecated）。提议表示还在讨论；已接受表示团队拍板确定为当前决策；已替代表示已经被新 ADR 取代；已废弃表示该决策不再适用但保留存档。

状态变化最重要的原则是“旧记录不能静默消失”。当一条新 ADR 被接受并取代旧方案时，必须回到旧 ADR 中把状态改成“已替代”，并链接到新 ADR。这就像手账里贴一张交叉引用：“想看最新路线？翻到第 18 页。”只有这样的回链，决策谱系才完整。

在 AI 领域，模型、框架和基础设施迭代极快。一条“选用 BERT”的 ADR 可能在半年后被“改用大模型 API”的 ADR 替代。这不是失败，而是团队认知升级的证据。

ADR 落地流程

有了一本漂亮的手账，并不等于队伍会用。落地流程要回答的关键问题是“什么时候写、谁来审、谁来维护”。如果你要等周五下班前统一补记录，那手账大概率会变成流水账；如果每次选路时顺手写一页，它才能保持鲜活。

落地流程可以分成五步：触发、起草、评审、合并、维护。触发条件通常是一次有长期影响、难以无损回退的技术选型；起草要求负责人在做决定前或决策当天写下 ADR；评审可以放在代码评审（PR）中异步进行，不必额外开会；合并意味着把 ADR 文件随代码一起提交到 Git 仓库；维护则是在后续变化时更新状态或补充后果。

团队可以约定一个极简阈值：如果一个决策需要开会讨论超过十五分钟，就值得写一条 ADR。这句话能过滤掉大量琐碎选择，让团队把力气花在真正影响长期架构的问题上。

一次完整的 ADR 落地不需要超过半小时。正是这种轻量，让它可以持续运转，而不是像一套重型文档流程那样虎头蛇尾。

常见反模式

再好的旅行手账，如果变成流水账，也会失去意义。ADR 实践中最常见的失败，不是“没人写”，而是“写成了没人看的东西”。比如有人把每个候选方案的所有实验数据、每段聊天记录都塞进 ADR，结果是真正想找答案的人根本找不到重点。

另一个典型问题是没有背景。只写“选择方案 A”，不写“为什么不用方案 B”，后人拿到手账也只会记住结论，无法重建当时的权衡。还有团队在 ADR Accepted 之后再也没改过状态，旧决策已经实际失效，页面还挂着“已接受”，误导后来的人。

一条 ADR 的健康度，可以用“仍然被阅读、仍然被引用”来衡量。如果大量 ADR 躺在仓库里吃灰，说明它已经变成文档负债。健康的 ADR 库应当像一本常翻常新的手账：该废弃的及时标记，该引用的随手可达，不该写的绝不硬凑。

所以，写 ADR 之前要问自己一句：这一页，未来会有人翻吗？如果答案是“不会”，那就别写；如果答案是“会”，就把它写清楚。

工具与协作

手账记得再多，如果没有编号和目录，也只是一堆散纸。ADR 的协作机制同样需要一套“收纳系统”：统一编号、统一命名、统一存放。最常见的做法是在仓库根目录创建 docs/adr/ 文件夹，每个文件命名为 NNNN-标题.md，例如 0001-使用向量数据库.md。

编号可以从 0001 开始连续递增，也可以按年份分段，例如 2025-001。命名规范要求标题中的单词用短横线连接，方便在命令行和 Git 里查看。这类规范不需要复杂工具，纯 Git 就能管理：ADR 随代码一起提交，改动通过 PR 评审，历史通过 Git 回溯。

如果团队希望更高效，可以使用 adr-tools、adr-log 等周边命令行工具，自动生成目录、建立状态索引，甚至渲染成静态站点。但更重要的是团队共识：新决策先查已有 ADR，评审 PR 时把 ADR 当作一等公民，而不是可选的“附加文档”。

工具只是脚手架，真正让 ADR 活下去的是团队的共同习惯。每次重要选型，大家养成条件反射式地打开 docs/adr/ 翻一翻、写一写，这本旅行手账才会成为团队真正的集体记忆。

AI 应用场景

Python 演示

from dataclasses import dataclass  @dataclassclass ADR:    seq: int    title: str    status: str    context: str    decision: str    consequence: str     def file_name(self) -> str:        return f"{self.seq:04d}-{self.title}.md"     def to_markdown(self) -> str:        return (f"# {self.seq:04d}-{self.title}\n\n"                f"状态：{self.status}\n\n"                f"## 背景\n{self.context}\n\n"                f"## 决策\n{self.decision}\n\n"                f"## 后果\n{self.consequence}\n")  class ADRLog:    def __init__(self):        self.records = []        self._seq = 0     def add(self, title, context, decision, consequence):        self._seq += 1        adr = ADR(self._seq, title, "已接受", context, decision, consequence)        self.records.append(adr)        return adr     def supersede(self, old_seq, title, context, decision, consequence):        if 1 <= old_seq <= len(self.records):            self.records[old_seq - 1].status = "已替代"        self._seq += 1        new_adr = ADR(self._seq, title, "已接受", context, decision, consequence)        self.records.append(new_adr)        return new_adr     def render_all(self) -> str:        return "\n\n---\n\n".join(r.to_markdown() for r in self.records)  if __name__ == "__main__":    log = ADRLog()    a1 = log.add(        "选择消息队列",        "服务需要异步解耦，团队无 Erlang 运维经验",        "采用 Kafka 作为消息中间件",        "运维复杂度上升，但生态最成熟"    )    a2 = log.add(        "引入特征平台",        "离线在线特征不一致导致模型效果波动",        "采用 Feast 统一特征口径",        "需要学习新组件，但特征一致性提升"    )    a3 = log.supersede(        a2.seq,        "替换特征平台",        "Feast 运维成本高，社区方向调整",        "改为自研特征服务",        "保留数据迁移窗口，旧 ADR 标记为已替代"    )    print(a1.file_name())    print(log.render_all())

1. adr = ADR(self._seq, title, "已接受", context, decision, consequence)创建一条正式 ADR，相当于向旅行手账里贴入新的一页。
2. self.records[old_seq - 1].status = "已替代"新决策出现时，把旧 ADR 状态改为“已替代”，保证决策链条完整。
3. def to_markdown(self) -> str:将 ADR 渲染为 Markdown，方便直接写入 docs/adr/NNNN-标题.md。
4. f"{self.seq:04d}-{self.title}.md"按 ADR 规范生成四位数编号文件名，例如 0001-选择消息队列.md。
5. log.render_all()一次性导出全部 ADR，形成团队可检索的决策手账。

常见误区

面试题