Architecture Decision Record 实战：以 CSS 框架选型（Bulma）为例的完整 ADR 撰写指南

这篇技术指南以仓库中的真实示例 CSS framework 决策记录 为骨架，系统讲解如何以"架构决策记录（ADR）"的规范结构记录一次 CSS 框架选型过程，并深度结合仓库内的模板文档与源码证据，帮助读者掌握从问题定义、候选方案对比、决策论证到后续影响跟踪的完整写作方法，并可直接套用该结构撰写自己的技术决策记录。

一、背景：什么是 ADR，以及这份 CSS 框架记录在仓库中的位置

架构决策记录（Architecture Decision Record，ADR）是一种捕获重要架构决策及其上下文与后果的文档。与之相关的核心概念还包括：

• 架构决策（AD）：满足一项重要需求（architecturally-significant requirement）的软件设计选择；
• 架构决策日志（ADL）：为某个项目（或组织）创建并维护的全部 ADR 的集合；
• 架构知识管理（AKM）：上述全部内容所属的学科领域。

（以上定义与缩写均来自仓库文档 what-is-an-architecture-decision-record。）

本仓库architecture-decision-record以"决策记录示例 + 决策记录模板 + 使用教程"三部分构成。其中示例统一存放在各语言目录的examples/下，例如本文主角 locales/en-us/examples/css-framework/index.md，以及其姊妹目录 locales/en-us/examples/css-framework/README.md（内容与 index.md 一致）；所有示例的索引见 locales/en-us/examples/index.md，根目录 README.md 也提供了指向各示例与模板的总览。

需要特别指出：这份 CSS framework 记录采用的结构（Issue → Decision → Status → Assumptions → Constraints → Positions → Argument → Implications → Related decisions/requirements/artifacts/principles → Notes）并非仓库自创，而是来自 Jeff Tyree 与 Art Akerman 在 Capital One 发表的架构决策描述模板。仓库中保留了该模板的完整字段说明文档 decision-record-template-by-jeff-tyree-and-art-akerman，本文后续将逐字段对照该模板的官方定义来讲解示例记录中每个部分的写法与意图。

此外，本仓库同时收录了其他风格迥异的 CSS 相关决策示例，可用于对比不同 ADR 模板的表达差异，例如采用"Decision → Context → Decision Drivers → Considered Options → Decision Outcome"结构的 Tailwind CSS 决策记录。

二、Summary 部分：用 Issue / Decision / Status 交代决策全貌

ADR 的开头应让读者在最短时间内了解"为什么做这个决策、做了什么决策、当前处于什么状态"。本示例的 Summary 由三个子字段构成：

Issue（问题）

原文提出的问题非常明确：

We want to use a CSS framework to create our web applications.

并给出了三个核心诉求：

• 用户体验快速且可靠：需要在所有主流浏览器与屏幕尺寸下都提供快速、可靠的用户体验；
• 设计与布局的快速迭代：希望在 design、layout、UI/UX 等方面能够快速迭代；
• 响应式应用支持：尤其要覆盖小屏（移动设备）、大屏（4K 宽屏）以及动态屏幕（如可旋转显示屏）。

对照模板文档中的定义，Issue 字段要求"描述你正在解决的架构设计问题，不留任何关于为什么现在解决这个问题的疑问"。本示例通过列出三个具体诉求，把"为什么现在需要选型 CSS 框架"这一动机交代清楚，值得模仿。

Decision（决策）

Decided on Bulma.

决策字段要求"清晰地陈述架构方向——即你选定的立场"。示例最终选定Bulma作为 CSS 框架。

Status（状态）

Decided on Bulma. Open to new CSS framework choices as they arrive.

状态字段用于标记决策所处阶段（如 pending、decided、approved）。示例在宣布已决的同时补充"对未来新出现的 CSS 框架选项保持开放"，体现了 ADR 的可演进性：决策不是不可更改的教条，而是一个有明确复核触发条件的快照。

三、Details 部分：Assumptions / Constraints / Positions / Argument / Implications

Details 是本 ADR 的信息主体，其五个子字段分别回答"基于什么前提、受什么限制、比过哪些方案、为什么选它、会带来什么影响"。

Assumptions（假设）

假设字段要求"清晰描述决策环境中的底层假设——成本、进度、技术等"。示例记录了两个层面的假设：

1. 产品目标假设：我们要创建现代化、快速、可靠、响应式的 Web 应用；
2. 技术趋势假设：现代 Web 应用正在减少甚至消除 jQuery 的使用，理由有三：
   • 现代 JavaScript 已逐步内置了 jQuery 提供的许多能力，jQuery 的必要性下降，且存在更好、更快、更小的模块提供特定实现；
   • jQuery 的"直接 DOM 操作"思路与现代 JavaScript 框架（如 React、Vue、Svelte）是反模式；
   • jQuery 若被重复加载会相互干扰（加载两次会导致自身冲突等）。

