企业官网建设流程全解析

架构决策记录（Architecture Decision Record，ADR）是一份记录重要架构决策及其背景（Context）与后果（Consequences）的文档。本文以 architecture-decision-record 仓库官方文档 Sugerencias para escribir buenos ADR（即英文版 Suggestions for writing good ADRs）为骨架，系统拆解"好 ADR"应具备的四大特征、Context 与 Consequences 两大部分的写作要点，以及新旧 ADR 之间的取代规则，并结合仓库内置的模板、示例与 Claude Code Skill 源码给出可落地的实践建议。读完本文，你将掌握一套可复用的 ADR 质量标准，能据此审视、撰写并维护团队自己的决策记录。

一、好 ADR 的四大特征：从"记了什么"到"为什么这么记"

一个合格的 ADR 远不止记录"我们选了 X"，它必须满足四个特征：Justificación（Rationale，理由）、Específico（Specific，单一主题）、Marcas de tiempo（Timestamps，时间标记）、Inmutable（Immutable，不可变）。这四点在仓库的英文原文中表述为 Rationale / Specific / Timestamps / Immutable，并被 writing-guide.md 与 SKILL.md 的写作清单完整继承，说明它们是贯穿该项目的核心质量标准。

1. Rationale（理由）：讲清楚"为什么做这个决策"

好 ADR 必须解释做出该项架构决策（Architecture Decision，AD）的原因。理由部分可以包含但不限于：

• Context（背景）：当前面临的问题与约束（详见下文第二节）；
• 各候选方案的优缺点（pros and cons）；
• 功能对比（feature comparisons）；
• 成本效益分析（cost/benefit discussions）。

仓库的 writing-guide.md 将其提炼为一句检查标准："解释决策的原因——背景、各选项的利弊、功能对比、成本/收益，而不仅仅是结果本身"。仓库示例 choosing-a-database-technology 是这一特征的教科书式示范：它在 Context 中列出关系型、文档型、事件型三类数据库，随后在 Decision 中选定文档数据库，并给出四条 Rationale（灵活数据模型、水平扩展、高效检索、无需复杂事务），每条都对应应用的实际需求。注意该示例把 Rationale 独立成节，与 Context、Consequences 并列——你可以按团队习惯把理由并入 Context，也可以单独成节，关键是"理由必须存在"。

2. Specific（单一主题）：一个 ADR 只讲一个 AD

每个 ADR 应只围绕一项架构决策展开，而不是一次塞进多个决策。理由在于：

• 单一主题的 ADR 更容易评审、更容易被后续 ADR 引用和取代；
• 多个决策混杂在一个文件里，会导致状态、理由、后果彼此纠缠，难以维护。

SKILL.md 第 5 节明确要求："One decision per ADR.Don't bundle multiple architecturally distinct decisions into one file."（一个 ADR 一个决策，不要把多个架构上相互独立的决策打包进同一个文件）。如果确实面临一组相关联的决策，正确做法是拆分为多个 ADR，并通过"后续 ADR"（后续小节会讲）在 Consequences 中建立引用关系。

3. Timestamps（时间标记）：标注每一项的写入时间

ADR 中每一项内容都应标明书写时间。这一点对随时间变化的要素尤其重要，典型包括：

• 成本（costs）：供应商报价、云资源单价、许可费用；
• 日程（schedules）：里程碑、交付计划；
• 规模（scaling）：容量规划、并发预估；
• 类似的可变信息：版本号、依赖的可用性等。

为什么要这么做？因为 ADR 会被长期阅读和引用，如果读者无法区分"这条信息是决策当时的事实"还是"事后补充的修正"，就很容易被过时的数字误导。writing-guide.md 的对应表述是："Timestamped: date anything that may change over time — costs, schedules, scaling numbers, vendor terms."（为任何可能随时间变化的内容打上日期——成本、日程、规模数字、供应商条款）。在模板层面，MADR 模板（decision-record-template-of-the-madr-project）在文件头部就预留了Date: [YYYY-MM-DD when the decision was last updated]字段，正是这一特征的结构化落地。

