ADR

ADR — Architecture Decision Record.

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

Если ADR навязан “сверху”, каждая такая запись превращается в длинный рассказ, который невозможно прочитать и понять, чем мотивировано то или иное решение. Такие ADR пишутся “чтобы были”, для одобрения коллег и руководства. Ошибочно предполагается, что “труд”, вложенный в длинный (и часто непоследовательный) рассказ приносит команде пользу.

Такие ADR пишутся один раз, никем и никогда не читаются, и хранятся “потому что являются важным документом”.

Основная задача ADR — передать коллегам, в том числе и будущим, контекст принятого решения.

Не превращайте ADR в длинную историю. Чётко зафиксируйте ситуацию, по пунктам укажите причины, повлиявшие на ваше решение, зафиксируйте предполагаемые последствия, на что может повлиять ваш выбор в будущем, чем он может вас ограничить, как можно обойти или снять полученные ограничения.

ADR — не высеченная в камне истина. Со временем или приходом понимания, что принятое решение устарело и не удовлетворяет новым требованиям, его следует пересмотреть, отклонить текущую запись и заменить её новой.

Другой частой проблемой в фиксации ADR является определение значимости решения. Разработчикам кажется, что они описывают очередную мелочь, о которой все и так знают. Как показывает практика — нет. Контекст забывается сразу же после очередного собрания.

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

В процессе работы выяснилось, что:

• Правила валидации расходятся на front- и backend’е приложения;
• Имена кластеров влияют на формирование имён хостов, входящих в кластер;
• Использование имени кластера в имени хоста накладывает ряд ограничений на на пользовательский ввод.

Что в данном случае уместно зафиксировать в ADR?

• Факт ограничений, накладываемых на имя кластера;
• Причины, по которым в данный момент времени вводятся ограничения;
• Правила валидации — единый источник истины для front- и backend-⁠разработчиков;
• Последствия принятого решения, например, возможные ограничения при импорте данных из внешних систем.

Инженерная культура моих коллег находится на самом высоком уровне. Мы всегда чётко фиксируем и исполняем принятые нами решения. Составленные ADR не занимают больше одного экрана 13" ноутбука, всегда описывают проблему и контекст принятого решения, отвечают на вопрос “почему” и предупреждают появление возможных негативных последствий. Устаревшие ADR пересматриваются и заменяются новыми, соответствующими современным требованиям.