使用 GIG Cymru NHS Wales 决策记录模板:以 Options → Options Analysis → Recommendation 叙事流编写严谨的 ADR
使用 GIG Cymru NHS Wales 决策记录模板:以 Options → Options Analysis → Recommendation 叙事流编写严谨的 ADR
导读
本文讲解 architecture-decision-record 开源仓库收录的 Decision record template by GIG Cymru NHS Wales,它是一套"候选方案 → 方案分析 → 最终建议"三段式叙事的架构决策记录(ADR)模板。你将学会用 Status 状态机管理决策生命周期,用 Drivers 明确决策动机,用 Options 与 Options Analysis 做结构化方案权衡,并用 Recommendation、Consequences、Confirmation 把决策落到可执行、可验证的闭环;同时结合仓库内的示例与技能文档,掌握把该模板实际用进团队日常开发流程的方法。
一、模板概览:它解决什么问题
GIG Cymru NHS Wales(威尔士 NHS 数字健康服务)的决策记录模板是一份结构完整、面向多方案比较型决策的 ADR 骨架。与 Michael Nygard 的极简模板(Title / Status / Context / Decision / Consequences)相比,它最大的特点是把"想清楚再决定"的过程显式地写进文档:先列出所有候选方案,再逐一对每个方案做 Pro/Con/Other 评估,最后才给出明确推荐。
仓库自带的 Claude Code 技能文档 SKILL.md 对这套模板的定位是一句话概括:"Options → Options Analysis → Recommendation" 叙事流("Want an 'Options → Options Analysis → Recommendation' narrative flow")。换言之,当你的决策不是"二选一"而是"多选一"、且每个选项各有明显取舍时,这套模板比 Nygard 模板更适合——它强迫作者把备选方案和权衡过程记录下来,让后来者不仅知道"选了什么",更知道"为什么没选别的"。
模板完整骨架(原文):
# {Your Title Here}
!!! info
**Status**: { Proposed | Under Review | Accepted | Rejected | Superseded | Deprecated }
**Updated**: {YYYY-MM-DD}
## Summary
## Drivers
## Options
### {Option 1 Title}
### {Option n Title}
## Options Analysis
### {Option 1 Assessment}
### {Option n Assessment}
## Recommendation
### Consequences (可选)
### Confirmation (可选)
## More Information (可选)
模板正文中的所有占位符均为花括号 { },填写时整体替换为真实内容,并删除说明性注释。
二、文档头:Status 状态机与 Updated 时间戳
模板开头是一个信息块(!!! info),包含两个关键元数据:
**Status**: { Proposed | Under Review | Accepted | Rejected | Superseded | Deprecated }
**Updated**: {YYYY-MM-DD}
- Status(决策状态) 是六选一的枚举:
Proposed(提议)、Under Review(评审中)、Accepted(已接受)、Rejected(已拒绝)、Superseded(已被取代)、Deprecated(已废弃)。它让任何人扫一眼就能判断这份 ADR 当前处于生命周期的哪个阶段。 - Updated(更新时间) 要求使用 ISO 8601 日期格式
YYYY-MM-DD,记录最近一次修改日期。
仓库的协作建议文档 teamwork-questions-for-adrs 提出了 ADR 生命周期的五阶段模型:Initiating → Researching → Evaluating → Implementing → Maintaining → Sunsetting,并建议每个阶段设定推进标准(如"研究完成、评估完成、向干系人发布一周评论期、所有评论已纳入")。你可以把模板的 Status 枚举映射到这套生命周期:Proposed 对应 Initiating/Researching,Under Review 对应 Evaluating,Accepted 对应 Implementing/Maintaining,Rejected/Deprecated/Superseded 对应 Sunsetting 或后续取代关系。
补充约定:当一份新 ADR 取代旧 ADR 时,应在旧文档的 Status 中标注 Superseded by <新 ADR 链接>,并在新文档中反向链接 Supersedes <旧 ADR 链接>(见 SKILL.md 第 6 节)。仓库写作建议 suggestions-for-writing-good-adrs 还强调 ADR 的 immutable(不可变) 原则:不修改已有信息,而是追加新信息或用新 ADR 取代旧 ADR。
三、Summary:决策的电梯演讲
模板对 Summary 的定位是"executive summary / elevator pitch",即一份技术论文的摘要或引言:
用 2~4 句简洁的话,清楚说明这份 ADR 要解决的核心问题、问题或机会,并对最终决定或关注领域给出暗示。目标是让读者快速理解这份 ADR 讲的是什么、是否与自己相关,无需通读全文。
写作要点:
- 直接点题:第一句就说出核心问题(例如"我们的新应用需要选择一种可水平扩展的数据存储技术")。
- 给出方向:中间一句暗示决策倾向(例如"经过评估,文档数据库最符合我们的灵活建模与横向扩展需求")。
- 控制长度:严格控制在 2~4 句,避免变成正文的浓缩版。
参考仓库真实示例,如 choosing-a-database-technology 的做法:先交代"正在设计一个需要可扩展、高性能存储检索的新应用",再说明"已识别关系型、文档型、事件型三类常见数据库",最后给出"决定使用文档数据库"——三段话即完成 Summary 的使命。
四、Drivers:回答"为什么是现在做这个决定"
Drivers 章节解释为什么这个决定必须现在做,模板原文给出的引导是:
清楚阐明促成这项架构决策的首要动机、需求或问题。思考背后的根本原因和压力。
模板提供了四类典型的 driver 示例,可直接套用:
- {e.g. We are developing a new feature/capability that needs...} → 新功能/新能力的需求
- {e.g. We need to improve performance, accessibility, remove debt...} → 性能、可访问性、技术债的改进诉求
- {e.g. Feedback from users suggests...} → 来自用户的反馈
- {e.g. The current approach imposes these limitations...} → 现有方案的限制
写作技巧:Drivers 是后续 Options Analysis 和 Recommendation 的评分标尺。每个 driver 应写得足够具体,使其可以在分析章节被"回引"(模板原文明确要求分析时要 relate your points back to the *Drivers*)。例如仓库示例 snake-case-v-camelcase-for-a-rest-api 列出的决策驱动是:
- 与项目现有命名约定保持一致
- 对 API 开发者的可读性与清晰度
- 与 REST API 命名行业最佳实践对齐
- 实现与维护的容易程度
这四个 driver 在后续 Decision 章节被一一对应展开,形成"驱动 → 论证 → 结论"的闭环。写 Drivers 时可以参考 suggestions-for-writing-good-adrs 的"Rationale"要求:说明组织的处境和业务优先级,纳入团队构成与技能组合的考量。
五、Options:列出所有认真考虑过的候选方案
Options 章节要求只陈述事实、不掺入观点(模板原文:"Stick to the facts and avoid opinions, the next section covers the analysis"),并强调:
包括所有你认真探索过的重要备选方案,即使它们最终没有被选中。目标是在进入评估之前,让读者对每个备选方案有清晰、不带偏见的理解。
每个选项使用 H3 子标题组织:
### {Option 1 Title}
{Describe the option, provide a summary, list the facts, provide links etc.}
写法要点:
- 每个选项一节,标题用简短名词短语(如"关系型数据库 MySQL"、"文档数据库 MongoDB")。
- 内容给出:方案描述、关键事实、相关文档或示例链接。
- 不要在此处写优点缺点——那属于 Options Analysis 章节。
以仓库示例 choosing-a-database-technology 为例,它先中立地描述了三类数据库的形态:关系型数据库以固定 schema 的表存储并强制数据完整性约束;文档数据库以类 JSON 文档、无 schema 方式存储并擅长横向扩展;事件数据库以事件流记录每次变更,适合审计与事件溯源。这就是"列事实"的示范——优劣评价全部留到后文。
六、Options Analysis:逐方案做 Pro / Con / Other 权衡
这是本模板区别于简单 ADR 的核心章节。模板要求对 Options 中的每个方案进行平衡的评估,并给出六个可参考的评估维度:
- Cost:开发成本、运维成本、许可成本
- Complexity:实现复杂度、维护复杂度、学习曲线
- Risks:技术风险、运维风险、安全风险
- Alignment:与架构原则或现有标准的对齐程度
- Impact:对性能、可扩展性、可用性、可维护性、安全性等的影响
每个选项的小节统一用三种陈述组织:
### {Option 1 Assessment}
* Pro: {A specific advantage or benefit of this option.}
* Con: {A specific disadvantage, risk, or cost associated with this option.}
* Other: {A relevant point that isn't strictly a pro or con.}
- Pro:该选项的具体优势或收益。
- Con:该选项伴随的具体劣势、风险或成本。
- Other:既不算优点也不算缺点的相关事实(例如许可模式、社区规模、迁移工作量等中性信息)。
模板同时要求"尽可能把每个论点回引到 Drivers 章节"("Be specific and, where possible, relate your points back to the Drivers"),让权衡有据可依,而不是泛泛而谈。仓库示例 continuous-integration 展示了这种正反两面写法:正面是质量与交付提升、自动化节省时间成本、团队协作增强;负面是实施初期成本、人员/工具/流程的前期投入、实施阶段技术困难的风险——并在 Conclusion 中明确"收益大于成本与风险"的权衡结论。
七、Recommendation:明确指名被选方案并给出理由
Recommendation 章节是决策的"落锤"之处,模板要求:
清楚陈述最终决定,并明确点出被选中的选项。详细解释为什么选择它,清楚说明该选项如何最好地回应 Drivers、满足关键需求或解决所述问题。
写法要点:
- 指名道姓:直接写出被选方案名称(如"我们决定采用文档数据库 MongoDB"),不用模糊表述。
- 回扣 Drivers:逐条说明该选项如何满足前面列出的每个驱动因素。
- 给出论证链:结论必须能从 Options Analysis 的 Pro/Con 中推导出来。
仓库示例 python-programming-language 的 Rationale 部分即示范了这种写法:针对"数据科学、机器学习、Web 开发"的项目需求,逐条论证 Python 的库生态(NumPy、Pandas、Scikit-learn)、社区支持、可扩展性、灵活性如何满足需求,再在 Consequences 中诚实列出性能、学习曲线、版本兼容性三个代价,最后得出"利大于弊"的结论。
Consequences(可选):接受决策带来的后果
模板把 Consequences 标记为可选,但强烈建议填写。它要求回答:
- 决策后预期会产生哪些正面与负面影响?
- 接受了哪些已知限制、成本或风险?
- 该决策如何影响不同干系人、其他系统、开发实践、运维流程或用户体验?
同样使用 Pro / Con / Other 三点式组织:
* Pro: {A specific positive outcome or benefit expected from this decision.}
* Con: {A specific accepted downside, cost, or risk resulting from this decision.}
* Other: {A consequence that isn't strictly a pro or con.}
仓库写作建议 suggestions-for-writing-good-adrs 对 Consequences 有更细的指导:说明决策带来的影响、结果、后续产出;记录由此触发的后续 ADR(一个大的总体决策常常会衍生出多个更小的决策,比较常见);包含事后复盘流程(如团队在决策一个月后对照实际实践复盘学习)。
Confirmation(可选):验证决策落地并维持合规
Confirmation 是这套模板非常实用的一节——它把决策从"纸面"推进到"被持续执行"。模板给出了四个自检问题:
- 如何检查决策被正确实现?(例如代码评审、特定测试、演示、同行评审)
- 如何长期维持对决策的遵从?(例如自动化检查、定期审计、更新团队指南、培训)
- 有哪些指标或信号表明决策达成了预期正面效果?(例如性能基准、采用率、特定错误减少、用户反馈评分)
- 谁负责监督此事?决策未被遵循时会发生什么?
回答这些问题时,可以借鉴仓库 fitness-functions-for-decisions-as-code 的思路:用自动化"适应度函数"把决策变成可测试、可验证的规则——"决策记录文档化决策,适应度函数保障决策"。例如决策是"采用事件溯源满足审计需求",对应的适应度函数就是"在 CI 服务器上测试所有状态变更都必须产生事件"。
八、More Information(可选):补充背景与未来线索
模板对 More Information 的使用建议:
提供任何支撑决策的补充信息、背景或对未来行动的指引。其他决策与资源的链接可以放在这里。可以简要记录参与决策的人员以及共识是如何达成的;也可以建议一个可能触发重新评估本决策的时间点或具体事件。
适合放入的内容:
- 参与决策的人员名单与角色;
- 决策过程的共识达成方式;
- 相关 ADR、需求、工件的链接;
- 明确的复审时间点(如"本决策将于每年 Q1 复审")或触发重新评估的事件。
这与仓库示例 monorepo-vs-multirepo 的 Related 部分异曲同工:它用 Related decisions / Related requirements / Related artifacts / Related principles 四个小节,把本决策与周边决策、需求、工件、原则关联起来,并注明"Open to revisiting"(对未来重新评估持开放态度)。模板中的 Status 字段也天然支持这种演进:决策被推翻时,把状态改为 Superseded 并链接新 ADR。
九、完整填写示例:从模板到成稿
把上述所有章节串起来,一个完整的填写成品大致如下:
# 为我们的 Web 应用选择消息队列
!!! info
**Status**: Accepted
**Updated**: 2026-06-15
## Summary
我们的新订单服务需要可靠地异步处理高并发订单事件。经过对三种主流消息队列的评估,我们决定采用 Apache Kafka,因为它同时满足高吞吐、持久化与生态成熟度要求。
## Drivers
* 新订单服务需要处理高峰时段每秒数千条事件的异步流转。
* 需要消息持久化,保证消费者宕机时事件不丢失。
* 团队已有 Kafka 运维经验,且现有监控体系可直接复用。
## Options
### Apache Kafka
分布式流处理平台,以分区日志模型提供高吞吐与持久化,生态成熟,但运维组件较多(ZooKeeper/KRaft、Broker、Partition)。
### RabbitMQ
功能丰富的 AMQP 消息代理,支持多种路由与协议,易用性好,但在极高吞吐场景下表现不如 Kafka。
### AWS SQS
托管式队列服务,零运维,自动扩展,但缺少广播/多消费者组模型,且存在 AWS 平台绑定。
## Options Analysis
### Apache Kafka Assessment
* Pro: 吞吐量高,日志模型天然支持事件重放与审计。
* Pro: 持久化机制完善,消费者可随时从任意 offset 重新消费。
* Con: 部署与运维复杂度较高,需要专门的集群管理。
* Other: 团队已有 Kafka 生产环境运维经验,可缩短学习曲线。
### RabbitMQ Assessment
* Pro: 上手快,路由与协议支持灵活。
* Con: 高吞吐与长期积压场景下性能不及 Kafka。
* Other: 与现有监控体系集成需要额外开发。
### AWS SQS Assessment
* Pro: 零运维、自动扩展,成本模型简单。
* Con: 缺乏多消费者组与事件重放能力,不满足审计需求。
* Con: 绑定 AWS 平台,违反多云战略原则。
* Other: 若后续需要纯托管方案可再评估。
## Recommendation
采用 Apache Kafka。它最好地回应了 Drivers:满足高峰吞吐(驱动 1)、提供持久化事件日志(驱动 2)、契合团队既有运维能力与监控体系(驱动 3),且避免了 SQS 的平台绑定问题。
### Consequences
* Pro: 订单事件可全量留存,支持后续事件溯源与数据分析。
* Con: 需要投入 Kafka 集群的运维资源与容量规划工作。
* Other: 可能触发一份新的 ADR:事件 schema 的版本管理策略。
### Confirmation
* 通过代码评审与集成测试验证事件生产/消费链路正确实现。
* 在 CI 中加入适应度函数:所有订单状态变更必须产生对应事件。
* 由平台团队每季度审查集群吞吐指标与积压情况;若连续两个月积压超过阈值,触发本决策复审。
## More Information
* 决策参与人:订单服务团队全体,平台架构师评审通过。
* 触发重新评估的事件:业务吞吐量增长 10 倍,或 Kafka 集群运维成本显著上升。
十、把模板接入团队工作流:命名、目录与工具
模板写好后,还要放入团队协作流程。仓库提供了三条现成路径:
1. 文件命名约定
参照 file-name-conventions-for-adrs:
- 使用现在时祈使动词短语,如
choose-database.md、format-timestamps.md、manage-passwords.md、handle-exceptions.md; - 全小写加连字符;
- 扩展名为
.md; - 若项目采用编号制,可加零填充序号前缀(如
0007-choose-database.md)。
2. git 工作流
参照 how-to-start-using-adrs-with-git:
$ mkdir adr
$ vi choose-database.md
# 写入模板内容后提交到 git 仓库
仓库 SKILL.md 还建议先检查既有约定:git ls-files | grep -iE '(^|/)(adr|adrs|decisions?)(/|$)',若团队已存在 adr/ 或 decisions/ 目录则沿用其命名与编号风格;部分团队更偏好 decisions/ 目录名,因为"decisions"一词能让更多人愿意把供应商决策、规划决策、排期决策也放进来。
3. 模板选择定位
仓库的 模板索引 共收录 11 套模板。技能文档的速查表(见 reference/templates.md)给出了选型建议:
| 场景 | 推荐模板 |
|---|---|
| 默认 / 大多数团队 / 不确定 | Nygard(Title, Status, Context, Decision, Consequences) |
| 多选项且 Pro/Con 重要 | MADR |
| 企业级、需追溯到需求与原则 | Tyree & Akerman |
| 快速高管审批的窄技术选择 | ITD(Important Technical Decision) |
| 供应商/工具选型、成本与 SWOT | Business case |
| 轻量"红绿灯"选项对比表 | Gareth Morgan |
| "Options → Options Analysis → Recommendation"叙事流 | GIG Cymru NHS Wales |
GIG Cymru NHS Wales 模板最适合需要把多方案权衡过程完整记录并供后来者追溯的决策场景:它的 Options/Options Analysis/Recommendation 三段结构让文档本身就是一份决策过程的透明档案,而非只记录结果的公告。
十一、模板使用边界与注意事项
- 适用范围:本模板面向"多方案比较型"架构决策。若决策只有一个明显选项或属于纯执行层面(如"临时绕过方案"),过度使用本模板会显得笨重——仓库协作文档 teamwork-questions-for-adrs 明确建议:范围、时间、风险、成本都很小的决策,或已被标准/政策覆盖的决策,可以跳过 ADR。
- 事实边界:Options 与 Options Analysis 中的成本数字、性能数据、许可条款会随时间变化,务必在 Updated 字段记录修改日期,对易过期的信息标注时间戳(suggestions-for-writing-good-adrs 的 Timestamps 要求)。
- 多份模板的差异:若你的场景是"轻量红绿灯对比",可参考 Gareth Morgan 模板;若需要严格的追溯关系,可参考 Tyree & Akerman 模板;本模板的独特价值在于叙事完整性——从动机到候选、从权衡到结论、从后果到验证的完整闭环。
结语
GIG Cymru NHS Wales 决策记录模板把 ADR 从"结论备忘录"升级为"决策过程档案"。借助 Status 状态机、Drivers 驱动的 Options Analysis,以及 Consequence 与 Confirmation 的落地闭环,团队可以写出一份份"经得起时间与后来者审视"的架构决策记录。结合仓库的 示例集、写作建议 与 技能文档,你可以立即在本项目或任何团队仓库中把这份模板投入使用。