Через год после запуска команда предлагает заменить базу данных. Все видят, что нынешняя система стала неудобной. Но почему её выбрали? Может быть, тогда у команды не было нужных специалистов, срок был жёстким, а прежний продукт не выдержал бы большой миграции. Или выбор действительно был неудачным. Без контекста мы не отличим одно от другого.
Architecture Decision Record — короткая запись о значимом техническом выборе. Она хранит не только ответ «что сделали», но и основания, на которых этот ответ когда-то был разумным.
Что в записи действительно важно
Хороший ADR описывает проблему, ограничения на момент решения, рассмотренные альтернативы, выбранный вариант и ожидаемые последствия. В нём полезно указать, от чего компания сознательно отказалась. Например, управляемая база обошлась дороже, зато не потребовала собственной команды эксплуатации.
Не нужно превращать ADR в многотомную архитектурную концепцию. Документ, который никто не может открыть и понять через год, не выполняет своей функции. Обычно достаточно конкретного контекста и честно перечисленных компромиссов.
Запись полезна только пока решение можно пересмотреть
Иногда ADR ошибочно используют как вечное оправдание: «мы же это утвердили». Но решение было принято при определённом бюджете, составе команды, сроках и нагрузке. Если эти условия изменились, старый аргумент тоже должен быть проверен заново.
Я бы добавлял к важным решениям признак пересмотра: какая ситуация должна наступить, чтобы вернуться к выбору? Например, рост стоимости эксплуатации, смена регуляторных требований или появление самостоятельной команды у части системы.
При изменении курса лучше создать новую запись, которая ссылается на прежнюю, чем молча переписывать историю. Так можно восстановить не только путь системы, но и развитие предположений.
В какой момент ADR превращается в бюрократию
Если каждый новый индекс базы и переименование метода требует отдельного комитета, команда начнёт писать документы ради отметки. Значимыми стоит считать решения, которые трудно обратить, меняют границы собственности, риски эксплуатации или стоимость будущих изменений.
ADR не заменяет эксперименты, измерения и архитектурные проверки. Он фиксирует, зачем мы согласились на определённый компромисс. А Fitness Functions могут помочь проверить, что важные договорённости действительно соблюдаются.
Хорошая архитектурная память не делает старое решение вечным. Она позволяет понять, почему оно было правильным — и когда перестало быть таким.