architecture-decision-record

architecture-decision-record

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

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

架构决策记录ADR软件架构文档化决策管理Github开源项目

架构决策记录 (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参考架构框架

编辑推荐精选

讯飞星火

讯飞星火

深度推理能力全新升级,全面对标OpenAI o1

科大讯飞的星火大模型,支持语言理解、知识问答和文本创作等多功能,适用于多种文件和业务场景,提升办公和日常生活的效率。讯飞星火是一个提供丰富智能服务的平台,涵盖科技资讯、图像创作、写作辅助、编程解答、科研文献解读等功能,能为不同需求的用户提供便捷高效的帮助,助力用户轻松获取信息、解决问题,满足多样化使用场景。

热门AI开发模型训练AI工具讯飞星火大模型智能问答内容创作多语种支持智慧生活
Spark-TTS

Spark-TTS

一种基于大语言模型的高效单流解耦语音令牌文本到语音合成模型

Spark-TTS 是一个基于 PyTorch 的开源文本到语音合成项目,由多个知名机构联合参与。该项目提供了高效的 LLM(大语言模型)驱动的语音合成方案,支持语音克隆和语音创建功能,可通过命令行界面(CLI)和 Web UI 两种方式使用。用户可以根据需求调整语音的性别、音高、速度等参数,生成高质量的语音。该项目适用于多种场景,如有声读物制作、智能语音助手开发等。

Trae

Trae

字节跳动发布的AI编程神器IDE

Trae是一种自适应的集成开发环境(IDE),通过自动化和多元协作改变开发流程。利用Trae,团队能够更快速、精确地编写和部署代码,从而提高编程效率和项目交付速度。Trae具备上下文感知和代码自动完成功能,是提升开发效率的理想工具。

AI工具TraeAI IDE协作生产力转型热门
咔片PPT

咔片PPT

AI助力,做PPT更简单!

咔片是一款轻量化在线演示设计工具,借助 AI 技术,实现从内容生成到智能设计的一站式 PPT 制作服务。支持多种文档格式导入生成 PPT,提供海量模板、智能美化、素材替换等功能,适用于销售、教师、学生等各类人群,能高效制作出高品质 PPT,满足不同场景演示需求。

讯飞绘文

讯飞绘文

选题、配图、成文,一站式创作,让内容运营更高效

讯飞绘文,一个AI集成平台,支持写作、选题、配图、排版和发布。高效生成适用于各类媒体的定制内容,加速品牌传播,提升内容营销效果。

热门AI辅助写作AI工具讯飞绘文内容运营AI创作个性化文章多平台分发AI助手
材料星

材料星

专业的AI公文写作平台,公文写作神器

AI 材料星,专业的 AI 公文写作辅助平台,为体制内工作人员提供高效的公文写作解决方案。拥有海量公文文库、9 大核心 AI 功能,支持 30 + 文稿类型生成,助力快速完成领导讲话、工作总结、述职报告等材料,提升办公效率,是体制打工人的得力写作神器。

openai-agents-python

openai-agents-python

OpenAI Agents SDK,助力开发者便捷使用 OpenAI 相关功能。

openai-agents-python 是 OpenAI 推出的一款强大 Python SDK,它为开发者提供了与 OpenAI 模型交互的高效工具,支持工具调用、结果处理、追踪等功能,涵盖多种应用场景,如研究助手、财务研究等,能显著提升开发效率,让开发者更轻松地利用 OpenAI 的技术优势。

Hunyuan3D-2

Hunyuan3D-2

高分辨率纹理 3D 资产生成

Hunyuan3D-2 是腾讯开发的用于 3D 资产生成的强大工具,支持从文本描述、单张图片或多视角图片生成 3D 模型,具备快速形状生成能力,可生成带纹理的高质量 3D 模型,适用于多个领域,为 3D 创作提供了高效解决方案。

3FS

3FS

一个具备存储、管理和客户端操作等多种功能的分布式文件系统相关项目。

3FS 是一个功能强大的分布式文件系统项目,涵盖了存储引擎、元数据管理、客户端工具等多个模块。它支持多种文件操作,如创建文件和目录、设置布局等,同时具备高效的事件循环、节点选择和协程池管理等特性。适用于需要大规模数据存储和管理的场景,能够提高系统的性能和可靠性,是分布式存储领域的优质解决方案。

TRELLIS

TRELLIS

用于可扩展和多功能 3D 生成的结构化 3D 潜在表示

TRELLIS 是一个专注于 3D 生成的项目,它利用结构化 3D 潜在表示技术,实现了可扩展且多功能的 3D 生成。项目提供了多种 3D 生成的方法和工具,包括文本到 3D、图像到 3D 等,并且支持多种输出格式,如 3D 高斯、辐射场和网格等。通过 TRELLIS,用户可以根据文本描述或图像输入快速生成高质量的 3D 资产,适用于游戏开发、动画制作、虚拟现实等多个领域。

下拉加载更多