企业官网建设流程全解析

导读：本文讲解 architecture-decision-record 开源仓库收录的 Gareth Morgan 版 ADR（Architecture Decision Record）模板。该模板在经典"上下文—决策—后果"骨架之上，专门增设了 Governance（治理）与一套红绿灯（traffic-light）配色的 Options Analysis（备选方案分析）矩阵，适合在面临多个技术路线选择时，用"绿/黄/红 + 正负号"快速把每个选项的契合度摆到桌面上。读完本文，你将掌握该模板每个字段的填写要领、三张对比表的用法，以及如何在 git 项目中落地一套可检索、可评审的 ADR 流程。

模板在仓库中的定位

本仓库 architecture-decision-record 是一份 ADR 模板、示例与协作指南的合集，内容按语言镜像存放于 locales 目录。本文关联的孟加拉语版本位于 locales/bn-001/টেমপ্লেট/গ্যারেথ-মর্গানের-সিদ্ধান্ত-রেকর্ড-টেমপ্লেট/index.md，其英文原版（仓库的事实源）是 locales/en-001/templates/decision-record-template-by-gareth-morgan/index.md，两个文件内容一致、逐段对应。

仓库自带的 Agent 技能文档对该模板的定位做了清晰概括：在 skills/architecture-decision-record-skill/SKILL.md 的模板选择速查表中，"需要一个轻量级红绿灯式选项对比表"时，推荐的就是Gareth Morgan模板。也就是说，相比 Nygard 的极简版（标题/状态/上下文/决策/后果）和 MADR 的重选项版，这个模板的特色是：把备选方案分析做成可视化矩阵，同时保留治理（Governance）小节。

仓库共收录十一套模板，全部列在 locales/en-001/templates/index.md（孟加拉语索引见 locales/bn-001/টেমপ্লেট/index.md），Gareth Morgan 模板是其中侧重"选项权衡可视化"的一套。

模板整体结构一览

模板以一个编号标题开头，随后依次是 6 个主小节和一组可选的 Options Analysis 子小节：

标题与编号：为每条记录建立可引用身份

模板第一行是# [000] Title（孟加拉语版为# [000] শিরোনাম），占位说明明确写道：

为方便引用与归档，为每条 ADR 分配一个编号

编号（如[000]）是 ADR 之间互相引用、状态流转（如DEPRECATED by [000]）的基础。实际项目中建议用零填充的序号（如0007-choose-database.md），这一约定同时出现在 locales/en-001/documents/file-name-conventions-for-adrs/index.md 与技能文档中。

同时，模板提示所有斜体文字都只是填写指引，正式发布前必须删除。

Status：声明决策的四个生命周期状态

## Status - DRAFT / ACTIVE / DEPRECATED by [000] / SUPERSEDES [000]

状态字段有四种取值，直接关系到 ADR 的可信度与检索：

• DRAFT：草稿，尚未定论；
• ACTIVE：当前生效的决策；
• DEPRECATED by [000]：已被编号为[000]的 ADR 弃用；
• SUPERSEDES [000]：本 ADR 取代了编号[000]的旧 ADR。

这与仓库"好 ADR"建议中的不可变性原则呼应：已有信息不应被静默改写，而是通过"新 ADR 取代旧 ADR"的方式演进。仓库 locales/en-001/documents/suggestions-for-writing-good-adrs/index.md 明确写到：当一个决策取代或使旧 ADR 失效时，应当创建新的 ADR，并把旧 ADR 的状态标记为被取代。

Context：讲清"为什么会有这个问题"

## Context *简述本 ADR 旨在解决的问题，以及这些问题为何存在。*

这一节是 ADR 的"为什么"核心，仓库给出的写作建议（见上节链接）要求：

• 说明组织所处局面与业务优先级；
• 纳入基于团队人员构成与技能结构考虑的论据；
• 列出与自身目标对齐的利弊。

不要只写"我们需要一个数据库"，而要写出约束条件与相互拉扯的力量——例如成本压力、合规要求、团队现有技能栈的分布。

Decided Approach：把决策写具体

## Decided Approach *详细写出已经做出/将要做出的、架构上重要的决策，并说明它如何解决 Context 中描述的问题。*

写作要点：决策要陈述得明确而非含糊；必须与 Context 中的问题一一对应，讲清"选它"是如何化解"问题"的。该模板用 "Decided Approach" 而不是常见的 "Decision"，意在强调这是一条"被选定、将被执行的路线"，而非一句口号。

Consequences：影响要落到架构特性与功能需求

## Consequences *该决策对系统的架构特性（architecture characteristics）与功能需求（functional requirements）有什么影响？*

这一节要求双向思考：既要写决策带来的正面结果（如可扩展性提升、集成更顺畅），也要写它让什么变得更难（如运维复杂度上升、迁移成本）。仓库建议（suggestions-for-writing-good-adrs）还提醒：一个大的总括决策往往会触发新的后续决策，因此 Consequences 里应包含对后续 ADR的提示；团队也常在决策一个月后进行复盘，把记录与实际结果对照。

Governance：把"谁来保证"写进文档

