【免费下载链接】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 RecordADR是一份描述团队在计划构建的软件架构中就某个重要方面所作出的选择的文档每一份 ADR 都完整记载架构决策本身、其背景Context与其后果Consequences。本文以本仓库孟加拉语bn-001与英文en-001版本同步收录的 AWS-এ আর্কিটেকচার সিদ্ধান্ত রেকর্ডের প্রক্রিয়াAWS ADR 流程 为核心结合仓库内 11 套决策记录模板与数十个实战示例完整拆解 AWS 推荐的 ADR 生命周期——从 Proposed提议、Accepted采纳、Rejected拒绝到 Superseded取代——并给出可直接套用的状态流转、所有权约定与评审会议操作规范。读完本文你将能够为团队建立一套不依赖特定工具、可在 git 仓库中落地执行、且与代码评审流程深度联动的架构决策记录体系。ADR 流程的产出决策日志Decision LogADR 流程的最终产物不是单份文档而是一系列架构决策记录的集合这个集合构成团队的决策日志decision log。决策日志同时承载两种价值项目背景的快速概览项目成员通过浏览每份 ADR 的标题即可快速掌握项目上下文的全貌实现与设计细节的深度追溯需要深入了解时成员按需阅读对应 ADR 正文获取实现方案与设计选择的详细依据。本仓库正是这种决策日志理念的完整示范README.md 作为总索引按 Templates11 套模板、Examples数十个示例、Documents12 篇方法论文档组织内容并提供了面向多语言30 locale的翻译镜像例如本主题的英文源文位于 locales/en-001/documents/aws-adr-process/README.md中文版本位于 locales/zh-001/文档/aws架构决策记录流程/即同一套 ADR 流程文档在不同语言团队中的同步呈现。不可变原则被采纳的 ADR 永不修改AWS 流程中最关键的一条纪律是当团队采纳accept一份 ADR 后它就变得不可变immutable。若出现新的洞察要求作出不同决策团队的正确做法不是回头编辑旧 ADR而是提出一份新的 ADR走完整的评审流程新 ADR 被采纳后取代supersede旧 ADR。这一原则在本仓库的模板中有直接体现。例如 MADR 项目决策记录模板 在 Status 行中预留了 superseded by [ADR-0005] 的写法并在 Links 一节提供 Refined by ADR-0005 的关联方式撰写优质 ADR 的建议 中也明确区分了两种演进方式通过追加新信息来修订amendADR或通过创建新 ADR来取代supersede旧 ADR而绝不允许改动既有内容。ADR 流程的范围什么决策值得记录并非所有决定都需要写 ADR。项目成员应当为每一个影响软件项目或产品的架构级重要决策创建 ADRAWS 指南引述 Richards and Ford 2020给出了五类典型范围类别说明典型示例结构Structure架构模式等结构性选择是否采用微服务microservices模式非功能性需求Non-functional requirements安全、高可用、容错等质量属性高可用架构、故障容错设计依赖Dependencies组件之间的耦合关系模块边界与耦合度约定接口InterfacesAPI 与对外发布的契约REST API 命名规范、gRPC 契约构建技术Construction techniques库、框架、工具与流程选用哪些库、框架与工程流程其中功能性与非功能性需求是 ADR 流程最常见的输入。本仓库的示例目录locales/en-001/examples/几乎逐一覆盖了上述类别如 API 使用 JSON 还是 gRPC 属于接口决策选择数据库技术 属于结构决策指标、监控与告警 属于非功能性需求决策——它们可作为判断是否该写 ADR的现成参考样例。ADR 的内容构成Context、Decision、Consequences当团队识别出需要一份 ADR 时成员应基于项目级统一模板开始撰写。模板的价值在于简化 ADR 的创建过程并确保 ADR 捕获所有相关信息。AWS 流程规定每份 ADR至少应包含三要素决策的背景context of the decision为什么会面对这个问题决策本身the decision团队选择了什么决策对项目及其交付物的后果consequences作出该选择后哪些事情变得更容易或更困难。ADR 结构最强大的地方在于它聚焦为什么作此决策而非团队如何实现。理解了决策的动机其他团队成员更容易接受并遵循该决策而未参与决策过程的架构师也无法在将来轻易推翻它。本仓库为这三要素提供了多个粒度不同的模板实现Michael Nygard 模板最简版本只有 Status / Context / Decision / Consequences 四个小节适合快速记录Jeff Tyree 与 Art Akerman 模板来自 Capital One更精细包含 Issue、Assumptions、Constraints、Positions、Argument、Implications、Related decisions、Related requirements、Related artifacts、Related principles、Notes 共 11 个字段其中Argument论证被认为与决策本身同等重要而 Positions 一节要求显式列出所有被考虑过的备选方案ITD重要技术决策模板面向快速高管评审的决策优先decision-first形态用 The Problem / Options Considered / Rationale / Notes 四段压缩评审负担。一个完整的实战示例可见 Amazon Web Services 架构决策记录其结构包含 Decision、Background、Considerations、Consequences、Ownership、Review——其中 Ownership 与 Review 两个小节正是 AWS 流程中所有权与定期复审思想的具体化。ADR 采纳流程从 Proposed 到 Accepted / RejectedAWS 为 ADR 定义了一条清晰的状态机路径完整状态流转如下Proposed提议──► 评审 ──► Accepted采纳不可变 │ │ │ └──► Rejected拒绝不可变 │ └──► 需要返工保持 Proposed补充行动项后重新评审 被取代后Superseded取代标记旧 ADR第一步确立所有权ownership任何团队成员都可以创建 ADR但团队应当为每份 ADR 确立明确的所有权定义。作为所有者的作者需要主动维护 ADR 内容并持续沟通在团队采纳 ADR 之前若 ADR 内容发生变化由所有者审批这些变更其他成员可随时向 ADR 贡献内容。第二步以 Proposed 状态提交团队识别出架构决策及其所有者后所有者将 ADR 以Proposed提议状态提交进入评审就绪阶段。第三步发起评审评审的目标是决定三件事之一采纳accept、需要返工rework或拒绝reject。评审由包括所有者在内的项目团队共同进行操作规范如下评审会议应预留专门的阅读时段平均1015 分钟即可完成通读期间每位成员阅读文档并以评论与提问标记不清晰的主题阅读阶段结束后所有者逐条朗读并讨论每一条评论。第四步三种评审结论的处理评审结论ADR 状态处理所有者动作需要返工发现改进行动项保持Proposed将行动项转化为任务与团队协作给每项任务指派负责人assignee并负责重新安排评审拒绝改为Rejected记录拒绝原因避免未来就同一主题重复讨论采纳改为Accepted补充时间戳timestamp、版本号version与利益相关者stakeholders名单ADR 与代码评审的联动让决策真正被执行ADR 与决策日志代表了团队作出的全部决策并提供了所有决策的历史记录。AWS 指南强调了两条落地实践代码与架构评审时以 ADR 为参考依据除执行代码评审、设计任务与实现任务外团队成员在做产品级战略决策时应查阅 ADR变更必须经同行评审并至少获得一人批准若评审者在代码评审中发现某次代码变更违反了一份或多份 ADR评审者应要求作者更新代码并分享该 ADR 的链接作为依据作者更新代码后经同行评审者批准再合入主代码库。本仓库对决策如何作为代码被持续守护还提供了更自动化的思路将决策作为代码的适应度函数 一文阐述了用编程代码编写客观的自动检查fitness functions来验证决策是否被持续遵守——例如采用事件溯源以满足审计要求的决策对应CI 服务器测试所有状态变更必须产生事件的适应度函数。这套机制可以把 AWS 流程中评审时查阅 ADR的强依赖转化为可持续的自动校验。ADR 评审流程接受或拒绝之后一旦团队采纳或拒绝了某份 ADR它都应被视为不可变文档immutable document。对既有 ADR 的修改必须遵循以下链条创建一份新的 ADR为这份新 ADR 建立评审流程并完成评审批准新 ADR由所有者将旧 ADR 的状态改为 Superseded取代。这也解释了为什么 MADR 模板 的 Status 行需要预留 superseded by [ADR-0005] 这样的反向链接——它让决策日志形成可追溯的演进链任何阅读者都能从当前决策一路回溯到最初的选择及其背景。在 git 仓库中落地 AWS ADR 流程AWS 流程本身不绑定任何工具而本仓库的 README 与 如何通过 git 开始使用 ADR 给出了最常用的落地方式——用纯文本文件 git 版本控制管理 ADR# 1. 为 ADR 文件创建独立目录 mkdir adr # 2. 为每份 ADR 创建一个文本文件如 choose-database.md vi adr/choose-database.md # 3. 依据仓库内的模板撰写内容Context / Decision / Consequences # 4. 提交到 git 仓库随代码演进保留完整决策历史 git add adr/choose-database.md git commit -m Add ADR: choose database仓库建议的文件命名约定为现在时祈使动词短语 小写连字符 .md 扩展名例如choose-database.md、format-timestamps.md、manage-passwords.md这既保证了可读性也与常规 commit message 格式保持一致。若希望借助 AI 辅助写作 ADR仓库还内置了两套 Claude Code skillarchitecture-decision-record-skill面向任何项目帮助判断是否需要 ADR、初始化 adr/ 目录、选择模板并撰写合格的 Context/Decision/Consequences 章节与 architecture-decision-record-maintainer-skill面向本仓库维护者涵盖仓库布局与 locales 镜像约定将 skill 目录复制到目标仓库的.claude/skills/后即可使用。总结AWS 架构决策记录流程的本质是围绕决策不可变、演进靠取代这一核心纪律建立一套由 Proposed → Accepted / Rejected → Superseded 构成的生命周期管理体系。落到实践中它要求团队为架构级重要决策结构、非功能性需求、依赖、接口、构建技术记录背景与后果为每份 ADR 明确所有者并走通通读 1015 分钟 → 逐条讨论评论 → 决定采纳/返工/拒绝的评审节奏在代码与架构评审中把 ADR 当作权威参考当决策需要变更时永远用新 ADR 取代旧 ADR 而非改写历史。本仓库 locales/en-001/ 下的模板与示例为这套流程提供了立即可用的素材而 README.md 则是搭建团队决策日志的最佳起点。赞分享【免费下载链接】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 Guid架构决策记录ADR全生命周期实战从 Proposed 到 Superseded 的 AWS 决策流程指南架构决策记录ADR全生命周期实战从 Proposed 到 Superseded 的 AWS 决策流程指南 本文以 architecture decisio用 ADR 记录架构决策Fleet 的架构决策记录体系与实战指南用 ADR 记录架构决策Fleet 的架构决策记录体系与实战指南 Architectural Decision Records架构决策记录简称 ADR是后端前端企业应用运维网络安全上一篇SearXNG 企业级部署方案高可用性和负载均衡配置终极指南下一篇推荐项目Heroku Buildpack for Python —— 打造无缝部署的Python应用体验创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考