4. Immutable（不可变）：不修改既有信息，而是增补或取代

ADR 一旦成文，其既有信息不应被修改。当情况变化时，有两种合规做法：

• 增补（amend）：在原 ADR 中追加新信息（保留原内容不变）；
• 取代（supersede）：创建新的 ADR取代旧的 ADR。

这一原则与 git 的哲学高度一致——ADR 本质上是"决策的提交历史"。值得注意的是，teamwork-advice-for-adrs 中记录了真实的团队实践经验：理论上的不可变是理想状态，但实践中"可变文档（living document）"在部分团队中效果更好——即把新信息以"日期戳 + '该信息在决策之后到来'的说明"形式插入既有 ADR。因此更准确的表述是：在一个项目内选定一种约定并保持一致（要么不可变+取代，要么带日期戳的增补式 living document），writing-guide.md 也明确允许两种风格并存，只要项目内统一并声明采用哪种约定。

二、写好「Context」部分：从技术问题到决策全景

「Context（背景）」是 ADR 中承上启下的部分，它回答"我们当时面临什么、为什么必须现在做决定"。一份好的 Context 应包含三方面内容：

1. 解释组织状况与业务优先级

不要只写技术问题本身（"我们需要一个数据库"），而要写组织当时的处境与业务优先级：业务处于什么阶段、增长预期如何、哪些非功能需求（性能、成本、合规）是硬约束、哪些可以妥协。仓库 writing-guide.md 的原话是："Explain the organization's actual situation and business priorities, not just the technical problem."（解释组织真实的处境与业务优先级，而不仅仅是技术问题）。

2. 纳入基于团队构成（社会构成与技能构成）的考量和理由

决策不是纯技术推演，团队的能力结构直接影响方案可行性。Context 中应体现：团队当前的社会构成与技能构成（social and skills makeups）——例如团队是否熟悉某项技术栈、是否需要引入新的运维能力、跨团队协作边界在哪里。这些"人的因素"往往是方案能否落地的关键变量，writing-guide.md 建议"在决策相关的范围内，纳入团队的技能构成"。

3. 写出与自身需求和目标对齐的优缺点

Context 中的优缺点必须与团队的真实需求和目标对齐，而不是放之四海皆准的模板套话。同样的"关系型 vs 文档型数据库"，在"需要复杂事务"的团队和"需要快速原型迭代"的团队眼中，结论可能完全相反——Context 的价值就在于把这个"对齐过程"写清楚。

三、写好「Consequences」部分：把决策的涟漪写进文档

「Consequences（后果）」记录决策之后发生的事情。一份好的 Consequences 应覆盖：

1. 决策带来的效应、结果、产出与后续跟进

包括但不限于：决策使哪些事情变得更容易、哪些事情变得更困难、产生了哪些新的产出物、需要哪些后续行动。仓库的 choosing-a-database-technology 示例为此提供了范本：它写明选择文档数据库后"需要投入学习并理解所选具体技术，且需确保应用的数据模型与文档数据库模型匹配以最大化性能与扩展性"——既写了成本，也写了收益权衡。writing-guide.md 特别强调要**同时覆盖"变容易的"和"变困难的"**两个方面，避免只报喜不报忧。

2. 记录任何后续 ADR

一个 ADR 经常触发更多 ADR 的产生——例如一个"大而全"的总体决策（选择某种数据库技术）会派生出若干更小的决策（选哪家云厂商的托管服务、数据模型怎么设计、备份策略如何定）。好的 Consequences 应显式列出这些"由本次决策派生的后续决策"，为后续 ADR 的创建建立线索。

3. 纳入事后评审（after-action review）流程

常见的团队实践是：每个 ADR 在决策一个月后进行一次评审，将 ADR 中记录的信息与实际发生的情况对照，从而学习和改进。在 Consequences 中写明"本团队将在一个月后对此 ADR 进行事后评审"的预期，等于为决策记录设置了复盘节点。writing-guide.md 给出的默认建议正是"常见做法：一个月后对比 ADR 与实际情况"。