这一部分的意义在于：显式记录假设可以让后续读者判断决策的前提是否仍然成立。例如，一旦"现代框架无需 jQuery"这一假设被打破（某框架重新依赖 jQuery），本决策的部分论据就需重新评估。

Constraints（约束）

约束字段用于"记录所选方案可能给环境带来的附加约束"。示例给出了两个相互权衡的约束：

• 若选择依赖 jQuery 的 CSS 框架，则被迫引入 jQuery：例如 Semantic UI 依赖 jQuery，而 Tachyons 不依赖；
• 若选择极简 CSS 框架，则放弃框架组件：例如 Semantic UI 提供图片轮播（image carousel），而 Tachyons 不提供。

这两条约束实际上构成了选型的两条"过滤轴"：依赖纯净度（是否引入 jQuery）与组件丰富度（是否需要内置组件）。任何候选方案都要在这两个维度上接受检验。

Positions（立场/候选方案）

模板文档对 Positions 的定义非常关键："列出你考虑过的立场（可行选项或替代方案）…… 这并非穷举列表，但你不想在最终评审时听到'你想过……吗？'这样的问题；这会导致可信度下降，并使其他架构决策受到质疑。显式陈述他人的意见有助于赢得其支持者。"

示例记录的候选方案演进过程分三步：

1. 不使用任何框架：仍然可行，尤其是 CSS Grid 已能提供项目所需的大部分能力；
2. 快速初筛（shortlist triage）：评估了 Bootstrap、Bulma、Foundation、Materialize、Semantic UI、Tachyons 等，进入深入评审的两个方案是Semantic UI（语义化程度最高）与Bulma（最轻量且提供当前所需组件）；
3. 深度评审：
   • Semantic UI：组件丰富，包含项目所需的 tabs、grids、buttons 等。团队做了两种方式的试点（典型 CDN 文件与 NPM 仓库），在静态 HTML 页面中成功，但在时限内未能构建出 JavaScript SPA（主要卡在 jQuery 加载问题）。示例还记录了一个重要的外部事实：多年来一直有开发者向 Semantic UI 团队请求提供无 jQuery 版本，但团队明确拒绝，理由是"重写难度过大——Semantic UI 项目中有超过 22,000 处与 jQuery 相关的接触点（touchpoints）"。示例给出了 Semantic UI 的标签页 HTML 写法作为证据：

     <div class="ui top attached tabular menu"> <a class="item">Alpha</a> <a class="item">Bravo</a> </div>

   • Bulma：能力与 Semantic UI 相似，但复杂组件较少；采用现代技术构建（无 jQuery）；存在一些可能用到的第三方组件。示例同样给出了 Bulma 的标签页写法：

     <div class="tabs"> <ul> <li><a>Alpha</a></li> <li><a>Bravo</a></li> </ul> </div>

值得注意的是，这两段代码展示了同一个 UI 需求（标签页导航）在不同框架下的类名表达差异：Semantic UI 使用ui top attached tabular menu这种高度语义化的复合类名组合，而 Bulma 使用简洁的tabs类名加标准 HTML 结构。"把候选方案的代码示例写进 ADR"是增强决策可追溯性的最佳实践——未来的评审者可以直接看到各方案的实现形态差异。

Argument（论证）

模板文档强调："概述你为什么选择某个立场，包括实施成本、总拥有成本、上市时间、所需开发资源可用性等。这可能与决策本身同等重要。"

示例的论证简洁而有力：如上所述，并重点指出 Semantic UI 在技术层面（过多 jQuery 接触点）和领导力层面（对"无 jQuery 版本"是直接拒绝，而非给出路线图、持续改进或捐赠筹资等建设性方案）都存在警示信号。

这里展示了 ADR 的一个高级技巧：论证不仅看技术指标，也看上游项目的治理态度（governance）。一个对社区合理诉求长期说"不"的项目，即使当前技术能力足够，也可能意味着长期的维护风险。反过来说，Argument 字段并不需要长篇大论——它是对 Positions 部分证据的提炼与归纳。

Implications（影响）

If we find a good non-jQuery CSS framework, this is generally helpful and good overall.

模板文档对 Implications 的解释是：一个决策会带来许多影响，可能引入新的待决策事项、产生新需求或修改现有需求、给环境增加约束、需要与客户重新谈判范围或进度、或需要额外的人员培训。明确理解并陈述影响，对于获得认同和制定架构执行路线图非常有效。

