用 Git 版本控制管理架构决策记录（ADR）：从 mkdir 到 Commit 的完整实战

导读

本文基于 architecture-decision-record 开源仓库中的《Erste Schritte mit ADRs und Git》（用 Git 开始使用 ADR）文档，讲解如何在一个典型的带源码的软件项目中，用最朴素也最强大的 Git 工作流来落地 Architecture Decision Record（ADR，架构决策记录）。读完本文，你将掌握「创建adr目录 → 为每条决策创建 Markdown 文本文件 → 参考仓库模板撰写内容 → 提交进 Git 仓库」的完整闭环，并理解 Git 化 ADR 在命名、不可变性、版本历史与团队协作上的设计动机。

为什么用 Git 管理 ADR：把决策当作一等代码资产

ADR（架构决策记录）是一份记录「重要架构决策及其上下文与后果」的文档，而 ADR 的集合称为 ADL（架构决策日志）。当团队习惯使用 Git 版本控制时，最自然的做法就是把 ADR 当作与源代码同等对待的普通文本文件，放进版本库统一管理——这正是关联文档给出的核心思路：

如果您喜欢使用 Git 版本控制，那么我们乐于向您介绍如何为一个典型的、带源码的软件项目，用 Git 开始使用 ADR。

与文档类工具、Wiki 或在线表格相比，Git 方案的优势在于：ADR 与代码同库演进、每次修改都有可追溯的提交记录、天然支持分支与合并评审（如 Pull Request），并且不依赖任何第三方平台。你可以随时git log查看决策的演进史，用git diff对比决策修订，用分支隔离「提议中」的决策。

第一步：为 ADR 文件创建专属目录

原文档给出的第一个操作，是创建一个专门存放 ADR 文件的目录：

$ mkdir adr

adr是仓库生态中常用的目录名。同名技能文档 skills/architecture-decision-record-skill/SKILL.md 中也给出了查找既有约定的快速方法，即在动手前先确认项目里是否已存在 ADR 目录及既有命名/编号习惯：

git ls-files | grep -iE '(^|/)(adr|adrs|decisions?)(/|$)'

从源码结构与技能文档看，可以推断：如果项目里还没有约定，团队通常会默认使用顶层的adr/或decisions/目录；部分团队偏好decisions这个名字，因为「architecture」一词和「ADR」缩写会让部分开发者或管理者望而却步，而「decisions」能吸引更多类型的决策（供应商决策、规划决策、排期决策等）进入该目录，且这些内容都可复用同一套模板。本仓库的德文文档目录（如 erste-schritte-mit-adrs-und-git）本身就以多语言镜像的方式展示了这种目录化组织的形态。

第二步：为每条 ADR 创建一个文本文件

原文档强调：每条 ADR 对应一个文本文件。例如用 vi 创建：

$ vi database.txt

在此基础上，仓库的 日期文件命名约定文档 给出了更规范的建议——既然 ADR 是普通文本文件，就应该为文件命名制定一套约定。该仓库推荐的具体格式是：

因此，实操中更推荐将原文档示例中的database.txt升级为符合命名约定的 Markdown 文件，例如choose-database.md。仓库中的示例目录正是这样组织的，例如 选择数据库技术示例、MySQL 数据库示例、时间戳格式示例。

如果你的项目已经采用编号式 ADR（如 adr-tools 风格），技能文档 SKILL.md 还提示可以在文件名前加零填充序号，例如0007-choose-database.md；若项目此前无编号习惯，则使用不带编号的现在时动词短语文件名最简单、最易上手。

第三步：撰写 ADR 内容——从仓库模板与示例中取材

原文档写道：「在 ADR 中写任何你想写的内容，灵感可参考本仓库中的模板。」这意味着模板仓库的价值正是为「写什么」提供骨架。本仓库在 德文模板目录 下收录了多套知名模板，例如：

• MADR 项目模板（entscheidungsprotokoll-vorlage-des-madr-projekts）：结构为标题 → 状态（proposed / rejected / accepted / deprecated / superseded by）→ 决策者 → 日期 → 技术故事 → 上下文与问题陈述 → 决策驱动因素 → 备选方案 → 决策结果 → 正面/负面后果 → 各方案的优缺点 → 链接。它同时适合简单与详尽两种场景，后者的重点正是「选项及其优缺点」。
• 重要技术决策（ITD）模板（entscheidungsprotokoll-vorlage-für-wichtige-technische-entscheidungen）：标题直接陈述决策本身（而非主题描述），再依次填写「问题」「备选方案（选中项加粗）」「理由（只列决定性因素）」「备注（可选）」，专为需要管理层快速审阅、快速验证的轻量场景设计。

