Журналирование архитектурных решений

Architectural Decision Records, ADR

3 min readApr 12, 2022

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

Готовность к изменениям важнее следования первоначальному плану)
- Agile-манифест разработки программного обеспечения

Эволюция архитектуры — важная часть знаний о Продукте и его истории.

Что такое Архитектурные решения?

Одно из самых простых определений Архитектурного решения (Architectural Decision, AD) которые видел, звучит так:

Любое инженерное решение, изменение которого обходится дорого.
- https://medium.com/@apolomodov

Есть более проработанные определения, но мы в данном случае остановимся на этом.

Важно отметить что:

Решения в области безопасности (Security)
Решения по Управлению Релизами (Release Management) и DevOps
Решения по Управлению Данными (Data Governance)

Тоже относятся к архитектурным.

Практика — Architectural Decision Records, ADR

Воспользуюсь материалами из ADR GitHub organization.

Чтобы команды могли отслеживать принципиальные изменения в Архитектуре неплохо их записывать(Architectural Decision Records, ADR) и размещать в общедоступном месте. Причем фиксировать решение лучше максимально прозрачным образом с описанием не только самого решения но и:

Контекста проблемы или вызова
Вариантов выбора и и их +/-
Последствий
И самого решения 🤖

Что улучшает практика:

Время онбординга разработчиков и архитекторов
Время приятия или пересмотра архитектурных решений
Неповторение неудачных решений и подходов
Уменьшение иллюзии о принятия решений “с потока”

Характеристики хорошего ADR:

Рациональное: Объясните причины выполнения конкретного AD. Это может включать контекст, плюсы и минусы различных возможных вариантов, сравнение функций, обсуждение затрат и выгод и многое другое.
Конкретное: каждый ADR должен относиться к одному AD, а не к нескольким AD.
Датированное: укажите, когда записывается каждый элемент в ADR. Это особенно важно для аспектов, которые могут меняться со временем, таких как затраты, графики, масштабирование и т.п.
Неизменяемое: не изменяйте существующую информацию в ADR. Вместо этого внесите изменения в ADR, добавив новую информацию, или замените ADR, создав новую ADR.

Характеристики хорошего раздела «Контекст» в ADR:

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

Характеристики хорошего раздела «Последствия» в ADR:

Объясните, что следует из принятого решения. Это может включать в себя эффекты, результаты, результаты, последующие действия и многое другое.
Включите информацию о любых последующих ADR. Относительно часто один ADR вызывает потребность в большем количестве ADR, например, когда один ADR делает большой всеобъемлющий выбор, который, в свою очередь, создает потребность в более мелких решениях.
Включите любые процессы проверки после действий. Команды обычно пересматривают каждый ADR через месяц, чтобы сравнить информацию о ADR с тем, что произошло на практике, чтобы учиться и развиваться.