## Governance *该决策的结果如何被监督？* *如何确保与决策保持一致？*

这是本模板区别于多数轻量模板的独特小节。它迫使团队回答两个治理问题：

1. 结果监督：通过什么指标、评审或工单机制观察决策落地后的效果；
2. 一致性保证：如何让后续开发持续遵循该决策——例如架构评审、代码审查中检查架构关注点，或用自动化检查（fitness function）来守护决策。

仓库在 locales/en-001/index.md 的 "Fitness functions for decisions as code" 一节给出可落地的思路：决策记录"记录"决策，而 fitness function 用代码"保证"决策——比如"所有状态变更必须产生事件"这条决策，可以用 CI 测试来强制验证。

Options Analysis：红绿灯矩阵的使用方法

Options Analysis 是可选小节，模板明确提示：如果适用，可包含或链接为达成决策所做的权衡分析。它由三张表构成，并配有一套视觉"信号（Key）"约定。

信号约定：绿、黄、红 + 正负号

模板定义了三色编码与符号前缀：

• 绿色（#4bce97）背景 = 契合度好；
• 黄色（#f1c232）背景 = 契合度变差；
• 红色（#e06666）背景 = 契合度最差；
• \+表示正面影响的批注；
• \-表示负面影响的批注。

这套约定让评审者一眼扫过即可定位问题选项，而不必逐字阅读每格文字。

高层概览表：三行快速判断

第一张表以"Summary"为行，横向对比Option 1 / Option 2 / Option 3，模板给出三行示例维度：

注意示例中的信息量：同一个选项在不同维度上可以一绿一红，这正是红绿灯矩阵的价值——它强制团队承认"没有完美选项"，并显式记录每个维度的取舍。

功能需求表：按场景逐格评估

第二张表以"Scenario"为行：模板预设Scenario 1 / 2 / 3，每个单元格填写该选项在此场景下的契合情况。模板还提示：可选：添加更多行/另一张表，以覆盖已知的未来场景。未来场景（如容量翻倍、新地域合规）通常最能区分长期候选方案。

非功能需求表：落到架构特性

第三张表以"Architecture Characteristic"为行，模板给出三行示例：Scalability（可扩展性）、Performance（性能）、Availability（可用性）。模板特别注明：

“Architecture Characteristics”本是更合适的标题，但请按你所在业务领域习惯的语言调整。

也就是说，行维度可以替换为你所在领域关心的质量属性。表末同样提示：可选：添加或链接针对你业务/产品语境定义的架构特性说明。这一做法让表内每个术语都有权威定义可追溯，避免评审时对"什么是可用性"产生分歧。

在 git 项目中落地：从模板到工作流

模板本身是一份待填写的骨架，落地时建议按仓库推荐的流程操作：

1. 建目录：为 ADR 创建独立目录（仓库建议mkdir adr，不少团队偏好decisions这个更直观的名字，理由见 locales/en-001/index.md 的团队协作建议）；
2. 建文件：每个 ADR 一个 Markdown 文件，文件名用现在时祈使短语 + 小写连字符，如choose-database.md、format-timestamps.md；
3. 填模板：把本模板各小节复制进文件，用实际内容替换占位斜体说明；
4. 写实：确保 Context 解释"为什么"，Decided Approach 明确"选什么"，Consequences 双向列出影响，Governance 写明"怎么监督"；
5. 提交：将 ADR 提交进 git 仓库，随代码一起版本化，供团队评审与后续检索。

若想进一步自动化，仓库还提到可在 PR 上挂接决策守护（如 ADR Guard 这类 gate），用 CI 强制"被监控代码路径变更时必须伴随 ADR 更新"，与 Governance 小节的意图一致。

模板间的横向参照

如果团队觉得该模板的矩阵分析过重或过轻，仓库提供了其他形态的模板可选（locales/en-001/templates/index.md）：

• Nygard：最简，只有 Title/Status/Context/Decision/Consequences，适合大多数默认场景；
• MADR：强调选项及其利弊的展开叙述；
• Tyree & Akerman：更复杂，面向企业级需求/原则追溯；
• Business case：MBA 风格，含成本、SWOT 与更多意见；
• GIG Cymru NHS Wales：采用"Options → Options Analysis → Recommendation"叙述流（见 locales/en-001/templates/decision-record-template-by-gig-cymru-nhs-wales/index.md）。

Gareth Morgan 模板的差异化价值在于：把权衡分析压缩为可直接扫描的三色矩阵，同时用 Governance 小节把"事后如何保证"制度化，特别适合需要向多方干系人快速同步多选项对比结果的场景。

进一步阅读

• 模板英文原版：locales/en-001/templates/decision-record-template-by-gareth-morgan/index.md
• ADR 基础概念：locales/en-001/documents/what-is-an-architecture-decision-record/index.md
• 写作建议：locales/en-001/documents/suggestions-for-writing-good-adrs/index.md
• 文件命名约定：locales/en-001/documents/file-name-conventions-for-adrs/index.md
• 模板选择速查表与写作清单：skills/architecture-decision-record-skill/SKILL.md
• 更多模板与示例：locales/en-001/templates/index.md、locales/en-001/examples