用ADR记录架构决策：别再凭感觉做选择（Awesome Architecture第08章实战指南）

【免费下载链接】awesome-architecture🧭 Architecture-first system design: 26 bilingual tutorials, 25 architecture templates, and 6 end-to-end cases covering distributed systems, AI-native systems, RAG, coding Agents, and production trade-offs.项目地址: https://gitcode.com/gh_mirrors/awesomearc/awesome-architecture

在架构设计中，最容易被遗忘的不是"选了什么技术"，而是"当初为什么这么选"。ADR（Architecture Decision Record，架构决策记录）就是解决这个问题的轻量文档：每个重要架构决策写一页纸，把背景、决策、放弃的选项和取舍记下来，随代码一起版本管理。本文基于开源项目 Awesome Architecture 的第 08 章 tutorial/08-架构决策记录与演进.md，用实战视角带你掌握 ADR 的写法、原则和落地技巧。

为什么"凭感觉做选择"最危险？

想象一个真实场景：你接手一个三年前的系统，发现订单数据被写进两个存储，中间还有对账逻辑。第一反应是"这不脱裤子放屁吗？"，于是删掉一个、合并逻辑——三周后线上炸了。

原因很简单：当年之所以双写，是因为监管要求订单流水必须落入不可篡改的存储，而主库要支持高频改单，两个诉求无法用一个存储同时满足。这个理由，代码里一个字都没写，拍板的人也早离职了。

💡架构最致命的信息流失：代码和图能说清系统"是什么"，但几乎永远讲不清"为什么这么选、当初放弃了什么"。

会议里讲过的原因，会在三次会议、两次离职、一年时间之后蒸发得一干二净。等需要它的时候，只剩下一个看起来莫名其妙的设计，和一群不敢动它的人。

ADR 是什么：给架构决策建一本"为什么"的账

ADR = Architecture Decision Record，架构决策记录。它是一份轻量文档，精髓在于足够轻：

ADR 由 Michael Nygard 在 2011 年提出，用一个个轻量小文件记录每个决策的背景、决定、状态和后果，如今已是业界标准格式。

六块模板：一份可以直接抄走的 ADR 格式

第 08 章给出了一个"订单流水双写"的完整 ADR 范例，模板就六块，记牢这六个标题就够了：

┌──────────────────────────────────────────────────────────┐ │ ADR-007:订单流水采用「主库 + 不可篡改日志」双写 │ ├──────────────────────────────────────────────────────────┤ │ 状态:已采纳（草稿 / 已采纳 / 已废弃 / 被 ADR-015 取代） │ │ 日期:2026-05-23 决策者:架构组 + 合规 │ │ │ │ 背景:监管要求订单流水落入「写后不可改」的存储; │ │ 业务又要求订单可被高频修改。单一存储无法两全。 │ │ │ │ 决策:主库存可变订单状态;每次变更追加写入不可篡改日志; │ │ 以日志为准定期对账。 │ │ │ │ 其它选项:A. 软删除 → 否决(仍可被改,过不了审计) │ │ B. 只用不可篡改存储 → 否决(无法改单) │ │ C. 双写(本方案) → 采纳 │ │ │ │ 取舍:+ 同时满足合规与业务两个硬约束 │ │ − 需要对账逻辑兜底不一致(已知复杂度) │ └──────────────────────────────────────────────────────────┘

一句话立住原则：好的文档不重复解释代码做了什么（代码自己会说），好的文档解释代码为什么这么做（代码永远不会说）。

技术债也要记账：有意识的债不是坏事

技术债常被当成纯贬义词，其实它借自金融含义：为了现在更快地拿到价值，有意识地选了个将来需要偿还的权宜方案。关键不是欠没欠，而是知不知道、记没记、还还不还。

处理技术债的纪律就三条：

1. ✅有意识地借——明确这是权宜之计；
2. ✅记下来——一笔技术债就是一条该写的 ADR，背景说明为什么暂时这样做；
3. ✅安排偿还时机——挂进 backlog，定下"当 X 发生时就还"的触发条件，而不是"有空再说"。

何时该升级架构：用尺子判断，不拍脑袋

凭"代码看着丑"或"大厂都上微服务了"升级架构，是两种糟糕的依据。正确的做法是拿两把尺子量：

• 尺子一：瓶颈——某个质量属性是不是已被架构真实卡住（读库冒烟、发布越来越慢）？
• 尺子二：质量属性的变化——业务对"要多好"的要求是否上了台阶（可用性 99% → 99.99%、用户量进下一个量级）？

🎯不是架构旧了就升级，而是某个你真正在乎的质量属性被量出来的真实瓶颈卡住了，才升级。而且每次升级本身就是一个该写 ADR 的重大决策。

tutorial/演进触发信号.md 把这些判断落成可观测的量化信号速查表（主库 CPU、P99 延迟、缓存命中率等），"没有信号，就别动"。

实战练习：把模板当 ADR 读

Awesome Architecture 仓库里有个绝佳的练习场：templates/ 下每个模板的第 8 节"关键架构决策与权衡"，本质就是一组写好的 ADR。

建议路径：

• 先读 tutorial/20-演进剧本MVP到规模化.md——同一个 AI 客服系统三段演进，每段升级都落了一条 ADR（ADR-001 到 ADR-005），背景栏全是量化信号，没有一句"感觉该升级了"；
• 再挑 templates/ai-chat-product/README.md 里"流式还是一次性返回"这条决策，按六块模板亲手补成一份完整 ADR；
• 最后回到 tutorial/README.md 的完整学习路径，把 07 章"设计"与 08 章"记录"串成闭环。

本章小结

• 📌 最先丢失的永远是"为什么"——代码能自我证明"是什么"，却永远不会说出当初放弃了什么；
• 📌 ADR 六块模板：标题、状态、背景、决策、其它选项、取舍与后果，一页纸即可；
• 📌 追加不修改，保留历史本身就是宝贵信息；
• 📌 技术债的纪律：有意识地借、记成 ADR、排期偿还；
• 📌 升级架构靠"瓶颈 + 质量属性变化"两把尺子，每次升级本身就写一条 ADR。

做出一个架构判断 → 把"为什么"记成 ADR → 业务长大、出现新瓶颈 → 重新判断……这个循环，会让判断力复利增长。别再凭感觉做选择——把决策写下来，才是架构师的分水岭。

【免费下载链接】awesome-architecture🧭 Architecture-first system design: 26 bilingual tutorials, 25 architecture templates, and 6 end-to-end cases covering distributed systems, AI-native systems, RAG, coding Agents, and production trade-offs.项目地址: https://gitcode.com/gh_mirrors/awesomearc/awesome-architecture