День 1849. #ProjectManagement
Отслеживаем Архитектурные Решения через ADR
При проектировании архитектуры системы у вас есть много вариантов выбора. Вы архитектор, делаете некоторый выбор, всё идёт хорошо несколько месяцев. И вдруг появляется новое требование. Оно заставляет задуматься: «Правильна ли эта архитектура? Стоит ли что-то менять?». Вы уже не помните причины своего выбора. Нужно что-то, что напоминало бы вам, почему вы сделали тот или иной выбор…

Реестр Архитектурных Решений (Architecture Decision Records, ADR) — это способ описания, отслеживания и обсуждения архитектурных и проектных решений. Он позволяет иметь чётко определённый процесс принятия обоснованных решений и отслеживать причины вашего выбора.

Структура
ADR — это не просто список решений. Это документ, в котором также отслеживается текущий контекст, рассматриваемые альтернативы и последствия окончательного выбора. ADR состоит из набора файлов, каждый из которых описывает решение.
1. Суть решения
Например, «Использовать Azure Service Bus для очередей».
2. Статус
Например, «На обсуждении», «Принято» и «Заменено».
3. Время принятия решения
Когда ADR создан и когда получал каждый статус.
4. Контекст
Например: «В настоящее время мы используем Azure в качестве основного поставщика».
5. Последствия
Например: «Мы согласны с привязкой к поставщику. Так будет легче получить поддержку со стороны команды по инфраструктуре».

Статусы
Обычно должен быть строгий набор статусов, гарантирующий, что после достижения одного из окончательных статусов решение в ADR не может быть изменено.
Первичные
- Черновик: первичное описание решения, вы пока не готовы его обсуждать.
- Предложение: объяснены все детали решения для официального обсуждения.
- Открыто: каждый может добавлять комментарии к решению, что позволит учесть другие точки зрения и указать слабые места.
Окончательные
- Принято: команда согласна с решением, и теперь можно его реализовать.
- Отклонено: решение неосуществимо, реализация невозможна.
- Устарело: решение больше не является полезным или необходимым.
- Заменено: другой ADR заменяет нынешний. Обязательно нужно указать номер нового ADR, а в новом сослаться на тот, который он заменяет. Так можно восстановить историю конкретного выбора.

Рекомендации
1. Используйте единый формат и структуру для каждого ADR.
2. Храните ADR в текстовом файле рядом с кодом, соответствующим этому решению, или в центральном репозитории, чтобы можно было просмотреть историю обновлений.
3. Используйте понятное и описательное имя файла, например ADR-001-use-azure-service-bus.md.
4. Делайте ADR кратким и сосредоточенными на одном решении. Добавляйте только необходимую информацию, чтобы понять причину решения.
5. Обновляйте ADR по мере развития или изменения решения, указывая причину изменений.
6. Периодически проверяйте актуальность ADR текущему состоянию архитектуры и потребностям бизнеса.

Вот хороший список шаблонов ADR.

Инструменты
- adr-cli - инструмент CLI, написанный на .NET, который автоматически создаёт и управляет историей ваших ADR.
- ADR Manager - UI инструмент, который подключается к вашему репозиторию GitHub и генерирует файлы ADR.

Итого
ADR — отличный инструмент, особенно для проектов, требования которых не определены заранее и которые, как ожидается, будут иметь длительный срок службы. Одним из наиболее важных этапов принятия архитектурных решений является обсуждение решения. Архитектор не должен навязывать архитектуру команде. Другие заинтересованные стороны, например разработчики, могут иметь некоторые опасения или заметить случай, который не может быть охвачен решением.

Источник: https://www.code4it.dev/architecture-notes/architecture-decision-records/