Технологии

Architecture Decision Record: как не потерять логику архитектурных решений

На itWeek вышла статья Эдуарда Забоева, технического директора DIGITAL SECTOR, «Архитектурная амнезия: почему компании помнят, что построили, но забывают зачем». В ней эксперт рассказывает, почему со временем команда может потерять не документацию и код, а понимание причин, по которым система устроена именно так.
Сложное архитектурное решение, у которого есть своя причина

Почему не каждое сложное решение — технический долг

Когда новая команда начинает разбираться в системе, которая работает уже несколько лет, сложные или необычные решения легко принять за технический долг. Кажется, что их можно убрать и сделать проще. Но сложность могла появиться не из-за неудачной разработки, а как ответ на конкретное ограничение — например, из-за высокой нагрузки, особенностей другой системы или требований к стабильности.
Представим, что данные для одного из разделов корпоративной системы обновляются не сразу, а раз в несколько минут. Новой команде это кажется странным: зачем показывать данные с задержкой, если их можно каждый раз запрашивать из основной системы напрямую? Команда меняет схему и подключает прямой обмен, но через некоторое время выясняется, что при большой нагрузке основная система начинает отвечать медленнее, а вместе с ней замедляется и пользовательский сервис. Оказывается, небольшая задержка в обновлении данных была предусмотрена специально: она позволяла не обращаться к основной системе при каждом действии пользователя и снижала нагрузку.
Поэтому перед тем, как относить такое решение к техническому долгу и переделывать его, важно понять, почему оно появилось. Если исходного ограничения уже нет, архитектуру действительно можно упростить. Если оно сохраняется, вместе с «лишней» сложностью можно убрать и решение реальной проблемы. Сложность здесь не в самом старом подходе, а в том, что его причина со временем потерялась: если она нигде не записана, новой команде приходится восстанавливать этот контекст заново.
Сравнение технического долга и осознанного архитектурного решения

Во что обходится потерянный архитектурный контекст

Пока система работает и её никто серьёзно не меняет, забытая история решений может не мешать годами. Потери становятся заметны, когда начинается модернизация или крупная доработка.

Приходится повторно искать уже найденный ответ

Разработчики видят необычное решение, но не знают, зачем оно понадобилось. Перед изменением нужно проверить, связано ли оно с нагрузкой, безопасностью, внешними системами или другими ограничениями, и на это снова уходит время архитекторов и разработчиков. В результате команда может прийти к тому же выводу, к которому предыдущие специалисты уже пришли несколько лет назад. Для бизнеса это оплаченная работа, которая не создаёт ничего нового: она только восстанавливает потерянный контекст.
Компания платит не за отсутствие ещё одного документа, а за необходимость заново искать уже однажды найденные ответы.Текст цитаты
Эдуард Забоев
технический директор DIGITAL SECTOR

Сложнее заранее оценить изменения

Если команда не знает, зачем в системе появилось конкретное ограничение, ей сложнее заранее понять последствия его изменения. То, что выглядит небольшой доработкой, может потребовать дополнительного обследования уже после старта работ: например, только в процессе выяснится, что старое решение связано с другой системой, нагрузкой или важным бизнес-сценарием. Тогда приходится уточнять план и объём работ. Причина здесь не просто в возрасте системы, а в том, что часть архитектурного контекста была потеряна.

Сколько стоит отложенная модернизация веб-системы и почему «подождём ещё год» обходится дороже

Разбираем, из чего складывается стоимость ещё одного года работы текущей системы и в каких случаях перенос модернизации действительно оправдан.

Читать статью →

Как сохранить причину архитектурного решения

Для этого можно использовать Architecture Decision Record (ADR) — короткий документ, в котором фиксируют важное архитектурное решение и причины, по которым его приняли. На практике ADR в разработке особенно полезен для решений, к которым команда может вернуться через несколько лет: в записи можно сохранить исходную задачу, ограничения, рассмотренные варианты и логику выбора.
В примере выше ADR мог бы выглядеть так — достаточно зафиксировать четыре вещи.
Карточка Architecture Decision Record с проблемой, решением, причиной и компромиссом
Такой записи достаточно, чтобы через несколько лет новая команда не гадала, почему данные обновляются именно таким способом. Это не значит, что решение нельзя менять: возможно, основную систему уже доработали и прежнего ограничения больше нет. Но сначала команда сможет проверить, актуальна ли причина, ради которой появилась такая схема.

