ADR 编写器
使用清晰的上下文、备选方案和后果记录架构决策。请用英文书写。
ADR 模板
# ADR-[编号]: [简短的决策标题]
**状态:** [提议 | 已接受 | 已弃用 | 被 ADR-XXX 取代]
**日期:** [YYYY-MM-DD]
**作者:** [姓名/昵称]
## 1. 上下文
我们正在解决什么问题？哪些因素影响它（业务目标、技术债务、预算）？
**约束条件：**
- [约束条件 1]
- [约束条件 2]
## 2. 决策
决策的简短陈述。核心论点。
## 3. 技术细节与机制
_自由格式部分。描述实现细节、数据结构、协议细节或关键框架特性。_
- [列表、API 描述、数据模式]
- [Mermaid 可视化（推荐用于复杂交互）]
## 4. 备选方案
### 4.1. [选项 1]
- **优点：** ...
- **缺点：** ...
- **决策：** [已拒绝/已考虑] （简短原因）。
## 5. 后果与风险
### 积极（优点）
- 这对系统/团队有何帮助？
### 消极/风险（缺点/风险）
- 我们接受哪些缺点？风险是什么？
- **缓解措施：** 我们将如何应对风险？
## 6. 修订历史
- **[日期]**: [变更说明] ([作者])
- **[日期]**: [例如：状态改为已接受] ([作者])
ADR 编号
ADR-001: 初始系统架构
ADR-002: 分析数据库选型
ADR-003: 认证策略
...
状态工作流
提议 → 已接受 → 已实施
↓
已拒绝
已接受 → 已弃用 → 被 ADR-XXX 取代
最佳实践
- 为重大决策编写 ADR：并非每个选择都需要 ADR
- 记录备选方案：表明你已考虑过其他选项
- 坦诚面对权衡：每个决策都有缺点
- 保持简洁：最多 1-2 页
- 更新状态：标记已弃用/已被取代的 ADR
- 关联相关 ADR：创建决策轨迹
- 包含后续行动：带负责人的待办事项
- 可视化：使用 Mermaid 图表展示架构和流程
- 为未来的读者编写，他们缺乏当前上下文
- 坦诚对待权衡（每个选择都有缺点）
常见模式
对于技术选型：
- 聚焦技术能力与需求的匹配度
- 如有性能基准测试，请包含在内
- 记录团队的专业水平
- 考虑运维复杂性
对于架构变更：
- 在后果中包含迁移策略
- 记录向后兼容性影响
- 考虑过渡期间对团队速度的影响
- 标注监控和回滚计划
对于标准和规范：
- 包含标准在实际中的应用示例
- 记录例外或逃生舱口
- 考虑实施机制
- 标注教育/入职影响
对于弃用：
- 将状态设置为“已弃用”或“已被取代”
- 链接到取代的 ADR
- 记录日落时间线
- 包含迁移指南
反模式
❌ 过于详细：没人读的 10 页 ADR ❌ 无备选方案：看起来决策是预先确定的 ❌ 缺失后果：忽视缺点 ❌ 无负责人：无人负责 ❌ 状态过期：旧的 ADR 标注为“提议”
审查清单
- 上下文中清晰的问题陈述
- 决策明确陈述
- 考虑了 2 个以上的备选方案
- 诚实评估了权衡
- 记录了后果（积极和消极）
- 识别了风险并包含缓解措施
- 指定了决策负责人
- 后续行动包含截止日期
- 状态是最新的
输出清单
- ADR 文档已创建
- 上下文解释了问题
- 决策已明确陈述
- 记录了 2-3 个备选方案
- 权衡部分已填写
- 列出了后果（积极和消极）
- 识别了风险并包含缓解措施
- 决策日期和负责人
- 后续行动已分配
- 状态已设置