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