ADR-Tools

架构决策记录的命令行工具——
让重要的技术决策，像代码一样被版本管理。

经典之作 · 源自 Michael Nygard 2011 年 ADR 文章 · ADR 实践的奠基工具

一句话定义

给技术决策建一本账。

轻量 CLI，把架构决策记录成 Markdown，随项目版本管理。

技术决策为什么丢失

• 口头决策无记录
  架构选型在会议室定下，会散即忘，只剩结果不见理由。
• 只留结论不留上下文
  代码能看出"做了什么"，看不出"为什么这么做"，备选方案更无人知。
• 新人反复踩坑
  不知道前人为何这样选，推翻重来才发现当初的原因。
• 同一问题反复争论
  没有决策档案，不同时间被不同人反复讨论。

什么是架构决策记录

一份短文本，记录一个决策的来龙去脉。

ADR (Architecture Decision Record) 由 Michael Nygard 在 2011 年提出。它不是冗长文档，而是与代码同生命周期的短记录，纳入版本管理，随项目演进。

一条 ADR 的样子

CLI 工作流

# 1. 初始化 ADR 目录（自建首条记录）
adr init doc/architecture/decisions

# 2. 新建一条决策，自动编号 + 打开编辑器
adr new "Implement as Unix shell scripts"

# 3. 新决策取代旧决策（如取代 ADR 9）
adr new -s 9 "Use Rust for performance-critical functionality"
# ↑ 自动更新 ADR 9 状态为 Superseded，并互链

# 4. 查看帮助
adr help

生成的 Markdown 存于 doc/adr/，编号自增，支持决策间引用关系。

为什么是 Bash + Markdown

决策不是静态的

每条 ADR 有明确状态。新决策取代旧决策时，工具自动更新双方状态并建立链接，形成决策演化图谱。

适合谁用

• 重视技术沉淀的团队
  希望决策有据可查，避免重复争论与知识流失。
• 架构师 / Tech Lead
  需要向团队传递决策上下文与权衡过程。
• 开源项目维护者
  向贡献者解释"为什么这样设计"，降低贡献门槛。
• 遗留系统接手者
  理解前任架构选择的来龙去脉，避免误判。

需要知道的

• 价值在实践而非工具
  ADR-Tools 只是壳，真正价值是 ADR 文化。没人写就形同虚设。
• 需要团队纪律
  工具无法强制，得靠流程与文化养成习惯。
• 维护成本
  ADR 累积多了需定期整理，否则成为噪音。
• 仅 Unix
  纯 Bash 实现，Windows 需 WSL 或替代品（如 log4brains）。

ADR-Tools 的孩子们

作为奠基项目，它启发了大量多语言移植与增强工具。

未来空间

架构决策记录领域的奠基之作，价值稳定但不追求增长。它更像一种工程文化载体——工具可以换代（已有更现代的替代品），但 ADR 作为一种实践会长期存在。对个人，掌握 ADR 思维比用哪个工具更重要；对团队，引入 ADR 文化是提升决策质量的高杠杆动作。