Skip to main content

Architectural Decision Records (ADR)

· 5 min read
Andrey Ganyushkin

Статьи серии:

Architectural Decision Records (ADR)
Architectural Decision Records (ADR). Y-Statements

AD и ADR​

Что такое AD и ADR?​

Architectural Decision (AD) - Архитектурное решение. Решение (выбор) принятое в процессе разработки архитектуры или проектирования программного обеспечения.

Architectural Decision Records (ADR) - Документ описывающий архитектурное решение.

An Architectural Decision (AD) is a justified software design choice that addresses a functional or non-functional requirement that is architecturally significant. An Architecturally Significant Requirement (ASR) is a requirement that has a measurable effect on a software system’s architecture and quality. An Architectural Decision Record (ADR) captures a single AD and its rationale; the collection of ADRs created and maintained in a project constitute its decision log. All these are within the topic of Architectural Knowledge Management (AKM)

источник

Главное из этого описания:

  • архитектурное решение - это выбор технологии, подхода и т.п.
  • архитектурное решение оказывает значительное влияние на архитектуру
  • нефункциональные требования являются причиной появления архитектурного решения
  • ADR содержит (описывает) только одно архитектурное решение
  • коллекция решений (ADR) - это журнал принятия решений описывающий проект, систему, компонент

Важно: Архитектурное решение (AD) или ADR - это не решение (solution) для имплементации какой-либо фичи, бизнес требования и т.п. Solution может включать в себя столько ADR сколько выборов необходимо было сделать в процессе разработки solution'а.

Или вот еще одно пояснение, что такое ADR:

An Architectural Decision (AD) is a software design choice that addresses a functional or non-functional requirement that is architecturally significant. This might, for instance, be a technology choice (e.g., Java vs. JavaScript), a choice of the IDE (e.g., IntelliJ vs. Eclipse IDE), a choice between a library (e.g., SLF4J vs java.util.logging), or a decision on features (e.g., infinite undo vs. limited undo).

источник

Зачем?​

ADR - это максимально простой документ отвечающий на вопрос, почему было принято то или иное решение.

ADR - это текстовое описание принятого решения, которое позволяет выразить заметно больше чем через диаграммы. Является прекрасным дополнением для различных диаграмм, поясняя почему и как было принято то или иное решение.

ADR - это не только текст. Нет запретов на использование диаграмм в ADR если это уместно и поможет описать мысль яснее.

Где записывать?​

Подойдет любой инструмент с функциями поиска, версионирования, организации документов. Например, Confluence или Git.

Ниже приведен пример формата записи для хранения в Git.

Когда стоит записать решение?​

В статье с хабра есть отличный пример критериев, когда стоит записать принятое решение. Его можно использовать как драфт вашего собственного списка критериев:

  • структуру ПО;
  • функциональные характеристики ПО;
  • зависимости между компонентами (где мы допускаем сильное связывание, а где его не должно случиться);
  • интерфейсы и API (как наши компоненты, модули и прочее будут взаимодействовать друг с другом);
  • используемые технологии (платформы, фреймворки, тулы и так далее).

Как писать?​

Писать нужно просто, понятно, коротко. Чтобы потом не приходилось делать презентации с описанием и интерпретацией написанного в ADR.

Интересная статья о том как писать ADR с хорошими и плохими подходами: How to create Architectural Decision Records (ADRs) — and how not to

И еще пару статей:

Architectural Significance Criteria and Some Core Decisions Required
A Definition of Done for Architectural Decision Making
How to review Architectural Decision Records (ADRs) — and how not to

MADR​

Что это такое?​

MADR - "Markdown Any Decision Records" (MADR). Ранее был известен как "Markdown Architectural Decision Records" (MADR). это Architectural Decision Records записанный в формате markdown.

MADR (https://adr.github.io/madr/) is a lean template to capture any decisions in a structured way.

В Short Version выглядит это примерно так:

## Какой фреймворк выбрать для создания нового UI компонента

### Контекст и постановка проблемы

Нужно сделать новый дашборд в существующей системе.
Нужно сделать быстро.

### Рассмотренные варианты

* React
* Angular
* Blazor

### Результат принятия решения

Был выбран React так как для него существует UI компонент Х с хорошей функциональностью из коробки.

Есть еще Long Version, где предлагается довольно подробно описать решение. Выглядит привлекательно.

Markdown удобен тем, что это текст который можно хранить в git, его можно прочитать и без рендеринга, существует много инструментов работы с ним.

Шаблоны MADR​

ADR Template
adr-template-long.md
adr-template-long-ru.md

И еще немного шаблонов из репозитория joelparkerhenderson/architecture-decision-record:

Инструменты для работы с MADR​

Для того чтобы сделать работы с коллекцией решений более удобной мы можем использовать такие инструменты как:

  • ADR Manager - облегчает работу с коллекциями ADR в Github.
  • Log4brains - Log4brains is a docs-as-code knowledge base for your development and infrastructure projects.

Еще несколько инструментов можно найти тут.

Интересное​

The Markdown ADR (MADR) Template Explained and Distilled
Architectural Decision Records (ADRs)
madr-paper9.pdf

Заключение​

История принятых решений в том виде и объеме в котором эти решения доносились до команды - это отличный способ увеличить прозрачность в проекте.