示例用一句话概括了选择无 jQuery 框架的整体影响：找到好的无 jQuery CSS 框架总体上是有益的。这看似简短，实则为后续 ADR 的展开埋下伏笔——"影响"字段往往是下一条决策记录的"问题"来源。

四、Related 部分：把决策挂接到组织上下文

模板文档强调"决策应由业务驱动"，Related 系列字段正是用来建立这种可追溯性（traceability）的：

• Related decisions（相关决策）：本决策可能影响可测试性（testability）——框架的类名结构、DOM 结构会直接影响选择器编写与端到端测试策略；
• Related requirements（相关需求）：两条——"我们希望快速交付纯现代（purely-modern）的应用"、"我们不想花时间在基于旧依赖（尤其是 jQuery）的旧框架（尤其是 Semantic UI）上"；
• Related artifacts（相关工件）：影响所有将使用该 CSS 的典型 HTML；
• Related principles（相关原则）：Easily reversible（易于逆转）与Need for speed（对速度的需求）。

模板文档的补充定义值得借鉴：Related decisions 在实践中，用可追溯性矩阵（traceability matrix）、决策树（decision trees）或元模型（metamodels）往往比单纯罗列更有效；Related requirements 应"评估每个架构决策对满足每个需求的贡献，若一个决策不服务于任何需求，就不要做这个决策"；Related principles 则要求"确保决策与组织既定原则中的一条或多条保持一致"。

Notes（备注）

Any notes here.

模板文档指出，决策过程可能持续数周，因此建议记录团队在社交化（socialization）过程中讨论的备注与问题。示例保留了一个占位说明，提示"在此填写任何备注"——这提醒我们 Notes 字段应如实记录决策过程中的开放问题与讨论痕迹，而非留空。

五、源码印证：这条 ADR 在仓库中如何被组织、检索与发布

这条 CSS 框架 ADR 不仅是独立文档，它已融入仓库的完整内容流水线：

1. 多语言组织：同一份决策记录被翻译为数十种语言，例如英文版 locales/en-us/examples/css-framework/index.md、德文版locales/de-001/beispiele/css-framework/、日文版locales/ja-001/例/css-framework/等（各语言目录结构见 locales/）。各语言示例索引见 locales/en-us/examples/index.md；
2. 站点发布：网站构建工程architecture-decision-record.github.io中同步维护了对应的发布版内容 architecture-decision-record.github.io/src/content/locales/en-us/examples/css-framework.md，并出现在搜索引擎索引 architecture-decision-record.github.io/static/llms.txt 的条目列表中，说明该示例已被纳入面向 LLM/Agent 的可检索目录；
3. 辅助脚本：网站工程下的 scripts/ 目录包含站点构建检查、sitemap 生成、搜索索引生成等脚本，用于保障这类内容文档的发布质量（如 generate-sitemap.mjs、generate-search-index.mjs）。

由此可见，一条合格的 ADR 不仅要在写作结构上自洽，还应处于一个可维护、可检索、可发布的文档体系中。

六、写作方法论：从这份记录提炼可复用的 ADR 写作清单

综合本示例与模板文档，可总结出撰写同类 ADR 的实践清单：

1. 用 Issue 交代"为什么现在做"：把驱动选型的业务与技术诉求（速度、可靠性、响应式、迭代效率）显式列出；
2. 用 Decision 给出明确结论：一句话说清选型结果（Decided on Bulma）；
3. 用 Status 说明演进性：标注当前状态并写明"对什么保持开放"；
4. 用 Assumptions 记录前提：写清技术趋势与产品目标假设，便于日后验证；
5. 用 Constraints 建立筛选条件：把"是否引入 jQuery""组件是否够用"这类权衡轴写清楚；
6. 用 Positions 完整呈现候选方案：从"无框架"到初筛再到深度评审，并为每个深度评审方案附上真实代码示例与试点结果；
7. 用 Argument 提炼决策理由：包括技术指标与上游项目治理态度等软性因素；
8. 用 Implications 展开影响面：为后续决策留下线索；
9. 用 Related 建立追溯链：关联到决策、需求、工件与组织原则；
10. 用 Notes 记录过程痕迹：留存讨论中的开放问题。

如果想要更简短的 ADR 风格，可参考同仓库的 Tailwind CSS 示例（Context → Decision Drivers → Considered Options → Decision Outcome 结构）；如果想要字段定义层面的权威解释，则直接查阅 Tyree & Akerman 模板 与 ADR 概念文档。更多决策记录示例与模板入口见根目录 README.md。