Команда трижды возвращается к спору о выборе архитектурного решения. Какой документ зафиксирует решение так, чтобы обсуждение не начиналось заново?
Для этого используют ADR — Architecture Decision Record, то есть запись об архитектурном решении. Она фиксирует не только выбранный вариант, но и контекст, рассматриваемые альтернативы, критерии выбора и последствия. Благодаря этому команда сохраняет логику решения и может проверить её при изменении условий.
В архитектуре решения часто принимаются на встречах, в переписке и устных обсуждениях. Со временем участники меняются, исходные ограничения забываются, а одна и та же дискуссия повторяется.
ADR появился как лёгкий формат технической документации, который должен сохранять важные решения рядом с кодом или документацией системы. Его цель — не описать всю архитектуру, а зафиксировать решения, способные повлиять на дальнейшую разработку и эксплуатацию.
Без записи команда видит только текущий результат: например, выбран брокер сообщений, способ интеграции или граница сервиса. Причины выбора и отклонённые варианты остаются скрытыми.
Это создаёт несколько рисков: решение могут отменить, не понимая ограничений; новый участник повторит прежнее исследование; при инциденте будет трудно определить, являлось ли спорное поведение осознанным компромиссом или случайной ошибкой.
ADR обычно содержит следующие элементы:
Ключевой механизм — сохранение связи между условиями и решением. Читатель должен понять не только что выбрали, но и при каких предпосылках этот выбор был рационален.
ADR не заменяет требования, проектную документацию или описание интерфейсов. Он отвечает на вопрос о принятом архитектурном выборе и его обосновании, тогда как спецификация API описывает фактический контракт.
Запись должна быть достаточно подробной для восстановления рассуждения, но не превращаться в стенограмму совещания. Если условия существенно изменились, старую запись не следует молча редактировать: её переводят в статус заменённой и создают новую ADR со ссылкой на предыдущую.
Основной компромисс — стоимость поддержки против экономии времени в будущем. Слишком редкая фиксация оставляет пробелы, а запись каждого мелкого решения перегружает процесс и снижает ценность документа.
Интернет-магазин выбирал способ передачи события об оплате из платёжного сервиса в систему заказов. Рассматривались синхронный вызов из системы заказов, публикация события через брокер и периодический опрос платёжного сервиса.
Синхронный вызов был проще для первого релиза, но связывал доступность двух систем и плохо переносил временные сбои. Брокер обеспечивал буферизацию и повторную доставку, однако требовал идемпотентной обработки и дополнительной инфраструктуры. Опрос был устойчив к недоступности уведомлений, но увеличивал задержку и нагрузку на платёжный сервис.
В ADR зафиксировали выбор брокера, потому что для бизнеса важнее была надёжная доставка при временной недоступности системы заказов. Там же указали обязательную идемпотентность потребителя, мониторинг отставания очереди и условие пересмотра решения при отказе от брокерской платформы.
Позже команда предложила вернуться к синхронному вызову ради упрощения. ADR позволила быстро проверить исходные предпосылки: они не изменились, поэтому спор завершился без повторного полного анализа. Если бы требования по задержке стали жёстче, существующая запись дала бы понятную основу для новой оценки.
1. Должна ли ADR описывать только выбранный вариант?
Нет. Без альтернатив и причин отказа запись превращается в констатацию факта и плохо помогает при пересмотре решения. Достаточно кратко указать существенные варианты и критерии, по которым их сравнивали.
2. Нужно ли изменять старую ADR, если решение больше не подходит?
Обычно нет. Старую запись сохраняют как историческую, меняют её статус на заменённую и создают новую ADR, объясняя, какие условия изменились. Это сохраняет хронологию и позволяет понять, почему архитектура эволюционировала.
3. Чем ADR отличается от технического задания или архитектурной схемы?
Техническое задание описывает, что система должна делать, а схема показывает её структуру и связи. ADR объясняет, почему был выбран конкретный вариант и какие последствия команда приняла. Один проект может содержать все три вида документации: они дополняют друг друга, но не заменяют друг друга.