用架构决策记录ADR保存设计系统的决策历史Carbon Design System 的实践【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carbon本文基于 docs/decisions/0001-record-project-decisions.md 展开。随着 Carbon Design System 多年演进围绕各项技术决策的背景与理由逐渐流失该项目于 2025-06-24 正式通过架构决策记录Architecture Decision RecordADR制度来保存这份决策历史。读完本文你将理解 ADR 是什么、Carbon 为何以及如何引入它、其模板与编号原则是什么并能直接依照仓库中的真实模板与流程为设计系统项目撰写和维护属于自己的 ADR。背景为什么 Carbon 需要记录决策在 0001 号决策记录 的 Context 一节中Carbon 团队如实描述了当时的困境随着 Carbon Design System 的持续演进围绕许多决策的上下文context与推理过程reasoning已经丢失。对于一套已包含carbon/react、carbon/web-components、carbon/styles、carbon/icons等十余个包、横跨 React / Web Components / 样式 / 图标 / 工具链的庞大设计系统而言一个组件为什么这样设计、这个入口为什么这样导出的原始动机一旦丢失后续维护者就只能靠猜测或重构代码来还原意图成本极高且容易失真。因此决策记录的首要目标是为自己和未来的维护者保存这条决策历史链。决策正式采用架构决策记录ADR0001 号决策 的 Decision 一节给出了明确结论采用架构决策记录ADR方法论源自 Michael Nygard 的经典文章《Documenting Architecture Decisions》ADR 中直接引用了该文章作为方法依据通过 ADR 记录该项目上做出的高层级决策high level decisions以保存决策历史。该决策的状态被标记为Accepted已接受日期为 2025-06-24。从仓库实际内容看这并非一纸空文——docs/decisions/目录下目前已积累 0000 至 0007 共 8 个文件含 1 个模板覆盖组件通信架构、版本语义、打包契约、Storybook 规范、文档内容标准等多个主题说明该制度已被持续执行。ADR 的文档结构五段式模板ADR 之所以易消化在于模板刻意保持精简。模板文件 定义了固定段落每一条 ADR 只需回答五个问题段落作用模板中的提示Title决策标题一句话概括这条决策Status当前状态如 proposed、accepted、rejected、deprecated、superseded 等Context背景是什么问题促使了这个决策或变更Decision决策内容我们提出/正在做的变更是什么Consequences后果这个变更让哪些事情变得更容易或更困难这个结构与 Michael Nygard 提出 ADR 时的经典骨架一致先讲为什么做Context再讲做了什么Decision最后坦诚代价是什么Consequences。在仓库的真实 ADR 中这一骨架被严格沿用——例如 0004 号utilities 包显式入口 在 Consequences 中同时列出 Positive outcomes 与 Tradeoffs and breaking changes把破坏了哪些深层导入路径这类副作用写得很直白。Carbon 的 ADR 使用原则decisions 目录的 README 进一步明确了运行这套制度的具体原则决策记录原则过程层面ADR 会先以提案proposal形式创建再做出决策提案会先在团队内部以及与相关方充分讨论决策一旦做出就通过更新最初/提案版 ADR来记录如果决策被推翻旧记录予以保留但标记为 superseded已被取代并在新旧记录之间互相添加链接。决策记录原则内容层面ADR按顺序编号号码不重复使用模板只保留少数几个部分保证每份文档易于消化每条 ADR 都应以与未来维护者对话的口吻书写——使用完整句子、按段落组织、行文清晰。从仓库证据看这些原则均有落地00010007 编号连续不重复0006 号Storybook 组织标准 的状态是Proposed演示了先提案、后决策的流程其余多为 Accepted体现了决策后更新 ADR的闭环。实操如何撰写一条新的 ADR根据 README 的 Authoring a decision record 一节在 Carbon 仓库中新增一条 ADR 只需四步复制模板在docs/decisions/目录内复制0000-template.md重命名改名为目录中下一个逻辑序号 决策标题例如0008-xxxx.md填写 ADR按 Title / Status / Context / Decision / Consequences 五个部分填写提交 PR将填写完成的 ADR 通过 Pull Request 提交供团队讨论与评审。这一流程与ADR 先以提案形式出现、经讨论后定稿的原则互相印证——PR 评审本身就是 ADR 讨论环节的载体。仓库中的真实实践00000007 全览截至当前仓库docs/decisions/下的记录已构成一个小型决策档案库每条都是 0001 号决策的活体例证编号决策主题状态0000ADR 模板模板文件—0001采用 ADR 记录项目决策Accepted0002TreeView 组件以 React Context 取代递归透传 propsAccepted0003以preview替代experimental/unstable命名Accepted0004utilities 包采用显式 package entrypointsAccepted0005Story 中使用贴近真实任务的示例内容Accepted0006Storybook 故事组织标准Proposed0007web-components 提供纯类导出与按需注册Accepted其中几条尤其能体现 ADR 的价值0002 号记录了一次架构级重构TreeView/TreeNode 原先通过递归遍历组件树来传递 props存在计算开销大、对包裹组件透传不可靠、难以维护等问题决策改用 React Context API 直接通信用户因此可以把 TreeNode 包进任意数量的自定义包裹组件而不影响父子通信。这条记录保存了为什么不用递归的关键推理未来维护者不必重新踩坑。0004 号记录了构建工具迁移Rollup → tsdown带来的契约变化不再把es/、lib/、types/的原始编译产物当作事实上的公共 API而是通过package.json#exports定义显式入口并约定顶层src/name/index.*即公开子路径pkg/name。它同时明确写下了破坏性后果深层导入es/、lib/、types/的用户会 break。0007 号记录了 web-components v3 的一次重大契约变更把import 即注册的副作用式自注册改为纯类导出 defineCustomElement显式注册并详列了多版本共存、自定义 tag 名、tree-shaking、移除es-custom构建等收益与 v3 破坏性变更。可以看到这些记录并不是流水账而是背景问题 → 决策方案 → 收益与代价的完整推理链正好回扣 0001 号决策中保存决策历史链的初衷。收益与成本采用 ADR 的 Consequences0001 号决策在 Consequences 一节中指向 Nygard 的文章而非自行展开但从仓库的长期运行结果可以推断并印证这套制度的实际收益正面收益上下文不再流失每条决策都自带为什么README 所引的项目生命周期中最难追踪的就是某些决策背后的动机这一问题得到缓解新人/未来维护者友好ADR 按与未来维护者对话的方式书写形成可检索、可引用的决策档案决策可追溯编号连续、状态明确proposed / accepted / superseded被取代的决策也予以保留并互相链接历史完整可查范围聚焦README 明确 ADR 只记录具有架构意义的决策——影响结构、非功能特性、依赖、接口或构建技术的决策避免沦为琐事流水账。潜在成本与约束需要团队持续自律每条 ADR 都要经历提案、讨论、定稿的流程且必须保持编号、模板与写作风格的统一ADR 写得好坏依赖撰写者对什么是架构级决策的判断需要 README 中列举的范畴项目流程、团队流程、设计标准、编码规范、UX 最佳实践、API 设计原则、可访问性方案等作为共同语言。结语如何利用这份决策档案对设计系统维护者而言docs/decisions/ 是理解 Carbon 架构演进的第一手资料对设计系统使用者而言阅读 00020007 等记录能快速掌握各包当前的设计契约及其背后的取舍例如为什么 web-components 现在要求显式注册为什么 utilities 包的导入路径被收窄。如果你也在维护自己的组件库或设计系统可以直接复用该仓库的实践复制 模板按背景—决策—后果三要素填写编号递增、状态明确先以提案形式提交评审——一套低成本、高回报的决策历史保存机制就此建立。【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carbon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 用架构决策记录（ADR）保存设计系统的决策历史：Carbon Design System 的实践
用架构决策记录ADR保存设计系统的决策历史Carbon Design System 的实践【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carbon本文基于 docs/decisions/0001-record-project-decisions.md 展开。随着 Carbon Design System 多年演进围绕各项技术决策的背景与理由逐渐流失该项目于 2025-06-24 正式通过架构决策记录Architecture Decision RecordADR制度来保存这份决策历史。读完本文你将理解 ADR 是什么、Carbon 为何以及如何引入它、其模板与编号原则是什么并能直接依照仓库中的真实模板与流程为设计系统项目撰写和维护属于自己的 ADR。背景为什么 Carbon 需要记录决策在 0001 号决策记录 的 Context 一节中Carbon 团队如实描述了当时的困境随着 Carbon Design System 的持续演进围绕许多决策的上下文context与推理过程reasoning已经丢失。对于一套已包含carbon/react、carbon/web-components、carbon/styles、carbon/icons等十余个包、横跨 React / Web Components / 样式 / 图标 / 工具链的庞大设计系统而言一个组件为什么这样设计、这个入口为什么这样导出的原始动机一旦丢失后续维护者就只能靠猜测或重构代码来还原意图成本极高且容易失真。因此决策记录的首要目标是为自己和未来的维护者保存这条决策历史链。决策正式采用架构决策记录ADR0001 号决策 的 Decision 一节给出了明确结论采用架构决策记录ADR方法论源自 Michael Nygard 的经典文章《Documenting Architecture Decisions》ADR 中直接引用了该文章作为方法依据通过 ADR 记录该项目上做出的高层级决策high level decisions以保存决策历史。该决策的状态被标记为Accepted已接受日期为 2025-06-24。从仓库实际内容看这并非一纸空文——docs/decisions/目录下目前已积累 0000 至 0007 共 8 个文件含 1 个模板覆盖组件通信架构、版本语义、打包契约、Storybook 规范、文档内容标准等多个主题说明该制度已被持续执行。ADR 的文档结构五段式模板ADR 之所以易消化在于模板刻意保持精简。模板文件 定义了固定段落每一条 ADR 只需回答五个问题段落作用模板中的提示Title决策标题一句话概括这条决策Status当前状态如 proposed、accepted、rejected、deprecated、superseded 等Context背景是什么问题促使了这个决策或变更Decision决策内容我们提出/正在做的变更是什么Consequences后果这个变更让哪些事情变得更容易或更困难这个结构与 Michael Nygard 提出 ADR 时的经典骨架一致先讲为什么做Context再讲做了什么Decision最后坦诚代价是什么Consequences。在仓库的真实 ADR 中这一骨架被严格沿用——例如 0004 号utilities 包显式入口 在 Consequences 中同时列出 Positive outcomes 与 Tradeoffs and breaking changes把破坏了哪些深层导入路径这类副作用写得很直白。Carbon 的 ADR 使用原则decisions 目录的 README 进一步明确了运行这套制度的具体原则决策记录原则过程层面ADR 会先以提案proposal形式创建再做出决策提案会先在团队内部以及与相关方充分讨论决策一旦做出就通过更新最初/提案版 ADR来记录如果决策被推翻旧记录予以保留但标记为 superseded已被取代并在新旧记录之间互相添加链接。决策记录原则内容层面ADR按顺序编号号码不重复使用模板只保留少数几个部分保证每份文档易于消化每条 ADR 都应以与未来维护者对话的口吻书写——使用完整句子、按段落组织、行文清晰。从仓库证据看这些原则均有落地00010007 编号连续不重复0006 号Storybook 组织标准 的状态是Proposed演示了先提案、后决策的流程其余多为 Accepted体现了决策后更新 ADR的闭环。实操如何撰写一条新的 ADR根据 README 的 Authoring a decision record 一节在 Carbon 仓库中新增一条 ADR 只需四步复制模板在docs/decisions/目录内复制0000-template.md重命名改名为目录中下一个逻辑序号 决策标题例如0008-xxxx.md填写 ADR按 Title / Status / Context / Decision / Consequences 五个部分填写提交 PR将填写完成的 ADR 通过 Pull Request 提交供团队讨论与评审。这一流程与ADR 先以提案形式出现、经讨论后定稿的原则互相印证——PR 评审本身就是 ADR 讨论环节的载体。仓库中的真实实践00000007 全览截至当前仓库docs/decisions/下的记录已构成一个小型决策档案库每条都是 0001 号决策的活体例证编号决策主题状态0000ADR 模板模板文件—0001采用 ADR 记录项目决策Accepted0002TreeView 组件以 React Context 取代递归透传 propsAccepted0003以preview替代experimental/unstable命名Accepted0004utilities 包采用显式 package entrypointsAccepted0005Story 中使用贴近真实任务的示例内容Accepted0006Storybook 故事组织标准Proposed0007web-components 提供纯类导出与按需注册Accepted其中几条尤其能体现 ADR 的价值0002 号记录了一次架构级重构TreeView/TreeNode 原先通过递归遍历组件树来传递 props存在计算开销大、对包裹组件透传不可靠、难以维护等问题决策改用 React Context API 直接通信用户因此可以把 TreeNode 包进任意数量的自定义包裹组件而不影响父子通信。这条记录保存了为什么不用递归的关键推理未来维护者不必重新踩坑。0004 号记录了构建工具迁移Rollup → tsdown带来的契约变化不再把es/、lib/、types/的原始编译产物当作事实上的公共 API而是通过package.json#exports定义显式入口并约定顶层src/name/index.*即公开子路径pkg/name。它同时明确写下了破坏性后果深层导入es/、lib/、types/的用户会 break。0007 号记录了 web-components v3 的一次重大契约变更把import 即注册的副作用式自注册改为纯类导出 defineCustomElement显式注册并详列了多版本共存、自定义 tag 名、tree-shaking、移除es-custom构建等收益与 v3 破坏性变更。可以看到这些记录并不是流水账而是背景问题 → 决策方案 → 收益与代价的完整推理链正好回扣 0001 号决策中保存决策历史链的初衷。收益与成本采用 ADR 的 Consequences0001 号决策在 Consequences 一节中指向 Nygard 的文章而非自行展开但从仓库的长期运行结果可以推断并印证这套制度的实际收益正面收益上下文不再流失每条决策都自带为什么README 所引的项目生命周期中最难追踪的就是某些决策背后的动机这一问题得到缓解新人/未来维护者友好ADR 按与未来维护者对话的方式书写形成可检索、可引用的决策档案决策可追溯编号连续、状态明确proposed / accepted / superseded被取代的决策也予以保留并互相链接历史完整可查范围聚焦README 明确 ADR 只记录具有架构意义的决策——影响结构、非功能特性、依赖、接口或构建技术的决策避免沦为琐事流水账。潜在成本与约束需要团队持续自律每条 ADR 都要经历提案、讨论、定稿的流程且必须保持编号、模板与写作风格的统一ADR 写得好坏依赖撰写者对什么是架构级决策的判断需要 README 中列举的范畴项目流程、团队流程、设计标准、编码规范、UX 最佳实践、API 设计原则、可访问性方案等作为共同语言。结语如何利用这份决策档案对设计系统维护者而言docs/decisions/ 是理解 Carbon 架构演进的第一手资料对设计系统使用者而言阅读 00020007 等记录能快速掌握各包当前的设计契约及其背后的取舍例如为什么 web-components 现在要求显式注册为什么 utilities 包的导入路径被收窄。如果你也在维护自己的组件库或设计系统可以直接复用该仓库的实践复制 模板按背景—决策—后果三要素填写编号递增、状态明确先以提案形式提交评审——一套低成本、高回报的决策历史保存机制就此建立。【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carbon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考