四、新旧 ADR 的取代规则：让决策历史可追溯

当一项新的架构决策取代或使旧 ADR 失效时，规则很明确：必须创建新的 ADR，而不是改写旧的。仓库的 SKILL.md 第 6 节给出了标准的三步操作流程，可直接照做：

1. 创建新 ADR 文件，描述新决策；
2. 更新旧 ADR 的 Status 字段为Superseded by new-adr，指向新 ADR；
3. 在新 ADR 中反向链接：在 Status/Links 部分写明Supersedes old-adr。

这套"双向链接"机制让决策历史形成一条可回溯的链条：任何读者都能从旧决策一路追踪到最新决策，并理解决策的演变原因。这也解释了为何四大特征中的Specific与Immutable如此重要——只有每个 ADR 只讲一个决策、且不被随意改写，取代关系才能保持清晰、可靠。

五、配套实践：文件命名、模板选择与自动化保障

写好 ADR 不止于掌握上述质量标准，仓库还提供了三个层面的配套实践，让"好 ADR"从原则变成日常习惯。

1. 文件命名约定：让文件名自带语义

仓库官方推荐的文件命名约定（详见 file-name-conventions-for-adrs）：

• 现在时祈使动词短语：如choose-database.md、format-timestamps.md、manage-passwords.md、handle-exceptions.md——这既利于阅读，也与 commit message 的格式习惯一致；
• 小写 + 连字符：与仓库本身风格一致，兼顾可读性与系统易用性；
• 扩展名用.md：便于 Markdown 格式排版。

若项目采用编号制，可加零填充序号前缀（如0007-choose-database.md，即 adr-tools 风格），SKILL.md 第 3 节对此有说明。

2. 模板选择：按决策形态匹配骨架

仓库收录了十余套 ADR 模板，选择标准可参考 SKILL.md 中的对照表（节选）：

其中 Nygard 模板最为简单流行，其 Status 字段可取值proposed / accepted / rejected / deprecated / superseded等；Tyree & Akerman 模板则提供了 Issue、Decision、Status、Group、Assumptions、Constraints、Positions、Argument、Implications、Related decisions 等更完整的字段体系；MADR 模板强调 Considered Options 与 Pros and Cons 的结构化对比——这些骨架本身就是"好 ADR 特征"的具象化。

3. 决策即代码：用 fitness function 让决策可测试

仓库的 fitness-functions-for-decisions-as-code 提出了一个进阶实践：fitness function（适应度函数）是写在代码里的客观自动化检查，用于验证决策是否仍在被遵守。决策记录（ADR）负责"文档化"决策，fitness function 负责"保障"决策：

• 示例决策："我们使用 event sourcing 满足审计需求"；
• 示例 fitness function："在 CI 服务器上测试所有状态变更必须产生事件"。

这意味着"好 ADR"的最终形态不仅是文档，还可以被机器持续验证——文档化的质量标准与代码化的验证手段互为表里。

六、结语：把"写好 ADR"变成团队的默认动作

回顾全文，一份好 ADR 的检验清单可以浓缩为四问：有没有讲清理由（Rationale）？是不是只讲一个决策（Specific）？可变信息有没有打时间戳（Timestamps）？旧信息有没有被改写（Immutable）？再加上两条对 Context 与 Consequences 的要求——Context 要写组织处境、团队构成和对齐的利弊，Consequences 要写后果、后续 ADR 与事后评审——就构成了一套完整、可执行的质量标准。

这些标准并非空谈：architecture-decision-record 仓库不仅用文档定义它们，还将其固化进 architecture-decision-record-skill 的写作流程、writing-guide.md 的检查清单、十余套模板与 82 个示例中。读者可以把本文作为团队的 ADR 评审 checklist：在提交每个 ADR 前，逐条对照四大特征与两大章节要求自查，即可显著提升决策记录的可读性、可追溯性与长期价值。