Project Icon

architecture-decision-record

系统化记录和管理软件架构决策的框架

architecture-decision-record项目为软件开发团队提供了一个系统化记录和管理架构决策的框架。它包括ADR的定义、实施指南、文件命名规则、编写建议和多种模板。该项目有助于团队捕捉、共享和追踪关键架构决策,增强项目透明度和可维护性。ADR的应用能够优化架构知识管理,使决策过程更加清晰和合理。该项目还提供了多种ADR模板和实际案例,涵盖了从简单到复杂的各种决策场景。它强调了ADR在团队协作中的重要性,并给出了实施ADR的实用建议。项目还包括了丰富的参考资源,有助于深入理解和应用ADR概念。

架构决策记录 (ADR)

架构决策记录 (ADR) 是一份文档,记录了重要的架构决策及其上下文和后果。

内容:

模板:

示例:

更多语言的翻译

什么是架构决策记录?

架构决策记录 (ADR) 是一份文档,记录了重要的架构决策及其上下文和后果。

架构决策 (AD) 是一个解决重要需求的软件设计选择。

架构决策日志 (ADL) 是为特定项目(或组织)创建和维护的所有 ADR 的集合。

架构上重要的需求 (ASR) 是对软件系统架构有可衡量影响的需求。

所有这些都属于架构知识管理 (AKM) 的范畴。

本文档的目标是提供 ADR 的快速概览,如何创建它们,以及在哪里查找更多信息。

缩写:

  • AD: 架构决策

  • ADL: 架构决策日志

  • ADR: 架构决策记录

  • AKM: 架构知识管理

  • ASR: 架构上重要的需求

如何开始使用 ADR

要开始使用 ADR,请与您的团队成员讨论以下方面。

决策识别:

  • AD 有多紧急和重要?

  • 必须现在做出决定,还是可以等到了解更多信息后再决定?

  • 个人和集体经验,以及公认的设计方法和实践,都可以帮助进行决策识别。

  • 理想情况下,维护一个决策待办事项列表,作为产品待办事项列表的补充。

决策制定:

  • 存在许多决策制定技术,既有一般性的,也有特定于软件架构的,例如对话映射。

  • 群体决策是一个活跃的研究课题。

决策实施和执行:

  • AD 用于软件设计;因此必须与资助、开发和运营系统的利益相关者进行沟通并获得他们的接受。

  • 架构明显的编码风格和关注架构问题和决策的代码审查是两种相关的做法。

  • 在软件演进中现代化软件系统时,也必须(重新)考虑 AD。

决策共享(可选):

  • 许多 AD 在项目之间重复出现。

  • 因此,当采用明确的知识管理策略时,过去决策的经验,无论好坏,都可能成为有价值的可重用资产。

决策文档:

  • 存在许多决策捕获的模板和工具。

  • 参见敏捷社区,例如 M. Nygard 的 ADR。

  • 参见传统软件工程和架构设计流程,例如 IBM UMF 和 CapitalOne 的 Tyree 和 Akerman 建议的表格布局。

更多信息:

如何使用工具开始使用 ADR

您可以按照自己的意愿开始使用带工具的 ADR。

例如:

  • 如果您喜欢使用 Google Drive 和在线编辑,那么您可以创建一个 Google 文档或 Google 表格。

  • 如果您喜欢使用源代码版本控制,如 git,那么您可以为每个 ADR 创建一个文件。

  • 如果您喜欢使用项目规划工具,如 Atlassian Jira,那么您可以使用该工具的规划跟踪器。

  • 如果您喜欢使用 wiki,如 MediaWiki,那么您可以创建一个 ADR wiki。

如何使用 git 开始使用 ADR

如果您喜欢使用 git 版本控制,那么以下是我们如何为典型的带有源代码的软件项目开始使用 git 的 ADR。

创建 ADR 文件的目录:

$ mkdir adr

为每个 ADR 创建一个文本文件,例如 database.txt:

$ vi database.txt

在 ADR 中写任何您想写的内容。参考本仓库中的模板获取想法。

将 ADR 提交到您的 git 仓库。

ADR 的文件名约定

如果您选择使用典型的文本文件创建 ADR,那么您可能想要制定自己的 ADR 文件名约定。

我们更喜欢使用具有特定格式的文件名约定。

示例:

  • choose-database.md

  • format-timestamps.md

  • manage-passwords.md

  • handle-exceptions.md

我们的文件名约定:

  • 名称使用现在时祈使动词短语。这有助于可读性,并与我们的提交消息格式相匹配。

  • 名称使用小写字母和破折号(与本仓库相同)。这是可读性和系统可用性的平衡。

  • 扩展名是 markdown。这对于轻松格式化很有用。

编写优秀 ADR 的建议

优秀 ADR 的特征:

  • 理由:解释做出特定 AD 的原因。这可以包括上下文(见下文)、各种潜在选择的利弊、功能比较、成本/收益讨论等。

  • 具体:每个 ADR 应该只涉及一个 AD,而不是多个 AD。

  • 时间戳:标识 ADR 中每个项目的编写时间。这对于可能随时间变化的方面尤为重要,如成本、时间表、扩展等。

  • 不可变:不要更改 ADR 中的现有信息。相反,通过添加新信息来修改 ADR,或通过创建新的 ADR 来取代它。