配套的 撰写优秀 ADR 的建议文档 给出了四条质量标准，可直接作为内容自检清单：

• 理由（Rationale）：解释作出该架构决策的原因，可包含上下文、各候选方案的优缺点、功能对比、成本收益讨论等；
• 具体（Specific）：每条 ADR 只针对一个架构决策，不把多个决策塞进同一文件；
• 时间戳（Timestamps）：标注每项内容的撰写时间，这对成本、排期、规模等随时间变化的要素尤其重要；
• 不可变（Immutable）：不要修改 ADR 中已有的信息；要么通过追加新信息来修订，要么创建新 ADR 来取代旧 ADR。

写作时可以参考仓库中真实完成的示例，例如 选择数据库技术 展示了「上下文 → 决策 → 理由 → 后果」的完整叙述，而英文原版示例 timestamp-format 则演示了带目录、假设、约束、立场、论据、影响、相关决策/需求/工件/原则、备注的详尽写法。

第四步：将 ADR 提交进 Git 仓库

撰写完成后，原文档要求将 ADR 提交到 Git 仓库：

$ git add adr/choose-database.md $ git commit -m "choose database" # 示例：提交信息与文件名约定呼应

这一「提交」动作是 Git 化 ADR 的灵魂所在：此后每条决策都有确定的作者、时间与变更范围，git log -- adr/可以还原整个决策演进史，git blame可以定位某段决策表述的引入者，团队评审则可以走分支 + Pull Request 的常规流程。仓库 README.md 与命名约定文档都强调「文件名采用现在时祈使动词短语，与提交信息格式相匹配」——这意味着在 Git 工作流里，文件名本身就能充当一条语义清晰的提交信息。

进阶：用 Git 承载 ADR 的不可变与取代（Supersession）

结合技能文档 SKILL.md 与好 ADR 建议，当一条新决策取代或推翻旧决策时，Git 工作流下的标准做法是：

1. 新建一个 ADR 文件来描述新决策；
2. 将旧 ADR 的状态更新为Superseded by 新 ADR；
3. 在新 ADR 的状态/链接区反向链接Supersedes 旧 ADR。

这与 MADR 模板中的superseded by ADR-0005状态位完全对应。需要说明的是：部分团队在实践中更偏好「活文档」模式——在既有 ADR 中插入带日期戳的新信息并注明「该信息在决策之后到达」，而非严格执行不可变；到底采用哪种，应由团队自行约定，并在仓库内保持一致。

仓库资源导航：从这里继续深入

• 概念入门：什么是 ADR——ADR、AD、ADL、ASR、AKM 五个核心术语的精确定义；
• 开始使用（无 Git）：erste-schritte-mit-adrs——决策识别、决策制定、决策实施与强制、决策分享、决策文档化五个讨论领域；
• 其他载体：erste-schritte-mit-adrs-und-werkzeugen——除 Git 外，还可选用 Google Docs/Sheets、Atlassian Jira、MediaWiki Wiki、MySpec 等工具承载 ADR，具体按团队习惯任意选择；
• 模板库：locales/de-001/vorlagen/index.md——MADR、arc42、EdgeX、Alexandrian 模式、业务案例、Planguage、Gareth Morgan、GIG Cymru NHS Wales、Tyree & Akerman、Nygard、ITD 等十余套模板；
• 示例库：locales/de-001/beispiele/index.md 与英文原版 locales/en-001/examples/index.md——覆盖数据库选型、CSS 框架、环境变量配置、认证授权、单仓 vs 多仓、时间戳格式等 40 余个真实决策场景；
• Agent 技能：skills/architecture-decision-record-skill/SKILL.md——判断「该决策是否需要 ADR」、建立目录、命名文件、挑选模板、处理取代关系的完整工作流，可直接复制到.claude/skills/使用。

小结

用 Git 开始使用 ADR 的全部要点可以浓缩为四步：mkdir adr建目录、为每条决策建一个符合「现在时祈使短语 + 小写连字符 +.md」约定的文本文件、参考仓库模板与示例填充「上下文—决策—后果」内容、最后git commit提交入库。这套做法零依赖、可追溯、与代码同演进，是架构知识管理（AKM）中投入产出比最高的起步方式之一。