【免费下载链接】architecture-decision-recordArchitecture decision record (ADR) examples for software planning, IT leadership, and template documentation项目地址https://gitcode.com/gh_mirrors/ar/architecture-decision-record点击查看免费下载导读本文以 architecture-decision-record 开源仓库中 《写好 ADR 的建议德语版》对应英文原文 Suggestions for writing good ADRs为骨架系统讲解一篇合格乃至优秀的 ADR 应该具备哪些特征为什么必须写清“理由Rationale”、为什么要“一事一议Specific”、为什么要“带时间戳Timestamps”、为什么“不可变Immutable”以及 Context 与 Consequences 两个关键章节的写作要点。读完本文你将掌握一套可直接落地的 ADR 写作规范并能在仓库内置的 11 套模板与数十个真实示例中为你的决策选对模板、写好内容、管理好版本演进。什么是“好 ADR”四大核心特征仓库中的建议文档将一篇好 ADR 的特征归纳为四点这也是全仓库所有示例与模板共同遵循的底层约定1. 理由Rationale解释“为什么”好 ADR 必须解释做出该项架构决策AD的原因。这可以包括决策的 Context见下文专门章节不同候选方案的优缺点Pros and Cons功能对比Feature Comparisons成本/收益讨论Cost/Benefit Discussions。仓库中的 Choosing a Database Technology 示例 就是典型示范它在Rationale一节用四条编号理由数据模型灵活演进、水平扩展、高效检索、无需复杂事务逐条说明为什么选择文档型数据库而不是只写一句“我们决定用 MongoDB”。写作 skill 的 writing-guide.md 也把这条概括为解释决策的原因——Context、选项的利弊、功能对比、成本收益而不只是结果。2. 具体Specific一事一议每个 ADR 只应针对一个架构决策AD而不是多个。把多个相互独立的决策塞进同一份文档会让后续的检索、引用和取代都变得混乱。写作 skill 中同样强调“不要将多个架构上不同的决策打包进一个文件如果确实打包了就拆分成独立文件。”仓库中的 文件名约定文档 也印证了这一点每个 ADR 文件对应一个决策主题如choose-database.md、format-timestamps.md、manage-passwords.md、handle-exceptions.md文件名本身就是“一件事”。3. 时间戳Timestamps标注每项内容的写入时间ADR 中每一项内容都应标明其写入时间。这一点对可能随时间变化的方面尤为重要例如成本Costs时间表Schedules扩展规模Scaling供应商条款、定价计划、许可证协议等第三方变化。仓库 Timestamp format 示例 本身就是在解决“时间戳格式”这一决策问题并在Argument中说明“我们重视人类可读/可写胜过原始速度/体积”。而在 Work from home 示例 中文档开头就明确写有Decision Date: July 1, 2021与Decision Maker体现了“决策何时作出、由谁作出”的时间信息价值。4. 不可变Immutable追加而非改写不要修改 ADR 中已有的信息。正确的做法有两种追加Amend在原有 ADR 中补充新信息取代Supersede创建一份新的 ADR 取代旧的。写作 skill 的 SKILL.md 第 6 节给出了取代supersession的标准操作步骤创建描述新决策的新 ADR 文件把旧 ADR 的 Status 更新为Superseded by new-adr在新 ADR 的 Status/Links 区域反向链接Supersedes old-adr。MADR 模板也内置了这种状态流转语法Status: proposed | rejected | accepted | deprecated | … | superseded by [ADR-0005]见 MADR 模板。实践变体说明仓库的 Teamwork advice for ADRs 坦诚指出——理论上不可变是理想的但实践中“可变”对许多团队效果更好把新信息插入既有 ADR附上日期戳并注明“该信息是在决策之后到达的”从而形成一份可共同更新的“活文档”living document。典型的更新触发点包括新队友带来的信息、新的技术选项、实际使用结果、事后第三方变化供应商能力、定价、许可等。写作 skill 的 writing-guide.md 也明确两种约定都可以关键是在同一个项目内保持一致并声明本团队采用的是哪种约定。写好 ADR 的 Context 章节Context背景/上下文是 ADR 中承上启下的部分。原文档给出了三条黄金标准解释你所在组织的处境与业务优先级situation and business priorities而不只是技术问题纳入基于团队社交构成与技能构成的理由与考量social and skills makeups列出相关的优缺点并用与你的需求和目标一致的语言来描述而不是空泛的套话。仓库示例如何落地这三点Choosing a Database Technology 的Context先交代业务处境“设计一个新应用需要以可扩展且高性能的方式存储和检索数据”再分别介绍关系型、文档型、事件型三类数据库的适用场景固定 Schema 事务、无 Schema 水平扩展、事件溯源 审计把候选空间讲清楚Work from home 的Background则把“团队处境”讲透疫情迫使远程办公员工表达了继续远程的意愿——这正是“组织处境与业务优先级”的体现MADR 模板把 Context 细化为Context and Problem Statement建议“用两三句自由形式描述最好把问题表述为一个问题”并单列Decision Drivers驱动力如“一个作用力、一个面临的关切”见 MADR 模板。Alexandrian 模式模板则把 Context 称为Discussion要求“解释在起作用的各类力量技术的、政治的、社会的、项目的”并强调“这是解释我们要解决的问题的故事”见 Alexandrian pattern 模板。写好 ADR 的 Consequences 章节Consequences后果回答“这个决策带来了什么”。原文档的三条要点解释决策之后随之而来的一切影响、结果、产出、后续行动等包含后续 ADR 的信息一个 ADR 常常会触发更多 ADR——当一个 ADR 作出一个大的、全局性的选择时往往会产生一系列更小决策的需求包含复盘after-action review流程团队通常在决策一个月后复审每个 ADR将 ADR 中的信息与实践中实际发生的情况对比以便学习与成长。仓库中的证据Timestamp format 示例 的Implications一节直接写道“我们的各类文本系统与时间系统将收敛到这一格式”其Related decisions又指出“我们可能还想要一种快速简便的方式来跟踪时间增量duration用 Unix epoch 时间戳很容易实现”——这正是“一个决策引发后续决策”的活例子Work from home 的Implications列举了持续沟通协调、调整工作流程与协议、确保设备工具资源到位等连锁影响Nygard 模板把 Consequences 定义为“由于这个变化什么事情变得更容易或更困难”见 Nygard 模板——要求正反两面都写写作 skill 的 writing-guide.md 进一步建议既要写“什么变得更容易”也要写“什么变得更困难”并点名那些这个决策现在要求的后续 ADR。新 ADR 取代旧 ADR版本演进的正确姿势原文档最后一条规则是当一项决策取代或使先前的 ADR 失效时应创建一份新的 ADR。结合仓库完整的操作流是为“新决策”新建一份 ADR 文件按仓库的 文件名约定 命名现在时祈使短语、小写加连字符、.md扩展名若项目按序号编号则加零填充序号如0007-choose-database.md把旧 ADR 的状态改为Superseded by 新文件路径在新 ADR 中反向标注Supersedes 旧文件路径全程不动旧 ADR 的原始正文——这正是“不可变”原则的落地。这套机制在仓库的模板层已有内建支持Nygard 模板的Status字段、MADR 模板的superseded by语法、Alexandrian 模板的Consequences“长期来看结果如何是否有效、是否失败、是否被更改、是否升级”都服务于同一个演进模型。为你的决策选对模板仓库 11 套模板速查写作 skill 的 SKILL.md 提供了一张“场景 → 模板”对照表可以直接指导写作你的场景推荐模板默认 / 大多数团队 / 不确定NygardTitle、Status、Context、Decision、Consequences想要轻量级的“选项 优缺点”MADR企业级需要追溯到需求/原则Tyree Akerman快速获得高管批准库、模型、CI 策略ITD重要技术决策供应商/工具选型成本、SWOT、利益相关方意见Business case想要一段式“Y-statement”摘要 叙事Alexandrian pattern需要正式、可测试的非功能需求语言Planguage匹配 EdgeX Foundry 约定EdgeX完整架构文档ADR 只是其中一节arc42§9想要轻量红绿灯式选项对比表Gareth Morgan想要“选项 → 选项分析 → 推荐”叙事流GIG Cymru NHS Wales所有模板的完整骨架均位于 locales/en-001/templates/ 目录其中Nygard 模板 最为简单流行只有四个章节Tyree Akerman 模板 最为详尽包含 Issue、Decision、Status、Group、Assumptions、Constraints、Positions、Argument、Implications、Related decisions、Related requirements、Related artifacts、Related principles、Notes 共 14 个字段——其中Positions要求列出你考虑过的所有可行方案“你不希望在最终评审时听到‘你们想过……吗’”Argument说明为什么选中某一方案“这大概和决策本身一样重要”Implications明确指出“一个决策可能引入做出其他决策的需求”Alexandrian pattern 模板 提供了经典的总结句式In the context of用例facing关切we decided for选项to achieve质量accepting代价。当你不确定时写作 skill 的建议是默认选 Nygard——它最简单、最广为人知、无需任何工具即可让团队上手。把好 ADR 放进 git命名、目录与工具链仓库 README 与 how-to-start-using-ADRs-with-git 给出的最小工作流是# 1. 为 ADR 文件建目录 mkdir adr # 2. 为每个决策创建文本文件如 choose-database.md vi choose-database.md # 3. 写入内容可参考本仓库模板 # 4. 提交到 git 仓库配合 文件名约定 的规范文件名使用现在时祈使动词短语choose-database.md提升可读性并与提交信息格式保持一致使用小写与连字符兼顾可读性与系统可用性扩展名统一为markdown便于格式化。仓库还随附两个 Claude Code 技能位于 skills/ 目录让 AI 编程助手可以按本项目的推荐方式编写与维护 ADRarchitecture-decision-record-skill通用技能帮助判断某决策是否需要 ADR、建立adr/或decisions/目录、命名文件、从 11 套模板中挑选骨架、写出扎实的 Context/Decision/Consequencesarchitecture-decision-record-maintainer-skill面向本仓库维护者记录仓库布局与新增模板/示例/工具链接的流程。此外写作 skill 的 writing-guide.md 还提供了几个可选的进阶机制ADR 生命周期Initiating → Researching → Evaluating → Implementing → Maintaining → Sunsetting、阶段推进的验收标准问题问题是否清晰备选方案是否真的考虑过权衡是否充分理解并记录相关上下文与利益相关方是否到位反馈是否已纳入、角色与责任proposer / researcher / evaluator / reviewer / approver / maintainer简单版是每个 ADR 指定主联系人、次联系人、责任团队、以及“fitness functions”——用 CI 中自动化的客观检查来保证决策被持续遵守例如决策“我们使用事件溯源以满足审计需求”对应的 fitness function 就是“CI 断言所有状态变更都必须产生事件”。结语用“四大特征 两大章节 一套演进机制”武装你的 ADR回到原点这篇 《写好 ADR 的建议》及其 德语版所传递的写作心法可以压缩为一句话写清楚理由、只写一个决策、给易变信息盖时间戳、不改写历史而用追加或取代同时把 Context 写成“组织处境 团队构成 贴合目标的利弊”把 Consequences 写成“正反影响 后续 ADR 复盘机制”。无论你选用仓库中的哪一套模板Nygard、MADR、Tyree Akerman、Alexandrian……只要守住这四条特征与两个章节的写作标准你的 ADR 就能在数年后依然被新加入的开发者准确理解——这正是 architecture-decision-record 仓库想要推广的“记录决策更记录为什么”的实践价值所在。赞分享【免费下载链接】architecture-decision-recordArchitecture decision record (ADR) examples for software planning, IT leadership, and template documentation项目地址https://gitcode.com/gh_mirrors/ar/architecture-decision-record点击查看免费下载相关推荐写出高质量架构决策记录ADRarchitecture-decision-record 仓库的写作建议与实践指南写出高质量架构决策记录ADRarchitecture decision record 仓库的写作建议与实践指南 架构决策记录Architecture D电视盒子变 Linux 服务器Armbian 移植实操指南电视盒子变 Linux 服务器Armbian 移植实操指南 amlogic s9xxx armbian 是一个开源项目可以把 Armbian基于 DebiDORA 节点间 CUDA 零拷贝延迟基准examples/cuda-benchmark 安装、运行与源码剖析DORA 节点间 CUDA 零拷贝延迟基准examples/cuda benchmark 安装、运行与源码剖析 本篇技术指南以 DORA 仓库中 exampl上一篇7个高效NLP工具链推荐从零开始掌握自然语言处理实战技巧下一篇BililiveRecorder命令行版深度使用服务器部署和自动化录制终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考