企业官网建设流程全解析

架构决策记录（Architecture Decision Record, ADR）用于捕获重大架构决策及其上下文与后果，而"可持续"则要求这些决策记录在数年后依然可读、可维护、可追溯、不会迅速过时。本文以 architecture-decision-record 仓库中 西班牙语文档《Pautas para lograr decisiones sostenibles》（对应英文版 Guidelines to Achieve Sustainable Decisions）为骨架，逐条拆解实现可持续决策的八条准则，并结合仓库内的评判标准、模板、示例与"决策即代码"实现给出可落地的实操方案。读完本文，你将掌握一套"先轻后重、分级记录、可追溯、可自动校验"的 ADR 工作方法，能够直接套用到自己的项目中去。

什么是"可持续的架构决策"

在深入八条准则之前，需要先明确评判标准。仓库配套文档 Criterios de sostenibilidad de las decisiones（决策可持续性评判标准）（英文版 Decision Sustainability Criteria）从 InfoQ 那篇关于可持续架构设计决策的公开文章中提炼出五个关键维度，正好作为八条准则的"体检表"：

1. 战略性（Strategic）：决策时要考虑长期影响，例如未来的运维与维护成本。记录时也应写明这些战略后果，而不是只写技术选型本身。
2. 可衡量、可管理（Measurable and Manageable）：决策结果应能按客观标准（最好是数值化标准，如质量属性场景）在时间轴上被测量与评估；同时必须限制决策的粒度——不可能捕获所有细粒度决策，架构师应当把粒度收敛到"设计一个类"这类层次，从而得到更可持续的决策集合、更少的追溯链接；限制决策之间的依赖数量还能降低变更的连锁反应。
3. 可实现、切合实际（Achievable and Realistic）：解决方案与问题匹配的论证要务实且显式化，例如明确说明自己避免了过度设计或设计不足，即采用"足够好（good enough）"原则。
4. 根植于需求（Rooted in Requirements）：决策应扎根于领域特有的架构经验与上下文，考虑公司环境、项目需求与约束，包括开发团队当前的技能水平、培训预算和流程。
5. 恒久（Timeless）：决策应建立在不太可能很快过时的经验与知识之上，例如优先选择平台无关的架构模式或战术（tactics）。

这五条标准回答了"什么样的决策才算可持续"，而下面八条准则则回答"如何一步步做到"。两者互为表里：写每一条 ADR 时都可以用这五条标准自查一遍。

准则一：初始文档采用轻量极简（lean/minimalistic）方式

Use un enfoque ligero y minimalista para la documentación inicial de las decisiones.

第一条准则是整个方法论的地基：决策刚做出时，不要一上来就写长篇大论。轻量极简的初始记录有三大好处：降低记录门槛，让团队成员愿意写；把精力留给真正需要深挖的决策；避免在决策仍可能反复调整时浪费排版与论证成本。

仓库在 文件名约定 中展示的正是"轻量"在文件层面的体现——每个 ADR 就是一个普通的 Markdown 文本文件，命名使用现在时祈使动词短语 + 小写 + 连字符，例如：

choose-database.md format-timestamps.md manage-passwords.md handle-exceptions.md

这种命名本身就是轻量文化的一部分：它和 commit message 格式一致、可读性好、对系统友好，且不需要任何重型工具链，一个文本编辑器即可开始。

"轻量"还体现在对决策的分类处理上——见准则二与准则四：并非所有决策都要同样详尽的记录，先统一用简版记录，再对少数重要决策升级为完整模板。

准则二：对所有重要决策进行优先级排序并完整捕获

Priorice y registre todas las decisiones importantes que sean lo bastante relevantes para documentar y comprender la arquitectura objetivo.

第二条准则要求有意识地筛选并记录：不是"所有决策都记录"，也不是"只记录感觉上重要的"，而是对所有重要决策建立优先级，并保证足够相关、足以支撑理解目标架构的决策都被完整捕获。