Какие архитектурные решения важно не потерять

Записывать в ADR каждую техническую задачу не нужно. Он полезен там, где выбранный подход влияет на другие части системы или его изменение потребует заметных затрат. Например, стоит зафиксировать, почему команда:
  • хранит одни и те же данные в двух местах;
  • обновляет данные не сразу, а с небольшой задержкой;
  • добавила между двумя системами ещё один промежуточный сервис;
  • предусмотрела отдельный сценарий на случай сбоя;
  • ввела ограничения для отдельных операций;
  • выбрала более сложный вариант, хотя на первый взгляд можно было сделать проще.
Во всех этих случаях важно сохранить не только что сделали, но и зачем. Именно эта причина через несколько лет чаще всего теряется.

Чек-лист: что записать в ADR

Большого документа не требуется. Для большинства решений достаточно ответить на десять вопросов.

1. Какую проблему решали?

Что происходило в системе и зачем вообще понадобилось принимать отдельное решение.

2. Какие ограничения были на тот момент?

Например, нагрузка, возможности внешней системы, требования безопасности, сроки или особенности существующей архитектуры.

3. Какие варианты рассматривали?

Достаточно перечислить основные альтернативы.

4. Что выбрали?

Коротко описать, какое решение в итоге выбрали.

5. Почему выбрали именно этот вариант?

Главное — сохранить логику выбора, а не просто описать результат.

6. Почему не подошли другие варианты?

Так следующей команде не придётся снова проверять то, что уже изучали раньше.

7. Какие минусы есть у решения?

Например, система становится устойчивее к сбоям, но усложняется поддержка или данные обновляются с небольшой задержкой.

8. Что от решения зависит?

Связанные системы, компоненты, интеграции или процессы.

9. Когда его стоит пересмотреть?

Например, после замены внешней системы, изменения нагрузки или инфраструктуры.

10. Где искать дополнительную информацию?

Ссылки на архитектурные схемы, задачи и техническую документацию.

Такого набора обычно достаточно, чтобы позже быстро восстановить главное: какую проблему решали, какие ограничения учитывали и почему остановились именно на этом варианте.

Три правила, чтобы ADR не превратились в формальность

Фиксировать решение сразу. Через несколько месяцев часть аргументов уже может забыться.     
Хранить записи там, где команда действительно ищет информацию о системе. Это может быть репозиторий или общая проектная документация.    
Не переписывать старую историю. Если условия изменились и принято новое решение, лучше создать новый ADR и связать его с предыдущим. Тогда будет видно не только текущее состояние системы, но и почему оно менялось. Особенно полезна такая история при смене команды: код и документацию можно передать новому подрядчику, а причины решений — только если они были где-то сохранены.

Как сменить подрядчика и не остановить веб-систему

Разбираем, что нужно передать новой команде кроме исходного кода и документации и как проверить, что она действительно готова самостоятельно поддерживать систему.

Читать статью →

Что делать, если система работает давно, а ADR никто не вёл

Восстанавливать задним числом историю каждого решения за много лет не нужно: часть информации всё равно уже потеряна. Лучше начать с тех участков системы, которые скоро предстоит менять.
Посмотрите, есть ли там решения, назначение которых сейчас непонятно: необычные интеграции, дублирование данных, дополнительные сервисы, ограничения или обходные сценарии. Если причина неочевидна, её лучше выяснить до начала разработки. Пока в компании остались специалисты, которые участвовали в создании системы, у них можно восстановить часть контекста и зафиксировать его, а все новые значимые решения уже записывать сразу.

ADR нужен не для того, чтобы сохранить старую архитектуру

Решение, принятое несколько лет назад, сегодня вполне может устареть. Смысл ADR не в том, чтобы сохранить старое решение любой ценой, а в том, чтобы при следующем изменении команда понимала исходную логику.
Система меняется, и решение пятилетней давности может потерять актуальность. Но пересматривать его безопаснее, когда известны исходные условия и причины выбора.
Эдуард Забоев
технический директор DIGITAL SECTOR
Если прежние ограничения исчезли, решение можно пересмотреть. Главное — делать это не на основе догадок, а понимая, почему оно когда-то появилось.

Планируете модернизацию существующей веб-системы?

Перед изменениями важно понять, какие части системы действительно устарели, а какие появились по конкретной причине и всё ещё решают свою задачу. DIGITAL SECTOR проводит техническое обследование, развивает и модернизирует работающие веб-системы.



Согласен