目录

模板告诉 AI 在哪里写内容。要让架构决策记录(ADR)保持易读,就需要定义哪些内容应当记录、哪些内容应当放到其他地方,并让撰写者和审阅者使用同一套规则。

要点#

  • 在 ADR 中保留长期有效的决策,将任务进度、迁移时间表和常规实现细节移到其他地方。
  • 说明项目实际面临的问题,让读者无需回溯过去的讨论也能理解决策。
  • 从反复出现的审阅意见中提炼撰写规则,通过规则 ID 和示例明确修改要求。
  • 为 AI 撰写者和审阅者提供共同的指南,而不是各自独立的指令。

模板的局限#

TOKIUM 的产品团队已经有了 ADR 模板,包含“背景”“决策”“结果”以及可选的“考虑过的替代方案”,并在元数据中记录状态和日期。AI 填写了各个章节,但生成的记录往往并不便于审阅。

一份 ADR 包含迁移依赖关系图和一张 23 行的任务表。另一份 ADR 描述了将普通配置与机密信息一起存储的假设性风险,却没有写明项目已经在这样做。一份关于邮件安全的 ADR 则将长期有效的方针与方法名、环境变量语法、地址匹配细节混在一起。

这些文档包含有用的信息。问题在于放置的位置。读者需要从临时工作和实现步骤中辨别出决策,并补全缺失的背景。增加标题也无法解决这个问题。

划定决策的边界#

ADR 用于说明问题、选定的应对方式及其结果。即使实现发生变化、迁移已经结束,它也需要继续发挥作用。

审阅草稿时,可以使用以下四种边界。

| 保留在 ADR 中的内容 | 放在其他地方的内容 | |---|---| | 迁移期间必须满足的条件 | 任务负责人、截止日期和进度 | | 防止向未经许可的收件地址发送邮件的要求 | 环境变量名和解析语法 | | 项目当前存在的配置问题 | 不涉及实际情况的泛泛警告 | | 接受的权衡及其依据 | 详细的实现步骤 |

例如,“预发布环境的邮件只能发送到已批准的收件地址,未配置时禁止发送”表达的是长期有效的要求。逗号分隔的配置或统一转为小写,通常应记录在规格文档或实现记录中。

可以问自己:这项决策保持有效,而只有实现发生变化,这种情况是否可能出现? 如果可能,依赖具体实现的细节大概就应放到其他地方。不过,这仍需要判断。选择特定技术或协议本身,有时就是架构决策。即使进行抽象,也应保留这一选择,不能将其删去。

将审阅意见转化为规则#

TOKIUM 调查了 34 个修改 ADR 的 PR 和 830 条审阅意见,提炼出 32 条规则。这是一种实用的方法:从审阅中反复出现的问题出发,而不是凭空设想理想的文档。

在自己的仓库中,也可以收集近期 ADR 的审阅意见,对反复出现的修改进行分类。为每条规则添加固定 ID、要求级别和简短示例。MUST 仅用于必须满足的验收条件;对于允许合理例外的规则,使用 SHOULD。

最初可以从以下少量规则开始。

  • C-1、MUST: 通过代码或一手资料核实事实性描述。
  • C-3、MUST: 确保仅阅读 ADR 就能理解问题和决策。
  • D-1、MUST: 将迁移进度和任务表放在 ADR 之外。
  • D-4、SHOULD: 除非实现方式的选择本身就是决策,否则应保留实现的自由度。

对于需要判断的规则,附上实用的问题。例如 D-1,可以问这段文字是否会在任务完成后变得多余。正反示例都应使用虚构内容,以免将旧项目的决策误留在指南中。

统一规则来源#

将指南与 ADR 模板放在同一位置,确保开始撰写前可以查阅两者。将规则藏在审阅提示词中就太晚了,因为撰写者提交文档后才会知道这些规则的存在。

在 ADR 撰写流程和 AI 审阅流程中纳入同一份指南。如果工具支持按目录设置指令,可以用简短的引用指令,在编辑 ADR 文件时加载指南。避免将完整规则复制到多个提示词中,以免内容出现偏差。

要求审阅意见明确指出适用规则、存在问题的位置以及所需修改。“D-1:将这张进度表移到迁移计划中”,能让撰写者知道该做什么。“提高可读性”则不能。

确认依据和责任归属#

即使 ADR 格式完善,也可能依赖无人能够核实的依据。TOKIUM 报告称,AI 审阅指出了仅以线下会议为依据的决策,以及将工作交由仓库中并不存在的测试计划处理的问题。

接受 ADR 前,应确认其依据可以查阅,委派的工作有指向实际文档的引用或明确的负责人。尚未解决的决策应明确标记为未解决,而不是当作已确定的事项。

报告中的示例表明,共同规则可以让审阅意见更加具体。但这些示例既不是对审阅时间缩短的实测结果,也不能证明 AI 能判断架构质量。决策能否解决问题、成本是否可以接受,仍需要人来评估。

下一步#

回顾最近 5 个 ADR 的 PR,将最常见的修改整理为共同规则,并附上 ID、要求级别和虚构的修改前后示例。

来源: https://zenn.dev/tokium_dev/articles/adr-authoring-guideline

目录