Agent开发系列（十二）-知识库建设（ADR）

一、什么是ADR？

ADR（Architecture Decision Record，即架构决策记录）。研发团队里特指"记录一次重要架构决策的短文档"。

它是什么	它不是什么
重要架构决策的"决策书"(过去时)	架构总览(那是"现在是什么")
记录"为什么选 A 不选 B"	会议纪要(那是过程)
防止"重复讨论 + 推翻重做"	产品决策(那是 PRD/Roadmap)
写一次、状态变更、几乎不改内容	实施细节(那是 PR/Commit)

# ADR-0001: 选 PostgreSQL 不用 MySQL

## 状态
Accepted

## 背景
- MySQL 5.7 已运行 5 年,数据量 3TB
- 性能瓶颈 + EOL 合规压力
- 需要 JSONB、窗口函数、并行查询

## 考虑的选项
1. MySQL 8.0(升级)
2. PostgreSQL 16(迁移)
3. TiDB(HTAP)

## 决策
选 PostgreSQL 16。
- 否决 MySQL 8:JSON 弱,无法解决 3TB JOIN
- 否决 TiDB:运维成本高,收益不明确

## 后果
- 正面:JSON 性能 +5x
- 负面:迁移需 6 周
- 后续:6 个月后 review

二、ADR的知识模板如何定义？

2.1 知识模板

分类	字段	类型	必填	备注
基础	编号	string	✓	全局唯一,如 0001
基础	标题	string	✓	动词开头,一句话
基础	状态	enum	✓	Proposed/Accepted/Rejected/Deprecated/Superseded
基础	创建日期	date	✓
基础	决策日期	date	×	状态变 Accepted 时填
基础	作者	@user	✓	草稿作者
基础	决策参与者	list[@user]	✓	参与讨论的人
基础	关联服务/系统	list[link]	×
核心	背景	markdown	✓	【核心】面临什么问题,为什么现在要决策,有什么约束
核心	选项	list(≥2)	✓	【核心】至少 2 个,通常 3-4 个,每个有名称
核心	决策	markdown	✓	【核心】选了什么,理由是什么
核心	后果	markdown	✓	【核心】正面 / 负面影响,后续工作
关联	superseded by	ADR 编号	×	状态为 Superseded 时填
关联	关联代码路径	list[link]	×	实施该 ADR 的代码
关联	关联 Runbook	list[link]	×	涉及运维的填
关联	关联事故档案	list[link]	×	事故触发的 ADR 填

案例如下：

# ADR-0001: 选 PostgreSQL 不用 MySQL

## 状态
Accepted

## 背景
- 当前订单数据存储在 MySQL 5.7,已运行 5 年
- 数据量增长到 3TB,MySQL 大表 JOIN 性能瓶颈
- 团队对 MySQL 5.7 EOL(2023-10)有合规压力
- 业务需要 JSONB、窗口函数、并行查询

## 考虑的选项
1. **MySQL 8.0**:升级现有 MySQL,无数据迁移
2. **PostgreSQL 16**:迁移到 PG,功能强,生态成熟
3. **TiDB**:HTAP 方案,水平扩展

## 决策
**选 PostgreSQL 16**。
理由:JSONB/窗口函数原生支持、并行查询、社区活跃度高于 MySQL 8、
团队已有 PG 经验(3 人)。
**否决 MySQL 8**:JSON 函数能力弱、并行查询有限、升级无法解决 3TB JOIN 瓶颈。
**否决 TiDB**:运维成本高、HTAP 收益对当前业务不明确。

## 后果
- **正面**:JSON 字段查询性能 +5x,大表 JOIN +3x
- **正面**:为后续架构演进(多租户、地理分布)提供更好基础
- **负面**:数据迁移需 6 周,需 0.5 FTE 专注
- **负面**:MySQL 时代的运维经验部分失效
- **后续**:运行 6 个月后 review,看是否需要回退
- **关联**: [迁移项目 #PRJ-2031]

三、ADR的更新机制如何设计？

触发器	触发条件	动作	责任方
PR-ingest	PR 实施 ADR 决策	自动关联 ADR 编号到 PR	LLM
Lint 反查	代码偏离 ADR	告警 + 提醒更新状态	自动
手动状态变更	重大事件(事故/技术演进)触发	走 PR 改状态	决策参与者
定期 review	每年/每季度复查	检查"过期的 ADR"	架构师

3.1 关键设计点

设计点	具体要求
状态变更走 PR	决策变更要可追溯,不是直接改
Superseded 必须有链接	superseded by: ADR-0015,可追溯链条
被 Superseded 的 ADR 不删除	历史背景常被翻账
Lint 强制:Accepted 状态 ADR 跟代码一致	不一致就告警,推动状态变更
状态变更要 review	至少 2 个决策参与者 approve
Accepted 后,正文几乎不修改	决策的"过去时"是稳定的

3.2 反模式

反模式	后果
直接修改 ADR 正文(改"决策")	历史丢失,无法知道"当时怎么想的"
状态不写,默认都是 Accepted	看不到哪些在讨论、哪些被否决
Superseded 写"已被新方案替代"不写编号	追溯链断裂
删除 Rejected 的 ADR	未来重新讨论时,前人踩过的坑看不见
状态变更不通知关联方	实施 ADR 的人不知道决策已变

四、ADR的质量标准如何定义？

核心判断：ADR 的"质量"= 决策可追溯 + 跟代码一致 + 状态正确。不是"文档漂不漂亮"。

指标	定义	健康值	测量方式
覆盖率	重大决策有 ADR 的比例	100%	抽查
一致性	代码与 ADR 描述一致	≥ 95%	Lint
可追溯	决策变更链条完整无断裂	100%	自动
被引用率	ADR 被代码/Runbook/wiki 引用的比例	≥ 80%	链接统计
状态正确性	ADR 状态与现实一致	≥ 95%	季度 review

4.1 3个反向指标(出现就告警)

反向指标	告警触发	修复动作
裸奔决策	重大代码变更(选型/架构)无对应 ADR	立即告警,要求补 ADR
失信 ADR	代码严重偏离 ADR 决策	立即告警,要求更新状态或同步代码
僵尸 ADR	状态长期不更新,引用链断裂	季度 review 列出,要求清理

4.2 3个质量门槛

门槛	触发	动作
准入门槛(发布前)	必填字段完整 + 至少 2 个选项 + 决策明确 + 至少 2 个决策参与者	缺一不准合并
持续门槛(运行中)	ADR 跟代码一致 + 状态正确 + 至少被 1 处引用	否则季度 review 标 stale
淘汰门槛	永不删除,只 Superseded	归档到 superseded/ 目录