ADR: фиксируем архитектурные решения

Это короткий пост, вдохновлённый карточками по теме, которые я встретил на канале S0ER’а. В геймдеве такая практика встречается нечасто. Поэтому внесу дополнительное упоминание в ленту. Оставлю вводные, ссылки на более подробное изучение, поделюсь своим опытом и расскажу, какое отношение к этому имеет AI.

✍️ Коротко об ADR:

ADR (Architecture Decision Record) — это документ, который фиксирует важное архитектурное решение, принятое на проекте, включая контекст, рассмотренные варианты и обоснование выбора.

Зачем нужны:

• 📝 Документирование решений для будущих разработчиков.

• 🔍 Прозрачность процесса принятия решений.

• ⏳ Сохранение контекста, который со временем забывается.

• 🔗 Связь между решениями и кодом.

Когда нужны:

• 🏗️ Сложные, большие или долгосрочные проекты.

• 👥 Большие, распределённые или часто обновляющиеся команды.

Подробнее тут:

• Карточки от S0ER

• Блог Антона Агатсова

• Как избежать повторения ошибок

• Метод документирования архитектурных решений

💻 Пример:

На одном из текущих проектов мы как раз ввели ADR. И постепенно их пополняем.

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

Например, один из ADR заключался в отказе от использования enum в качестве ключа словаря внутри сериализуемых данных для БД. Потому что случился непродуманный в начале разработки прецедент.

В итоге для таких кейсов стали использовать списки вместо словарей. Было найдено и опробовано много решений. Но выбранное показало себя самым оптимальным по трудозатратам на реализацию и дальнейшее масштабирование.

Весь контекст, альтернативы и последствия были зафиксированы в отдельном ёмком документе. С учётом всех рекомендаций из материалов выше.

🚀 Что это даёт:

Помимо перечисленного в прикреплённых материалах, я отмечаю следующие ценности:

1. Распространение знаний внутри всей команды.

2. Чёткая фиксация принятого решения для устранения неоднозначности.

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

4. Дополнительный контекст для AI. Если LLM сгенерит что-то «запрещённое«, в него будет достаточно бросить один файл «вместо тысячи слов«. Или сразу прикрепить как правило.

🤖 Как это делать:

Если раньше этой практике могли мешать лень или нехватка времени (а ёмкий и качественный текст требует затрат), то теперь с широким распространением LLM это стало просто и быстро.

В долгосрочной перспективе это очень полезный инструмент, который сейчас стал настолько дешёвым (в использовании), что будто бы дороже его игнорировать.

Споры и обсуждения у нас всегда ведутся либо в чатах, либо на созвонах с последующей фиксацией тезисов.

Все эти текстовые артефакты вместе со связанными задачами и всеми предыдущими ADR можно передать в LLM. Даже не выходя из IDE (см. статью). К слову, в этих сценариях GPT-5 себя очень хорошо показал.

Дальше останется только принять правки, сложить в выделенную для ADR директорию и немного дополишить.

Почему директория выделенная: легко искать документы и поддерживать хронологию.