Сообщить об ошибкеКороткий ответ
ADR — это короткий документ, фиксирующий конкретное архитектурное решение, рассмотренные альтернативы и причины выбора; его стоит заводить для решений, которые сложно будет отменить позже или которые вызывают споры в команде.
Как это работает подробнее
ADR обычно содержит контекст (какая проблема решалась), рассмотренные варианты, выбранное решение и его последствия (в том числе отрицательные). Он хранится рядом с кодом (например, в папке docs/adr) и доступен всей команде, в отличие от решения, принятого устно на созвоне и нигде не зафиксированного, которое легко забывается или искажается при пересказе.
Пример кода
example.txt
ADR-007: Выбор брокера сообщений для асинхронной обработки заказов
Контекст: нужно обрабатывать до 500 заказов/мин с гарантией доставки
хотя бы один раз, команда уже использует PostgreSQL и Redis.
Рассмотрены: Redis Streams, RabbitMQ, Kafka.
Решение: RabbitMQ — есть опыт в команде, достаточной пропускной способности,
не требует отдельной инфраструктуры как Kafka.
Последствия: при росте нагрузки на порядок потребуется пересмотреть выбор.Что использовать на практике
- Практика. ADR особенно полезен для решений вроде выбора брокера сообщений, схемы разбиения на сервисы или отказа от какого-то паттерна — то есть там, где через полгода кто-то неизбежно спросит «а почему мы сделали именно так» и где отмена решения стоит дорого. Для мелких технических деталей, которые легко поменять, заводить ADR избыточно и только добавляет лишнюю бюрократию в процесс разработки.
Подводные камни
- Риски. Частая ошибка — писать ADR постфактум просто как документацию «как есть», без фиксации реально рассмотренных альтернатив и компромиссов — тогда он теряет ценность при пересмотре решения в будущем. Другая ошибка — заводить ADR на каждое мелкое решение, из-за чего действительно важные записи теряются среди тривиальных. Также вредно никогда не пересматривать старые ADR, хотя условия, в которых решение принималось, со временем могут измениться.