【免费下载链接】architecture-decision-recordArchitecture decision record (ADR) examples for software planning, IT leadership, and template documentation项目地址https://gitcode.com/gh_mirrors/ar/architecture-decision-record点击查看免费下载在软件架构演进中谁在何时、因何原因、做出了什么决定往往比代码本身更值得留存。本篇指南以 AWS Prescriptive Guidance 的 ADR Process 为核心骨架仓库中收录于 locales/en-001/documents/aws-adr-process/系统讲解架构决策记录Architecture Decision Record, ADR的定义、适用范围、内容结构与完整生命周期并借助 architecture-decision-record 仓库中收录的 11 套模板与 41 个实战示例给出可直接复用的落地方法。读完本文你将能够为团队设计一套从提出 → 评审 → 采纳/拒绝 → 取代全流程闭环的决策日志体系并让 ADR 与代码评审、git 工作流无缝衔接。什么是 ADR 与决策日志Decision LogADRArchitecture Decision Record是一种用于记录团队在软件架构规划中做出的重要选择的文档。每份 ADR 描述三件事决策本身、决策所处的上下文Context、以及决策带来的后果Consequences。ADR 具有状态state因此会经历一个生命周期lifecycle。ADR 流程的产出是一组架构决策记录的集合这个集合构成了决策日志Decision Log。决策日志承载了两层价值项目上下文成员通过浏览每份 ADR 的标题即可快速获得项目全局概览实现与设计细节成员深入阅读具体 ADR可以理解项目实现和设计选择背后的原因。仓库根目录的 README.md 对核心概念给出了更精炼的定义架构决策AD为满足重要需求而做出的软件设计选择架构决策日志ADL为某个项目或组织创建和维护的全部 ADR 的集合架构显著需求ASR对软件系统架构产生可度量影响的需求上述概念共同归属于**架构知识管理AKM**范畴。不可变性Immutability是 ADR 流程最重要的原则之一当团队采纳accept一份 ADR 后它就变为不可变文档。如果后续出现新的洞察需要改变决策团队不能直接修改原 ADR而是要提出一份新 ADR新 ADR 被采纳后将取代supersede旧 ADR。这一原则保证了决策日志作为历史档案的可靠性任何人都无法篡改已经定案的决策。ADR 流程的适用范围Scope并非所有决定都需要写成 ADR。团队应当为每一个具有架构显著性architecturally significant的决策创建 ADR。参照 Richards 与 Ford2020的经典分类覆盖范围包括类别典型内容结构Structure架构模式例如微服务、分层、事件驱动等非功能需求Non-functional requirements安全性、高可用性、容错性依赖关系Dependencies组件之间的耦合程度接口InterfacesAPI 与对外发布的契约构建技术Construction techniques库、框架、工具与过程在实际项目中功能需求与非功能需求是 ADR 流程最常见的输入。仓库中的示例正是对这一范围的生动诠释例如 choosing-a-database-technology 示例 对应依赖与结构类决策amazon-web-services 示例 与 microsoft-azure-cloud-infrastructure 示例 对应云基础设施选型continuous-integration 示例 对应构建技术/过程类决策secrets-storage 示例 则同时覆盖安全性与工具选型两个维度。ADR 应包含的内容Context、Decision、Consequences当团队识别出需要一份 ADR 时成员应基于项目级模板开始撰写。模板的作用是简化创建过程并确保 ADR 捕获全部相关信息。一份 ADR至少要定义三个部分决策的上下文Context是什么问题/场景推动了这次决策决策本身Decision团队做出的具体选择决策的后果Consequences该决策对项目及其交付物带来的影响。ADR 结构最有价值的一点在于它聚焦于为什么做这个决定而不是团队如何实现它。理解决策背后的原因一方面让其他团队成员更容易接受并采纳该决策另一方面也阻止了未参与决策过程的架构师在将来轻易推翻它。仓库 locales/en-001/documents/suggestions-for-writing-good-adrs/ 对好 ADR给出了更细的写作标准Rationale理由充分解释做此决策的原因可包含上下文、各候选方案的利弊、特性对比、成本/收益讨论等Specific主题单一每份 ADR 只讨论一个架构决策不混杂多个决策Timestamps带时间戳标明每项内容的撰写时间这对成本、进度、规模等随时间变化的要素尤为重要Immutable不可变不修改已有信息需要补充时通过新增信息修订需要变更时通过创建新 ADR取代。好的 Context 段落应当说明组织现状与业务优先级、基于团队人员构成与技能构成的理由和考量、以及与团队需求目标一致的利弊分析好的 Consequences 段落则应说明决策带来的影响、产出与后续行动包括由此触发的后续 ADR一个大的顶层决策往往会催生多个更小的决策以及事后复盘安排——例如在决策一个月后回顾 ADR 内容与实际运行情况的差异用于团队学习成长。ADR 采纳流程Adoption Process所有权Ownership定义每位团队成员都可以创建 ADR但团队必须为每份 ADR 建立所有权定义。ADR 作者作为所有者Owner应当主动维护和沟通 ADR 内容。其他成员可以随时为 ADR 做贡献但在 ADR 被团队采纳之前内容变更需经所有者批准。状态机Proposed → Accepted / Rejected完整的采纳流程围绕 ADR 状态展开Proposed提议团队识别出架构决策并确定所有者后所有者将 ADR 置于 Proposed 状态此时 ADR 处于待评审状态随时可被审查。发起评审所有者启动 ADR 评审流程。评审的目标是让团队做出三种决定之一采纳accept、需要返工rework或拒绝reject。评审会议项目团队含所有者共同评审。评审会议应安排专门的阅读时段平均 1015 分钟足够。在此期间每位成员阅读文档通过评论和提问标记不清晰的主题阅读阶段结束后由所有者逐条宣读并与团队讨论每条评论。返工如果团队发现了改进行动点action pointsADR 状态保持 Proposed。所有者负责制定行动项并与团队协作为每个行动项指定负责人assignee。任何成员都可以贡献并解决行动点重新安排评审流程是所有者的责任。拒绝团队也可以决定拒绝 ADR。此时所有者需要补充拒绝理由以避免将来就同一主题再次引发讨论并将 ADR 状态改为Rejected。采纳如果团队批准 ADR所有者需要补充时间戳timestamp、版本号version和利益相关者清单stakeholders然后将状态更新为Accepted。由此可以看出 ADR 状态在采纳流程中的完整流转Proposed ──(评审通过)──→ Accepted补充时间戳、版本、利益相关者清单 │ ├──(发现行动点)──→ 保持 Proposed制定行动项并重新评审 └──(评审拒绝)──→ Rejected补充拒绝理由决策日志的持续使用ADR 及其形成的决策日志代表团队做出的决策并提供了全部决策的历史。团队应尽可能在代码评审与架构评审中以 ADR 为参考依据除了执行代码评审、设计任务与实现任务之外成员还应就产品的战略决策咨询 ADR。ADR 评审流程Review Process与不可变性评审流程是 ADR 生命周期中保障质量的核心环节其要点如下不可变文档ADR 被采纳或拒绝之后团队都应将其视为不可变文档变更必须新建对已有 ADR 的修改需要创建新 ADR、为新 ADR 建立评审流程并批准它状态取代如果新 ADR 获批所有者应将旧 ADR 的状态改为Superseded已取代。这一追加而非修改的机制使得决策日志天然成为一份可审计的决策历史任何决策的演进都能通过 Superseded 链追溯到源头。仓库中的模板对状态取值给出了更丰富的约定例如 MADR 模板decision-record-template-of-the-madr-project的状态字段为proposed | rejected | accepted | deprecated | … | superseded by [ADR-0005]EdgeX 模板decision-record-template-by-edgex的变更日志则使用pending, approved, amended, deprecated四态并强制要求记录状态、日期与 PR 链接。与代码评审的结合作为良好实践每次软件变更都应经过同行评审peer review并要求至少一个批准。在代码评审过程中评审者可能会发现某些变更违反了一份或多份 ADR此时评审者应要求代码作者更新代码并分享该 ADR 的链接作为依据作者更新代码后经同行评审者批准再合并进主代码库。这一机制让 ADR 从文档真正变成代码变更的守门人。从流程到实践仓库中的模板与示例仓库在 locales/en-001/templates/ 收录了 11 套业界主流 ADR 模板在 locales/en-001/examples/ 收录了 41 个实战示例可以直接对照使用模板特点与适用场景Michael Nygard 模板最经典的四段式Status / Context / Decision / Consequences简单流行适合快速上手Jeff Tyree Art Akerman 模板更精细含 Issue、Positions、Argument、Implications、Related requirements 等十余个字段适合大型企业级决策MADR 项目模板含 Context and Problem Statement、Decision Drivers、Considered Options、Pros and Cons强调候选方案对比arc42 模板完整覆盖 Introduction、Constraints、Context、Runtime/Deployment View、Quality Requirements 等 11 个部分适合需要全量架构文档的场景EdgeX 模板面向开源基金会含 Submitters、Change Log、Referenced Use Cases、Proposed Design、Considerations、Governance 等Important Technical DecisionsITD模板精简的决策优先模板The Problem / Options Considered / Rationale / Notes适合快速高管评审Alexandrian pattern 模板简单且强调上下文细节Business case 模板偏 MBA 视角含成本、SWOT 等Planguage 模板偏质量保障quality assurance视角以 Nygard 模板为例一个最小可用 ADR 的骨架如下完整版见 choosing-a-database-technology 示例# Architecture Decision Record: Choosing a Database Technology ## Status Accepted ## Context We are designing a new application that requires storing and retrieving data in a scalable and performant manner... ## Decision After carefully evaluating the requirements and constraints of our application, we have decided to use a document database. ## Consequences By choosing a document database, we will need to invest in learning and understanding the specific technology... !-- 含正面与负面后果 --仓库中的 amazon-web-services 示例 则展示了另一套实用结构Decision / Background / Considerations / Consequences / Ownership / Review其中Ownership明确云基础设施团队负责保障有效使用与管理相关风险Review约定决策将每年复审一次——这与 AWS 流程中所有者维护 事后复盘的思想完全呼应。落地建议结合 git 工作流与文件命名规范将 ADR 流程落实到日常开发推荐使用 git 管理每个 ADR 文件。仓库 locales/en-001/documents/file-name-conventions-for-adrs/ 给出了可直接采用的命名约定文件名采用现在时祈使动词短语例如choose-database.md、format-timestamps.md、manage-passwords.md、handle-exceptions.md可读性好且与 commit message 格式一致使用小写字母与连字符与仓库本身一致兼顾可读性与系统可用性扩展名使用 markdown便于排版。典型操作流程# 1. 为 ADR 文件创建目录 $ mkdir adr # 2. 为每个 ADR 创建文本文件 $ vi adr/choose-database.md # 3. 参考仓库模板撰写 Context / Decision / Consequences # 4. 提交到 git 仓库 $ git add adr/choose-database.md $ git commit -m add ADR: choose database至此一套完整的 ADR 流程闭环即可运转成员基于模板撰写 ADRProposed→ 团队评审1015 分钟阅读 逐条讨论→ 返工或拒绝保持 Proposed / Rejected 拒绝理由→ 采纳补充时间戳、版本与利益相关者清单进入 Accepted→ 后续变更通过新 ADR 取代旧 ADRSuperseded并让 ADR 在代码评审中作为决策依据持续发挥作用。仓库的 README.md 还收录了 ADR 与代码变更结合的工具生态如失败 PR 的决策护栏、AI 编码代理的决策维护技能等可作为进一步自动化的参考方向。赞分享【免费下载链接】architecture-decision-recordArchitecture decision record (ADR) examples for software planning, IT leadership, and template documentation项目地址https://gitcode.com/gh_mirrors/ar/architecture-decision-record点击查看免费下载相关推荐架构决策记录全流程实战基于 AWS ADR 流程的状态机、评审机制与决策日志落地指南架构决策记录全流程实战基于 AWS ADR 流程的状态机、评审机制与决策日志落地指南 导读 本文以 AWS 官方规范性指南Prescriptive GuidAtlantis 架构决策记录ADR实践指南从决策流程到 API 增强与漂移检测的实现落地Atlantis 架构决策记录ADR实践指南从决策流程到 API 增强与漂移检测的实现落地 本文以 Atlantis 仓库 docs/adr/ 目录下的架DevOpsCI/CD基础设施Semantic Kernel 架构决策记录ADR体系基于 MADR 模板的跨语言决策流程与实践Semantic Kernel 架构决策记录ADR体系基于 MADR 模板的跨语言决策流程与实践 本文深入解析 Semantic Kernel 项目用于管人工智能大模型AI AgentAgent 框架多智能体RAG上一篇对比实验Score-Entropy-Discrete-Diffusion与传统离散扩散模型的性能差异下一篇零成本起步5款免费云服务 免费额度横评盘点创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考