如何判断"重要"？仓库文档 Cómo empezar a usar ADR（如何开始使用 ADR） 给出了实践入口：与团队讨论"这个架构决策（AD）有多紧迫、多重要""是现在就做还是等了解更多再做"，并维护一份与产品待办清单（backlog）并行的"待决决策清单"。这相当于把"识别决策"本身变成一项持续进行的工程活动，而不是靠拍脑袋。

而"重要"的反面同样需要界定。仓库的 ADR 团队协作提问清单 明确列出不值得发起 ADR 的情形：与架构无关的决策；微小到风险极低、自包含、单人即可完成的决策；已被标准、策略或既有文档完全覆盖的决策；临时的 workaround、概念验证或实验。给出"不记录"的标准，恰恰能让"记录"更有分量。

准则三：在初始工作完成之后，才用完整模板细化特别重要的决策

Detalle las decisiones especialmente importantes con plantillas completas solo después de haber terminado el trabajo inicial (es decir, cuando quienes toman las decisiones estén conformes con las decisiones de arquitectura adoptadas y confíen en que no será necesario revisarlas pronto).

第三条准则是第一条的"升级路径"：只有当决策者对已采纳的架构决策感到满意、并确信近期不会需要修改时，才用完整模板对"特别重要"的决策进行细化。换言之，模板的投入程度应当与决策的稳定度匹配——决策还处于摇摆期就写满八节模板，是典型的过早优化。

仓库为这个"升级"提供了现成的完整模板。以 MADR 项目决策记录模板 为例，完整模板包含：

• Status（状态：proposed / rejected / accepted / deprecated / superseded by ADR-xxxx）
• Deciders（参与决策的人员）、Date（最近更新日期）
• Technical Story（技术背景描述或工单/Issue 链接）
• Context and Problem Statement（上下文与问题陈述）
• Decision Drivers（决策驱动因素）
• Considered Options（候选方案清单）
• Decision Outcome（决策结果：选定方案、理由、正面/负面后果）
• Pros and Cons of the Options（各方案优缺点）
• Links（关联链接）

仓库还提供了另一类更"决策优先"的精简模板——重要技术决策（ITD）模板。它强调：标题直接陈述决策本身（而非主题描述），例如"为端上翻译选用 Qwen2.5 1.5B Instruct"；正文只需 The Problem、Options Considered（选定项加粗）、Rationale（只写决定性因素，不列全部利弊）、Notes 四个小节。这种模板非常适合不严格属于架构决策但同样重要的技术选择，例如选模型、选库、定 CI/CD 策略，也恰好呼应了"先轻后重、按需选择模板深度"的原则。

准则四：用轻量版本充当详细决策的概览与琐碎决策的载体

Use las versiones ligeras y minimalistas del paso 1 como una versión corta de las decisiones documentadas, con el nivel de granularidad adecuado para ofrecer una visión general de las decisiones detalladas, así como para las decisiones triviales u obvias.

第四条准则点明了轻量版本的双重用途：

1. 作为详细决策的"短版本"：对于已用完整模板细化的决策，轻量版起到索引与概览作用，以合适的粒度让读者快速掌握"有哪些决策、各自结论是什么"，再按需深入；
2. 作为琐碎或显而易见决策的正式载体：那些不值得开完整模板的小决策，用一两行轻量记录即可，避免过度文档化。

这其实是在为"决策记录体系"建立两级粒度：顶层是概览级（轻量版），底层是细节级（完整模板）。正如评判标准"可衡量、可管理"所强调的，架构师必须限制决策粒度到"创建设计类"这类层次，粒度过细既无法完整捕获，也会产生海量追溯链接，反而不利于长期维护。仓库的 示例：选择数据库技术 展示了这种两级结构的落地形态——它本身是完整的决策记录（含 Status、Context、Decision、Rationale、Consequences），同时其 Rationale 只保留四条决定性理由，其余候选方案的优劣则收敛在上下文里，可作为团队模仿的范本。

