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