一份记录，一个决策
ADR 只回答一个问题：基于当时所知，我们为什么这样选？它刻意简短，通常一页，放在受该决策约束的代码旁边。一个需要十页的决策，往往是多个应当分别记录的决策，每个都有自己的状态。
一份好记录包含什么
背景描述各种作用力，而不是解决方案。决策用一两句话说明选了什么。后果列出什么变容易了、什么变难了、什么已经难以逆转。备选方案也应写入，因为被否决的选项恰恰是后来者最想了解的。
# 0012 Queue-based order processing
Status: accepted (2026-09-14)
Context: checkout latency spikes when the warehouse API is slow.
Decision: publish order events to a queue; consumers retry independently.
Consequences: checkout no longer blocks; duplicates must be handled downstream.
Alternatives: synchronous retries (rejected: latency), circuit breaker only (rejected: drops orders).生命周期与取代
记录从提议走向接受，之后变为被取代或废弃。不要为了表达新观点去修改已接受的记录，而应新写一份并引用旧记录。这段历史正是价值所在：它显示假设何时改变、因何改变，往往比任何单个决策都更有信息量。
记录放在哪里
把 ADR 放在受影响的仓库中，并用 README 建立索引。跨团队决策可以另存中央档案，但代码旁的副本应是权威版本。新记录应与变更放在同一个 PR 里评审，让决策与实现一同落地。
与设计文档的对比
设计文档在方案尚不存在时完整描述它；ADR 在权衡之后记录一项承诺。设计文档很快过期，ADR 则因为只描述某个时刻及其推理而长期为真。团队两者都需要，但只有一种能在二十分钟内写完。