准则五：尽可能复用已有的架构知识

Siempre que sea posible, use el conocimiento de arquitectura existente, ya sea de modelos de orientación o de otras fuentes. Revise y amplíe ese conocimiento y adáptelo al contexto de la decisión específica.

第五条准则要求不要闭门造车：尽可能复用已有的架构知识——无论是指导性模型（guidance models）还是其他来源，然后审查、扩展并将其适配到具体决策的上下文中。

这条准则与"根植于需求"的评判标准相呼应：复用知识不是照搬结论，而是把通用经验当作起点，结合公司环境、项目约束、团队技能进行裁剪。在仓库中，"复用"体现在两个层面：

• 模板复用：仓库的 模板目录 汇集了 MADR、arc42、EdgeX、Gareth Morgan、Michael Nygard、Jeff Tyree 与 Art Akerman、Alexandrian 模式、PLanguage、商业案例等多种业界模板，团队可以直接选用与自己组织风格最匹配的一种，而不是从零发明；
• 决策复用：Cómo empezar a usar ADR 指出许多架构决策会跨项目重复出现，过去的好决策与坏决策经验都可以成为可复用的资产——前提是采用显式的架构知识管理（AKM）策略。

准则六：在决策与需求、架构设计、代码之间建立追溯链接

Asegúrese de que se establezcan vínculos de trazabilidad entre las decisiones y tanto los requisitos como los diseños de arquitectura y el código.

第六条准则要求建立双向追溯：决策要能追溯到它服务的需求（回答"为什么做这个选择"），也要能追溯到它落地的架构设计与代码（回答"这个决策在哪里生效"）。缺少追溯，ADR 就会退化成孤立文档，无人知道它是否仍然有效、是否已被实现。

仓库的 MADR 模板在机制上直接支持这一点：

• 向上追溯需求：Technical Story字段可填描述或 ticket/issue URL；
• 向下追溯实现：Links一节专门用于"Refined by [ADR-0005]"这类指向具体实现 ADR 的链接；
• 决策之间的追溯：Status支持superseded by [ADR-0005]，Links支持关联后续细化决策，完整记录决策链条。

这正符合"好 ADR"的 写作建议：一个 ADR 常会触发更多 ADR——大决策带来小决策，追溯链接把这条链条显式地画出来，而不是让它们散落在各人的记忆里。

准则七：提供自动化一致性检查，并限制决策间依赖数量

Proporcione una comprobación de coherencia automatizada para asegurarse de que los vínculos de trazabilidad se mantengan sincronizados tras un cambio. Limite el número de dependencias entre decisiones y otros artefactos de software.

第七条准则是第六条的自然延伸：追溯链接光建立还不够，必须在变更后保持同步，而同步要靠自动化检查来保证；同时要限制决策之间、决策与其他软件制品之间的依赖数量，因为依赖越少，变更的连锁反应（ripple effect）越小——这与评判标准"可衡量、可管理"中"减少决策依赖以降低变更涟漪"的论述完全一致。

"自动化一致性检查"在仓库中有现成的落地范式，即 Funciones de aptitud para decisiones como código（决策即代码的适配函数）（英文版 Fitness functions for decisions as code）。其核心思想是：

决策记录（decision record）负责记录决策，而适配函数（fitness function）负责确保决策被持续遵守。

仓库给出的经典配对示例：

• 决策：出于审计需求，我们使用事件溯源（event sourcing）；
• 适配函数：在持续集成服务器上运行测试，验证所有状态变更都必须产生事件。

适配函数之所以有效，是因为它具备四个特性（仓库文档原话）：

• 客观可测：函数要么通过要么失败，工作成果一目了然；
• 持续生效：它是"活规则"，每次 commit 和每次构建都会执行；
• 重构信心：决策规则出错时能被自动捕获，团队可以放心演进代码；
• 治理可扩展：在不制造瓶颈的前提下保障标准落地。

