ADR-Tools

架构决策记录（ADR）命令行工具

更新于 2026-07-07

一句话定位

架构决策记录（ADR）命令行工具

轻量 Bash CLI，把架构决策记录成 Markdown 并纳入版本管理。源自 Michael Nygard 2011 年 ADR 文章，是该领域的奠基工具。适合重视技术决策沉淀、希望决策有据可查的团队和个人。

技术决策为什么会丢失

• 口头决策无记录：架构选型在会议里定，会散即忘
• 只留结论不留理由：代码能看出"做了什么"，看不出"为什么"
• 新人反复踩坑：不知道前人为何这样选，推翻重来才发现原因
• 重复讨论：同一问题在不同时间被反复争论

什么是 ADR

Architecture Decision Record。

一份简短文本，记录一个架构决策的背景、决策、后果。与代码同生命周期，纳入版本管理。

CLI 工作流

# 新建一条 ADR
adr new "使用 PostgreSQL 替代 MySQL"

# 列出所有决策
adr list

# 链接决策（supersede/links）
adr link -superseds 7 12

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

适合谁用

• 重视技术沉淀的团队：希望决策有据可查、可追溯
• 架构师/Tech Lead：需要向团队传递决策上下文
• 开源项目维护者：向贡献者解释"为什么这样设计"

注意事项

• 工具本身简单：价值在于 ADR 实践，而非工具复杂度
• 需要团队纪律：没人写就形同虚设，工具无法强制
• 维护成本：ADR 过多需要定期整理，否则成为噪音

未来空间

架构决策记录领域的经典工具，价值稳定但增长有限。更适合作为团队工程文化的一部分长期使用，而非追逐热点项目。