替代一条决策
在不破坏历史的前提下更改已接受架构决策的正确方式。
为什么
直接改旧 ADR 会抹掉当时成立的推理，未来的考古者无法理解架构为何长成这样。替代保留了原件作为历史文物，并加一条新 ADR 说明改了什么、为什么。这在事故复盘时很关键：根因常常是"我们改了 X 但没更新决策记录"，干净的替代链让这件事可见而非隐形。
何时使用
任何时候要推翻或大幅修改 Accepted 的决策。耗时 20 分钟。永远不要跳过——原地编辑是架构文档过时的头号原因。
如何做
1. 用下一个编号创建新 ADR（不要改旧的） 2. 在新 ADR 的 Context 里链接旧的："Supersedes ADR-0007" 3. 解释世界上发生了什么变化使旧决策不再成立 4. 写出新 Decision 及其 Consequences 5. 打开旧 ADR，只改 Status 行： "Status: Superseded by [ADR-0012]"——其余不动 6. 在同一个 PR 里提交两个文件，提交信息 "supersede ADR-0007 with ADR-0012"
示例
旧 ADR-0007（PostgreSQL）对事件路径太慢了。
新 ADR-0012：
- Status: Accepted
- Context: Supersedes ADR-0007。事件写路径到 5 万写/秒；
Postgres WAL 跟不上。事务计费存储仍留在 Postgres
（ADR-0007 对该范围仍有效）。
- Decision: **事件写入走 ClickHouse；计费仍用 Postgres。**
ADR-0007 更新：
- Status: Superseded by [ADR-0012]（仅事件路径；计费不变）常见问题
- ⚠替代时不解释世界上发生了什么变化——新 ADR 读起来像偏好，而非对新信息的回应。
- ⚠把旧 ADR 标成 'Deprecated' 而非 'Superseded by'——Deprecated 有歧义；显式链接才让链可导航。
最佳实践
- ✓精确界定替代范围——"仅事件路径"比笼统的"我们换掉了 Postgres"更有用。
- ✓在新 ADR 顶部加一行 TL;DR，让略读者不读全文也能抓住变化。
- ✓如果一条决策被替代超过两次，安排架构评审——反复变动说明地基不稳。