📘ADR: фиксируем архитектурные решения📘
Это короткий пост, вдохновлённый карточками по теме, которые я встретил на канале S0ER'а. В геймдеве такая практика встречается нечасто. Поэтому внесу дополнительное упоминание в ленту. Оставлю вводные, ссылки на более подробное изучение, поделюсь своим опытом и расскажу, какое отношение к этому имеет AI.
✍ Коротко об ADR:
ADR (Architecture Decision Record) — это документ, который фиксирует важное архитектурное решение, принятое на проекте, включая контекст, рассмотренные варианты и обоснование выбора.
Зачем нужны:
- 📝 Документирование решений для будущих разработчиков.
- 🔍 Прозрачность процесса принятия решений.
- ⏳ Сохранение контекста, который со временем забывается.
- 🔗 Связь между решениями и кодом.
Когда нужны:
- 🏗 Сложные, большие или долгосрочные проекты.
- 👥 Большие, распределённые или часто обновляющиеся команды.
Подробнее тут:
💻 Пример:
На одном из текущих проектов мы как раз ввели ADR. И постепенно их пополняем.
Используем только для важных архитектурных решений, принятых уже в процессе разработки и продиктованных обстоятельствами.
Например, один из ADR заключался в отказе от использования enum в качестве ключа словаря внутри сериализуемых данных для БД. Потому что случился непродуманный в начале разработки прецедент.
В итоге для таких кейсов стали использовать списки вместо словарей. Было найдено и опробовано много решений. Но выбранное показало себя самым оптимальным по трудозатратам на реализацию и дальнейшее масштабирование.
Весь контекст, альтернативы и последствия были зафиксированы в отдельном ёмком документе. С учётом всех рекомендаций из материалов выше.
🚀 Что это даёт:
Помимо перечисленного в прикреплённых материалах, я отмечаю следующие ценности:
- Распространение знаний внутри всей команды.
- Чёткая фиксация принятого решения для устранения неоднозначности.
- Потом обязательно будут случаи, когда очередной революционер на проекте решит переложить всё, что плохо лежит. ADR помогут показать, что лежит оно не так плохо, как могло бы, и почему лучше лишний раз не перекладывать. Даже когда команда проекта уже полностью обновится.
- Дополнительный контекст для AI. Если LLM сгенерит что-то "запрещённое", в него будет достаточно бросить один файл "вместо тысячи слов". Или сразу прикрепить как правило.
🤖 Как это делать:
Если раньше этой практике могли мешать лень или нехватка времени (а ёмкий и качественный текст требует затрат), то теперь с широким распространением LLM это стало просто и быстро.
В долгосрочной перспективе это очень полезный инструмент, который сейчас стал настолько дешёвым (в использовании), что будто бы дороже его игнорировать.
Споры и обсуждения у нас всегда ведутся либо в чатах, либо на созвонах с последующей фиксацией тезисов.
Все эти текстовые артефакты вместе со связанными задачами и всеми предыдущими ADR можно передать в LLM. Даже не выходя из IDE (запись в блоге). К слову, в этих сценариях GPT-5 себя очень хорошо показал.
Дальше останется только принять правки, сложить в выделенную для ADR директорию и немного дополишить.
Почему директория выделенная: легко искать документы и поддерживать хронологию.