ADR-{NNN} ·
AI 生成 · 待 owner review
本文档由 DocAgent 自动生成,status: draft。owner 工程师 / 架构师 review 通过后请把 status 改为 published,并删除 frontmatter 中的 generated_by 字段。
TL;DR
- 决策:{一句话结论}
- 状态:Proposed / Accepted / Deprecated / Superseded by ADR-{NNN}
- 日期:YYYY-MM-DD
- 决策者:{角色或姓名}
1. 背景(Context)
{2-5 段描述问题的来龙去脉:业务背景 / 技术约束 / 当前痛点。说明"为什么需要做这个决策"。}
2. 决策驱动力(Drivers)
- {驱动力 1:如"端到端延迟必须 < 20ms"}
- {驱动力 2:如"必须兼容现有 P3 硬件"}
- {驱动力 3:如"团队 C# 经验远多于 Rust"}
3. 候选方案(Options Considered)
方案 A ·
做法:{1-3 句描述}
优点: - {优点 1} - {优点 2}
缺点: - {缺点 1} - {缺点 2}
方案 B ·
(同上结构)
方案 C ·
(同上结构)
4. 对比矩阵
| 维度 | 方案 A | 方案 B | 方案 C | 权重 |
|---|---|---|---|---|
| 性能 | ⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐⭐ | 高 |
| 实现成本 | ⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐ | 高 |
| 可维护性 | ⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐ | 中 |
| 团队熟悉度 | ⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐ | 中 |
| 总分 | 14 | 11 | 9 | — |
5. 决策(Decision)
决策
采用 方案 A,理由:{核心权衡的 1-3 句说明}。
6. 后果(Consequences)
6.1 正面后果
- {正面 1}
- {正面 2}
6.2 负面后果
- {负面 1}
- {负面 2}
6.3 风险与缓解
| 风险 | 概率 | 影响 | 缓解措施 |
|---|---|---|---|
| {风险 1} | 中 | 高 | {措施} |
| {风险 2} | 低 | 中 | {措施} |
7. 实施计划(Implementation)
gantt
title ADR-{NNN} 实施甘特
dateFormat YYYY-MM-DD
section Phase 1
需求确认 :a1, YYYY-MM-DD, 7d
技术预研 :a2, after a1, 14d
section Phase 2
核心实现 :b1, after a2, 21d
单元测试 :b2, after a2, 14d
section Phase 3
集成验证 :c1, after b1, 14d
上线灰度 :c2, after c1, 7d8. 验收标准
- 性能指标:{具体数值}
- 覆盖率:单元测试 ≥ 80%
- 文档:D3 架构文档同步更新
- mkdocs build 0 ERROR
9. 相关 ADR / 文档
- ADR-{XXX} — {关联说明}
- D3 架构:{相关架构文档}
- 实现:{对应 API/Spec 文档}
10. Changelog
| 版本 | 日期 | 改动 |
|---|---|---|
| 0.1.0 | YYYY-MM-DD | 首版 Proposed(DocAgent 生成) |
模板使用说明(DocAgent 内部参考,生成正式文档时删除本节): 1. ADR 编号
{NNN}在08-implementation/{stack}/adr/目录下顺序递增,跑ls找最大编号 +1 2. 候选方案至少 2 个(只列 1 个无意义),推荐 3 个 3. 对比矩阵的"权重"列用于明确哪些维度是"硬约束" 4. 决策一旦status: published后不允许修改,要变更必须新写 ADR 并把旧 ADR 标Superseded by ADR-{NNN}