ADR 中优秀"上下文"部分的特征:

  • 解释您组织的情况和业务优先事项。

  • 根据您团队的社会构成和技能组成,包含理由和考虑因素。

  • 包含相关的利弊,并用符合您需求和目标的术语描述它们。

ADR中良好的"结果"部分的特征:

  • 解释做出决定后会发生什么。这可以包括影响、结果、输出、后续行动等。

  • 包含任何后续ADR的信息。一个ADR触发更多ADR需求是比较常见的,比如当一个ADR做出一个大的总体选择时,进而产生更多较小决策的需求。

  • 包含任何事后审查流程。团队通常会在一个月后审查每个ADR,将ADR信息与实际情况进行比较,以便学习和成长。

新的ADR可能会取代先前的ADR:

  • 当做出的AD取代或使先前的ADR无效时,应创建新的ADR

ADR示例模板

我们在网上收集的ADR示例模板:

ADR的团队合作建议

如果您正在考虑在团队中使用决策记录,以下是我们通过与多个团队合作学到的一些建议。

您有机会引导您的团队成员,通过一起讨论"为什么",而不是强制规定"什么"。例如,决策记录是团队思考更明智、沟通更好的一种方式;如果决策记录只是事后强制的文书工作要求,那就没有价值。

一些团队更喜欢使用"decisions"这个名称,而不是缩写"ADRs"。当一些团队使用"decisions"作为目录名时,就好像灯泡亮了,团队开始在目录中放入更多信息,如供应商决策、规划决策、调度决策等。所有这些类型的信息都可以使用相同的模板。我们假设人们用词("decisions")比用缩写("ADRs")学习更快,而且当去掉"record"一词时,人们更有动力写工作进展文档,此外一些开发人员和一些管理人员不喜欢"architecture"这个词。

理论上,不可变性是理想的。实践中,可变性对我们的团队更有效。我们在现有ADR中插入新信息,加上日期戳,并注明该信息是在决策之后到达的。这种方法会导致一个我们都可以更新的"活文档"。典型的更新是当我们通过新队友、新产品、我们使用的实际结果,或事后第三方变化(如供应商能力、定价计划、许可协议等)获得信息时。

更多信息

介绍:

模板:

深入探讨:

工具:

公司特定指南:

示例:

另请参阅:

  • REMAP(过程知识的表示和维护)

  • DRL(决策表示语言)

  • IBIS(基于问题的信息系统)

  • QOC(问题、选项和标准)

  • IBM的e-Business参考架构框架

项目侧边栏1项目侧边栏2
推荐项目
Project Cover

豆包MarsCode

豆包 MarsCode 是一款革命性的编程助手,通过AI技术提供代码补全、单测生成、代码解释和智能问答等功能,支持100+编程语言,与主流编辑器无缝集成,显著提升开发效率和代码质量。

Project Cover

AI写歌

Suno AI是一个革命性的AI音乐创作平台,能在短短30秒内帮助用户创作出一首完整的歌曲。无论是寻找创作灵感还是需要快速制作音乐,Suno AI都是音乐爱好者和专业人士的理想选择。

Project Cover

有言AI

有言平台提供一站式AIGC视频创作解决方案,通过智能技术简化视频制作流程。无论是企业宣传还是个人分享,有言都能帮助用户快速、轻松地制作出专业级别的视频内容。

Project Cover

Kimi

Kimi AI助手提供多语言对话支持,能够阅读和理解用户上传的文件内容,解析网页信息,并结合搜索结果为用户提供详尽的答案。无论是日常咨询还是专业问题,Kimi都能以友好、专业的方式提供帮助。

Project Cover

阿里绘蛙

绘蛙是阿里巴巴集团推出的革命性AI电商营销平台。利用尖端人工智能技术,为商家提供一键生成商品图和营销文案的服务,显著提升内容创作效率和营销效果。适用于淘宝、天猫等电商平台,让商品第一时间被种草。

Project Cover

吐司

探索Tensor.Art平台的独特AI模型,免费访问各种图像生成与AI训练工具,从Stable Diffusion等基础模型开始,轻松实现创新图像生成。体验前沿的AI技术,推动个人和企业的创新发展。

Project Cover

SubCat字幕猫

SubCat字幕猫APP是一款创新的视频播放器,它将改变您观看视频的方式!SubCat结合了先进的人工智能技术,为您提供即时视频字幕翻译,无论是本地视频还是网络流媒体,让您轻松享受各种语言的内容。

Project Cover

美间AI

美间AI创意设计平台,利用前沿AI技术,为设计师和营销人员提供一站式设计解决方案。从智能海报到3D效果图,再到文案生成,美间让创意设计更简单、更高效。

Project Cover

AIWritePaper论文写作

AIWritePaper论文写作是一站式AI论文写作辅助工具,简化了选题、文献检索至论文撰写的整个过程。通过简单设定,平台可快速生成高质量论文大纲和全文,配合图表、参考文献等一应俱全,同时提供开题报告和答辩PPT等增值服务,保障数据安全,有效提升写作效率和论文质量。

投诉举报邮箱: service@vectorlightyear.com
@2024 懂AI·鲁ICP备2024100362号-6·鲁公网安备37021002001498号