GIG Cymru NHS Wales 决策记录模板:以 Options → Options Analysis → Recommendation 叙事流撰写 ADR
GIG Cymru NHS Wales 决策记录模板:以 Options → Options Analysis → Recommendation 叙事流撰写 ADR
本篇技术指南以 architecture-decision-record 仓库中收录的 GIG Cymru NHS Wales 决策记录模板(德语版 locales/de-001/vorlagen/entscheidungsprotokoll-vorlage-von-gig-cymru-nhs-wales/index.md)为核心,逐节拆解这套以「摘要 → 驱动因素 → 备选方案 → 选项分析 → 推荐」为主线的 ADR 编写方法。读完本文,你将掌握该模板每个字段的填写要求与评判维度,理解它与 Nygard、MADR 等仓库内其他模板的定位差异,并能直接复用模板骨架为所在团队编写可评审、可追踪、可落地的架构决策记录。
一、模板定位:仓库中的「选项叙事流」决策记录
在 architecture-decision-record 仓库中,共收录了 11 套决策记录模板(见 locales/en-001/templates/index.md 与仓库 README.md),包括 Michael Nygard 的经典四段式、Jeff Tyree 与 Art Akerman 的企业级可追踪模板、MADR 项目的选项对比模板、arc42 的全量架构文档模板等。GIG Cymru NHS Wales(威尔士国民医疗服务体系下属的 GIG Cymru 机构)模板是其中唯一一套以 Options(备选方案)→ Options Analysis(选项分析)→ Recommendation(推荐) 三段叙事流为骨架的模板,特别适合「候选方案明确、需要摆出取舍后再做决定」的架构选型场景。
仓库配套的 ADR 编写技能 skills/architecture-decision-record-skill/SKILL.md 在模板速查表中将该模板定位为:
| 决策场景 | 推荐模板 |
|---|---|
| 默认 / 多数团队 / 不确定 | Nygard(Title、Status、Context、Decision、Consequences) |
| 需要轻量级「选项 + 利弊」 | MADR |
| 企业级、需追踪到需求与原则 | Tyree & Akerman |
| 需要快速高管评审的窄技术决策 | ITD |
| 需要「选项 → 选项分析 → 推荐」叙事流 | GIG Cymru NHS Wales |
德语版模板位于 locales/de-001/vorlagen/entscheidungsprotokoll-vorlage-von-gig-cymru-nhs-wales/index.md,其英文源文件(single source of truth)为 locales/en-001/templates/decision-record-template-by-gig-cymru-nhs-wales/index.md。按仓库维护规范(AGENTS.md),所有翻译以英文为源、目录内 README.md 为 index.md 的符号链接,本模板的德语版与英文版内容一一对应。模板全集目录为 locales/de-001/vorlagen/index.md。
二、模板骨架总览
整套模板以标题与「信息块」开篇,随后依次是七个章节,其中后三个章节(Konsequenzen、Bestätigung、Weitere Informationen)标注为可选。模板完整骨架如下:
# {Ihr Titel hier} ← 标题占位符
!!! info ← 信息块(状态 + 更新时间)
**Status**: { Proposed | Under Review | Accepted | Rejected | Superseded | Deprecated }
**Aktualisiert**: {YYYY-MM-DD}
## Zusammenfassung (摘要,必填)
## Treiber (驱动因素,必填)
## Optionen (备选方案,必填)
## Optionsanalyse (选项分析,必填)
## Empfehlung (推荐,必填)
### Konsequenzen (后果,可选)
### Bestätigung (确认,可选)
## Weitere Informationen (更多信息,可选)
可以看出,这套模板的核心设计意图是:先把决策语境交代清楚(摘要、驱动因素),再中立地摆出所有候选方案,然后逐一评估取舍,最后给出明确推荐——即模板在选项分析一节中所强调的「先陈述事实、避免主观意见,分析交给下一节」,保证读者在看评估结论之前,已经对每个备选方案形成无偏见的理解。
三、头部元信息:标题、状态与更新时间
模板的第一行是 # {Ihr Titel hier}(您的标题),并在 !!! info 信息块中提供两条受控元数据:
- Status(状态):从
Proposed | Under Review | Accepted | Rejected | Superseded | Deprecated六种取值中选一,分别对应「提议中 / 评审中 / 已接受 / 已拒绝 / 已被取代 / 已废弃」; - Aktualisiert(更新时间):按
YYYY-MM-DD格式记录最近一次更新日期。
仓库的 ADR 编写技能在 skills/architecture-decision-record-skill/SKILL.md 中给出了同源的状态取值建议:proposed | accepted | rejected | deprecated | superseded by <link>,并强调「给记录一个状态」。当新决策取代旧决策时,正确做法不是静默改写旧 ADR,而是新建 ADR 文件、将旧 ADR 的状态更新为 Superseded by new-adr、并在新 ADR 中反向标注 Supersedes old-adr(见 skills/architecture-decision-record-skill/SKILL.md)。
状态字段之所以重要,是因为 ADR 通常被视作不可变文档:仓库的写作指南 skills/architecture-decision-record-skill/reference/writing-guide.md 明确建议「默认不重写已接受 ADR 的原始内容,而是追加带日期的补充信息,或用新 ADR 取代它」。这与德语版写作建议文档 locales/de-001/dokumente/empfehlungen-für-gute-adrs/index.md 中「不要修改 ADR 中的既有信息,应通过追加新信息或新建 ADR 来修订」的要求完全一致。
四、Zusammenfassung(摘要):电梯演讲式的开篇
模板要求用「典型的 2–4 句」简洁句子完成摘要,其作用相当于技术论文的 Abstract 或一段极简引言。需要覆盖三件事:
- 本 ADR 处理的核心问题、疑问或机会;
- 已做决策或关注领域的简短提示;
- 让读者无需通读全文即可判断该 ADR 是否与自己相关。
摘要的写作要点(模板原文):"Das Ziel ist es, Lesern zu helfen, schnell zu verstehen, worum es in diesem ADR geht, und zu entscheiden, ob er für sie relevant ist, ohne das gesamte Dokument lesen zu müssen."(目标是帮助读者快速理解该 ADR 的主题,并判断其相关性,而无需阅读整个文档。)
仓库示例 locales/de-001/beispiele/zeitstempelformat/index.md 展示了摘要层的典型写法——「问题」段落先用一句话点明诉求(用统一时间戳格式跨系统追踪事件发生时间),再列出三类格式冲突(JSON 无原生时间戳格式、应用使用本地时间而非 UTC、不同系统的精度需求从秒到纳秒不等),随后给出明确决策(选用 ISO 8601 纳秒精度格式)与状态(已决定)。这种「问题 → 决策 → 状态」的浓缩表达,正是摘要章节应该达到的效果。
五、Treiber(驱动因素):为什么是现在、为什么必须做
Treiber 一节回答的是模板原文强调的两个问题:为什么(warum)要做出这项决策、以及为什么是现在(jetzt)。写作要求是清晰阐明促成该架构决策的主要动机、需求或问题,并回到根本原因与约束条件("Denken Sie an die zugrunde liegenden Gründe und Zwänge")。
模板给出了四类驱动因素示例,可直接作为起草线索:
- 我们正在开发需要……的新功能/新能力;
- 我们需要改善性能、可访问性、消除技术债……;
- 用户反馈表明……;
- 当前方案带来了这些限制……
仓库写作指南 skills/architecture-decision-record-skill/reference/writing-guide.md 补充了深度要求:驱动因素要解释组织的实际处境与业务优先级,而不只是技术问题;在相关时应纳入团队的技能构成等社会性因素;利弊陈述要贴合本团队的真实需求与目标,避免套话。同时 locales/de-001/dokumente/empfehlungen-für-gute-adrs/index.md 也强调「Context 应解释组织处境与业务优先级,并基于团队的社会与技能构成给出理由」。后续的选项分析章节会反复引用这里的驱动因素作为评分依据,因此驱动因素写得越具体,后面的评估就越有锚点。
六、Optionen(备选方案):中立陈列全部候选
Optionen 一节的写作纪律是「只陈述事实、避免观点」,因为评估属于下一节。每条备选方案需要给出:简洁描述、事实清单、以及指向相关文档或示例的链接("Fügen Sie eine prägnante Beschreibung und Links zu relevanter Dokumentation oder Beispielen bei")。
模板特别提醒:即使最终未选中的方案,只要它属于你认真研究过的重要替代项,就必须列入。目的是在进入评估之前,让读者对每个备选方案形成清晰、无偏见的理解。结构上每个方案使用三级标题:
### {Titel von Option 1}
{Beschreiben Sie die Option, geben Sie eine Zusammenfassung, listen Sie die Fakten auf, geben Sie Links an usw.}
### {Titel von Option n}
...
仓库示例 locales/de-001/beispiele/zeitstempelformat/index.md 的「Positionen(立场)」一节是这一写法的绝佳参照:它中立地列出了一组备选——Unix 纪元(一个递增数字)、紧凑文本格式 YYYYMMDDTHHMMSSNNNNNNNNN、以及「本地时区 vs UTC 时区」的选择,每条只有一句话,不夹带评价。这正是 GIG Cymru NHS Wales 模板所要求的「先摆事实、后做分析」的分层策略。
七、Optionsanalyse(选项分析):多维度的利弊权衡
选项分析是这套模板的精髓章节,要求对 Optionen 中列出的每个方案进行批判性评估,给出优点、缺点与其他相关权衡的均衡视图,并且「尽可能具体、将观点回扣到 Treiber」("Seien Sie konkret und beziehen Sie Ihre Punkte, wo möglich, auf die Treiber")。模板明确要求至少考虑以下五个维度:
- Kosten(成本):开发、运营、许可成本;
- Komplexität(复杂性):实现、维护、学习曲线的复杂度;
- Risiken(风险):技术、运营、安全风险;
- Übereinstimmung(一致性):与架构原则或现有标准的吻合度;
- Auswirkungen(影响):对性能、可扩展性、可用性、可维护性、安全性等质量属性的影响。
每个方案的评估采用统一的 Pro / Kontra / Sonstiges 三段式结构:
### {Bewertung von Option 1}
* Pro: {Ein konkreter Vorteil oder Nutzen dieser Option.}
* Kontra: {Ein konkreter Nachteil, ein Risiko oder Kosten dieser Option.}
* Sonstiges: {Ein relevanter Punkt, der nicht streng ein Pro oder Kontra ist.}
- Pro:该方案的一个具体优势或收益;
- Kontra:该方案的一个具体劣势、风险或成本;
- Sonstiges:一个不严格属于利或弊、但对决策有参考价值的点(例如前置依赖、迁移窗口、团队熟悉度)。
「Sonstiges」字段是这套模板区别于简单利弊清单的亮点:它允许记录既非优点也非缺点的中立事实,比如「该方案需要现有团队先完成一次技能培训」「该方案与另一项已排期的架构改造存在时间耦合」等。模板同时强调可按需增加任意数量的 Pro/Kontra/Sonstiges 陈述("Fügen Sie so viele Pro-/Kontra-/Sonstiges-Aussagen ein wie erforderlich")。
从仓库的写作建议看,这一节还应呼应 ADR 的「Begründung(理由)」特征——locales/de-001/dokumente/empfehlungen-für-gute-adrs/index.md 要求解释决策理由,包括上下文、各候选的利弊、功能对比、成本收益讨论等;skills/architecture-decision-record-skill/reference/writing-guide.md 也强调「不仅是结果,还要给出理由——上下文、选项利弊、功能对比、成本收益」。评估时应避免泛泛而谈,尽量把每条利弊量化或锚定到驱动因素。
八、Empfehlung(推荐):明确结论并解释为什么
推荐章节要求清楚陈述最终决策、明确指出被选中的方案,并详细解释为什么选择它——重点说明所选方案如何最好地回应 Treiber、满足关键需求或解决既定问题("Sie sollten klar darlegen, wie die gewählte Option die Treiber am besten adressiert")。模板明确要求「明确指名所选选项」,而不是含糊地说「综合考虑后我们倾向于方案 A」。
Konsequenzen(后果,可选)
既然决策已做出,这一节需要描述预期的结果与影响,包括正面与负面;说明接受该决策将承担的已知限制、成本或风险;以及该决策将如何影响不同的利益相关者、其他系统、开发实践、运营流程或用户体验。同样采用三列清单:
* Pro: {Ein konkretes positives Ergebnis oder ein Nutzen, der von dieser Entscheidung erwartet wird.}
* Kontra: {Ein konkreter in Kauf genommener Nachteil, Kosten oder ein Risiko infolge dieser Entscheidung.}
* Sonstiges: {Eine Konsequenz, die nicht streng ein Pro oder Kontra ist.}
写作指南 skills/architecture-decision-record-skill/reference/writing-guide.md 为这一节补充了三条实践建议:既要写「变得更容易」也要写「变得更困难」;应点出该决策催生的后续 ADR(一个大的总体决策往往会产生若干较小的跟进决策);如果团队有事后复盘惯例(常见做法是一个月后对照实际发生的情况重审 ADR),也应在此注明。德语版写作建议文档同样指出「一个 ADR 触发更多 ADR 的需求是相当常见的」(locales/de-001/dokumente/empfehlungen-für-gute-adrs/index.md)。
仓库示例 locales/de-001/beispiele/zeitstempelformat/index.md 的「Zugehöriges(相关)」部分就是后果/关联章节的实践样板:它列出可能需要的后续决策(用 Unix 纪元时间戳轻松计算时长)、可能触发的需求调整(Splunk、Sumo、ELK 等特定日志消息戳格式)、相关语言库与示例链接,以及两条支撑原则(易于反转、推迟过早优化)——充分体现了「一项决策引发后续决策与关联需求」的连锁效应。
Bestätigung(确认,可选)
这一可选章节回答四类问题,目的是证明决策「不只是理论,而是会被积极实施与监控」:
- 如何验证实施正确:代码评审、特定测试、演示、同行评审等;
- 如何长期维持合规:自动化检查、定期审计、更新团队规范、培训等;
- 用哪些指标证明决策达到预期:性能基准、采用率、特定错误数量下降、用户反馈评分等;
- 由谁负责监督,以及不遵守时怎么办:明确责任人及其职责。
这四问与仓库的「fitness function(适应度函数)」理念一脉相承——README.md 指出「决策记录记录决策,而适应度函数以代码形式自动化验证决策仍在被遵守」,例如「决策:为审计需求采用事件溯源」对应「适应度函数:CI 服务器断言所有状态变更必须产生事件」。在 Bestätigung 章节中写下具体的适应度函数或检查手段,就能让 ADR 从文档变成可测试、可保障的治理资产。
九、Weitere Informationen(更多信息,可选)
最后一个可选章节用于补充支撑决策的信息、添加上下文、指导后续行动,典型内容包括:
- 指向其他决策与资源的链接;
- 简要记录参与决策过程的人员,以及共识是如何达成的;
- 建议触发未来重新评估本决策的时间框架或特定事件("Sie können auch einen Zeitrahmen oder bestimmte Ereignisse vorschlagen, die künftig zu einer Neubewertung dieser Entscheidung führen könnten")。
为这一节预留「重评触发条件」是 ADR 长期保鲜的关键机制:技术环境、供应商能力、许可条款会随时间变化,预先写明「何时应重新审视」能让决策日志保持活力,避免过时决策被静默沿用。
十、仓库内配套资源与使用建议
在 architecture-decision-record 仓库中围绕这套模板还有以下可直接利用的配套资源:
- 英文源模板:locales/en-001/templates/decision-record-template-by-gig-cymru-nhs-wales/index.md,如需对照英文原文理解字段语义,可与之对照;
- 模板速查与骨架合集:skills/architecture-decision-record-skill/reference/templates.md 收录了本模板的压缩版骨架,并逐一列出仓库全部模板的适用场景,可用于在写 ADR 前快速选型;
- 写作清单:skills/architecture-decision-record-skill/reference/writing-guide.md 提供「好 ADR 的特征、Context/Consequences 写作要点、是否值得写 ADR 的判断标准、生命周期与角色建议」等完整 checklist;
- 实战示例:仓库的 40 个英文示例与对应翻译(如 locales/en-001/examples/timestamp-format/index.md、locales/de-001/beispiele/zeitstempelformat/index.md)展示了已填写的 ADR 长什么样,可作为内容密度与行文风格的参照;
- 治理与审计:仓库通过 scripts/audit-locales.py 校验每个 locale 的文件数、翻译 slug 与链接锚点,确保多语言模板(包括本德语版)与英文源保持一致。
实际使用时,建议按以下流程落地:先依据 skills/architecture-decision-record-skill/SKILL.md 判断该决策是否值得写 ADR(架构意义重大、未来开发者需要理解「为什么」、涉及真实取舍——值得;微小、自包含、已被规范覆盖或纯临时方案——跳过);然后按仓库的文件命名惯例(现在时祈使短语、小写加连字符、.md 扩展名,如 choose-database.md,见 README.md)创建文件;复制本模板骨架后,从摘要开始逐节填写,确保每条 Pro/Kontra 都能回扣到 Treiber,最后为决策指定状态与更新日期。
总结
GIG Cymru NHS Wales 模板为「方案明确的架构选型」提供了一条清晰、可复用的决策记录路径:摘要与驱动因素锚定「为什么」,备选方案中立陈列「有什么可选」,选项分析用成本、复杂性、风险、一致性、质量影响五个维度加 Pro/Kontra/Sonstiges 三列清单完成「怎么比」,推荐章节给出「选什么、为什么」,而可选的后果、确认与更多信息章节则让决策可追踪、可验证、可重新审视。结合 architecture-decision-record 仓库的写作指南、模板骨架与实战示例,团队可以在不引入任何工具的前提下,用这套模板写出信息密度高、评审效率高的架构决策记录。