Большинство архитектурных решений принимаются не в вакууме. Есть сроки, бюджет, текущая команда, ограничения legacy, требования клиента, доступные технологии и риск, который компания готова принять именно сейчас.
Через несколько месяцев часть этого контекста исчезает. Люди меняются, проект растёт, ограничения уже не очевидны. Остаётся только система и вопрос: «Почему здесь вообще сделано именно так?»
Какую проблему мы решаем
Architecture Decision Record, или ADR, — короткая запись о значимом архитектурном решении. Обычно она фиксирует проблему, рассматриваемые варианты, выбранный вариант, причины выбора и последствия.
Это не попытка документировать каждый класс или каждую настройку. Смысл ADR — сохранить решения, которые меняют границы системы, стоимость будущих изменений, эксплуатационные риски или зависимость от конкретного подхода.
Главное здесь слово — «почему». Схема показывает, что система состоит из сервисов. ADR объясняет, почему компания решила выделить эти сервисы именно сейчас и какие альтернативы сознательно отвергла.
Что получает бизнес
Бизнес получает более дешёвые будущие решения. Когда через год возникает вопрос о миграции, масштабировании или смене платформы, команде не приходится заново восстанавливать историю по перепискам и памяти нескольких людей.
Это снижает зависимость от конкретных сотрудников. Уход архитектора или технического лидера не должен означать потерю причин, по которым компания потратила деньги на определённую архитектуру.
ADR также помогает отличать постоянное ограничение от временного компромисса. Если решение было принято ради быстрого выхода на рынок, спустя два года его можно честно пересмотреть, а не защищать только потому, что «так уже работает».
Что получает команда
Команда получает общий контекст. Новому человеку проще понять не только устройство системы, но и историю её границ.
Повторные архитектурные споры становятся короче. Если вариант уже обсуждался и был отвергнут по конкретной причине, не нужно каждые полгода начинать разговор с нуля. Если причина больше не актуальна — это как раз хороший повод пересмотреть ADR.
Запись решения дисциплинирует и сам процесс выбора. Формулировка альтернатив и последствий часто показывает слабые места ещё до внедрения.
Что получает клиент
Клиент редко видит ADR напрямую. Но он получает более последовательный продукт: меньше случайных переписываний, меньше решений «по памяти» и ниже риск, что важное ограничение потеряется при смене команды.
Особенно это заметно в долгоживущих интеграциях и продуктах, где изменения должны учитывать старые договорённости и поведение системы.
Чем мы за это платим
ADR требуют привычки писать. Если каждое решение превращать в многостраничный документ с согласованием, практика быстро умрёт.
Есть и другая крайность: сотни записей про мелочи создают шум. Ценность появляется, когда фиксируются действительно значимые решения и статус записи понятен: принято, заменено, отменено.
Документ также устаревает, если команда никогда не связывает новые решения со старыми. ADR — не архив ради архива, а история эволюции системы.
Когда ADR не нужны
Для маленького краткоживущего проекта с одним разработчиком и очевидной архитектурой отдельная система решений может быть лишней.
Но чем дольше живёт продукт, чем больше команд участвует и чем дороже архитектурные изменения, тем ценнее становится сохранённый контекст.
Что стоит спросить перед решением
- Какие решения действительно влияют на стоимость будущих изменений?
- Сможет ли новый сотрудник через год понять причину выбора?
- Какие альтернативы мы рассматривали и почему отказались?
- Какие условия должны измениться, чтобы решение стоило пересмотреть?
- Кто отвечает за то, чтобы новые ADR не превращались в бюрократию?
В итоге
Хорошая архитектурная память хранит не только схемы. Она хранит причины.
ADR помогают компании не платить второй раз за уже проведённое мышление и быстрее понимать, когда старый компромисс перестал быть правильным.