决策文档
写 ADR 使未来工程师（或 6 月后的你）能理解决了什么及为何。
为什么
说"我们选 Postgres"的 ADR 无用——6 月后有人问"为何不 DynamoDB？"理由没了。说"我们选 Postgres 因需 join+事务、DynamoDB 被拒因访问模式关系、考虑了 MySQL 但团队会 Postgres"的 ADR 永远有用。决策文档是捕决策时的上下文、备选和理由，使决策可审计、可理、上下文变时可被新 ADR 取代。无它每决策从头重审因无人知为何做 。
何时使用
每中+决策、决策时。30-60 分钟写。永不回溯——记忆腐烂。
如何做
1. 用 ADR 模板（Nygard 格式）： # ADR-NNN：标题 ## 状态：提议 | 已接受 | 被 ADR-MMM 取代 ## 上下文：问题、力、约束 ## 决策：决定了什么 ## 后果：正+负+中 ## 考虑备选：还有什么+为何拒 2. 先写上下文——它腐烂最快；捕问题+约束 3. 备选具体："DynamoDB：拒因访问模式需 join"非"DynamoDB：不适" 4. 记你接受的后果（所做权衡）非仅益 5. 若用 decision-criteria 链标准+分 6. 顺序编号；取代非编辑——决策变时写 ADR-MMM 取代 NNN 7. ADR 存仓库 /docs/adr/ 非 wiki——与代码版本
示例
# ADR-015：订单服务用 Postgres ## 状态：已接受（2024-03-12） ## 上下文 订单服务需存订单+行项带 ACID 事务 （超卖是法律问题）。访问模式：按 id 取、按用户+日期列、 按月聚合。团队会 Postgres、不会 DynamoDB。 ## 决策 用 Postgres（RDS 托管、db.r6g.large）。 ## 后果 + join+事务免费 + 团队能运维（ 现有专长） − 垂直扩展限（缓解：列表查询读副本） − 单区域（接受：订单本就区域） ## 备选 - DynamoDB：拒——访问模式关系（join）非 KV - MySQL：拒——团队专长 Postgres、此处无 MySQL 优势 - MongoDB：拒——事务更弱、访问模式关系
常见问题
- ⚠编辑已接受 ADR——历史丢；用新 ADR 取代引旧的，使演进可追。
最佳实践
- ✓写上下文节如读者不在——6 月后无人记驱决策的力。
- ✓ADR 保持短（1-2 页）——更长则决策太大；分解为多 ADR。