更进一步的思路是"架构单元测试"：对 Java 代码可用 ArchUnit 在任意 Java 单元测试框架中校验架构规则；对 TypeScript/JavaScript 代码可用 ArchUnitTS 配合 Jest、Vitest、Jasmine 等框架校验。仓库文档还给出了用 AI LLM 充当适配函数的提示词模板——以检索主导推理（retrieval-led reasoning）优先、开启扩展思考与搜索，把"我们的决策在此、待评估的工作在此"交给模型，让它直接指出错误、问题、缺口与弱点。这些机制共同构成第七条准则的工程实现：链接同步不靠人盯，靠机器盯。

准则八：始终如一、有力地应用论证准则——论证是决策文档的灵魂

Aplique las pautas de justificación de forma consecuente y enérgica: son la parte más importante de la documentación de las decisiones, porque aportan el fundamento.

第八条准则被原文称为整个决策文档中最重要的部分：论证（justification / rationale）为决策提供根基，必须**始终如一（consecuente）且有力（enérgica）**地应用。没有论证的 ADR 只是一句结论，后人无法判断它当时为什么成立、现在是否仍然成立。

仓库 Suggestions for writing good ADRs 把 Rationale 列为好 ADR 的第一特征：解释做出该特定决策的理由，可以包含上下文、各候选方案的利弊、功能对比、成本/收益分析等。同时它给出了一套保证"论证始终如一"的写作纪律：

• Specific（具体）：每个 ADR 只针对一项决策，不混写多项；
• Timestamps（时间戳）：标明每一项内容的写作时间——成本、排期、规模等随时间变化的要素尤其需要；
• Immutable（不可变）：不修改 ADR 中已有信息；需要变化时，要么通过追加信息来修订，要么通过新建 ADR 来取代旧 ADR（当新决策替换或废止旧决策时，必须创建新 ADR）。

"取代"机制与准则六的追溯链接协同：superseded by状态让决策演化历史完整可查，后人在阅读旧 ADR 时能顺着链接看到它已被哪个新决策替代，这正是"论证有力且始终如一"在长期维度上的体现。

八条准则落地：一个可持续 ADR 工作流

把八条准则串起来，就形成一套可直接落地的工作流，配合仓库的 示例 与 模板 即可开工：

1. 轻量起步（准则一）：决策产生时，用"动词短语 + 小写连字符"命名的 Markdown 文件记录一句话结论与理由，例如choose-database.md；
2. 筛选分级（准则二、四）：对照"重要性"与"是否值得记录"标准筛选；普通决策停留在轻量版，作为概览；特别重要的决策进入待升级清单；
3. 稳定后细化（准则三）：当决策者确认方案稳定、近期不会修改时，套用完整模板（如 MADR 模板）补全 Context、Decision Drivers、Considered Options、Decision Outcome、Pros/Cons 与 Links；
4. 复用与适配（准则五）：从仓库模板库或其他来源取用既有架构知识，结合团队技能、项目约束裁剪适配；
5. 建立追溯（准则六）：通过 Technical Story 链接需求，通过 Links 链接细化 ADR，通过 superseded by 记录决策演化；
6. 自动校验（准则七）：为关键决策编写适配函数（ArchUnit / ArchUnitTS / CI 测试），并把决策依赖数量控制在合理范围内；
7. 论证到位（准则八）：每一条 ADR 都要有明确、及时、不可变篡改的 Rationale，并遵守"取代即新建"的纪律。

最后，可用五条评判标准（战略性、可衡量可管理、可实现切合实际、根植于需求、恒久）对每一条决策记录做终检：决策是否有长期影响说明？结果是否可测？方案是否务实且避免过度/不足设计？是否与需求、团队、流程对齐？依据是否不太可能迅速过时？——凡是五项都能给出肯定回答的决策，就是经得起时间检验的可持续决策。