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

一、什么是ADRADRArchitecture 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 byADR 编号×状态为 Superseded 时填关联关联代码路径list[link]×实施该 ADR 的代码关联关联 Runbooklist[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-ingestPR 实施 ADR 决策自动关联 ADR 编号到 PRLLMLint 反查代码偏离 ADR告警 提醒更新状态自动手动状态变更重大事件(事故/技术演进)触发走 PR 改状态决策参与者定期 review每年/每季度复查检查过期的 ADR架构师3.1 关键设计点设计点具体要求状态变更走 PR决策变更要可追溯,不是直接改Superseded 必须有链接superseded by: ADR-0015,可追溯链条被 Superseded 的 ADR 不删除历史背景常被翻账Lint 强制:Accepted 状态 ADR 跟代码一致不一致就告警,推动状态变更状态变更要 review至少 2 个决策参与者 approveAccepted 后,正文几乎不修改决策的过去时是稳定的3.2 反模式反模式后果直接修改 ADR 正文(改决策)历史丢失,无法知道当时怎么想的状态不写,默认都是 Accepted看不到哪些在讨论、哪些被否决Superseded 写已被新方案替代不写编号追溯链断裂删除 Rejected 的 ADR未来重新讨论时,前人踩过的坑看不见状态变更不通知关联方实施 ADR 的人不知道决策已变四、ADR的质量标准如何定义核心判断ADR 的质量 决策可追溯 跟代码一致 状态正确。不是文档漂不漂亮。指标定义健康值测量方式覆盖率重大决策有 ADR 的比例100%抽查一致性代码与 ADR 描述一致≥ 95%Lint可追溯决策变更链条完整无断裂100%自动被引用率ADR 被代码/Runbook/wiki 引用的比例≥ 80%链接统计状态正确性ADR 状态与现实一致≥ 95%季度 review4.1 3个反向指标(出现就告警)反向指标告警触发修复动作裸奔决策重大代码变更(选型/架构)无对应 ADR立即告警,要求补 ADR失信 ADR代码严重偏离 ADR 决策立即告警,要求更新状态或同步代码僵尸 ADR状态长期不更新,引用链断裂季度 review 列出,要求清理4.2 3个质量门槛门槛触发动作准入门槛(发布前)必填字段完整 至少 2 个选项 决策明确 至少 2 个决策参与者缺一不准合并持续门槛(运行中)ADR 跟代码一致 状态正确 至少被 1 处引用否则季度 review 标 stale淘汰门槛永不删除,只 Superseded归档到superseded/目录