Никто никогда не вернется в 2007 год, однако сделать так, чтобы потомки были нам благодарны и понимали нашу мотивацию есть.
Это ADR (Architecture Decision Records) – записи архитектурных решений.
ADR – это эффективный инструмент для фиксации важных архитектурных решений в проекте. Если коротко, это документ, в котором зафиксировано почему выбрали то или иное решение.
1️⃣Зачем это нужно?
Чтобы помнить, а чем мы руководствовались, когда ставили себе в проект очередную зависимость, почему выбрали тот или иной инструмент.
Чтобы команда лучше понимала проект и требования (и бонусом это может повлиять на онбординг)
Чтобы мы перестали холиварить о каких-то темах, а просто зафиксировали решение.
2️⃣Что ADR из себя представляет?
Это текстовый документ, у которого может быть несколько статусов (например, драфт, в работе, обсуждение, принято, устарело). Его можно положить во внутреннюю документацию (notion, wiki, confluence, не важно).
В нем зафиксировано:
- контекст
- требования
- предлагаемые решения
- последствия
- вывод
ADR представляет собой небольшую защиту диплома. Кто-то исследует проблему, выбирает оптимальное решение и потом на встрече его презентует. Если защита проходит успешно, то ADR меняет статус в "принято" и становится стандартом. Если нет, то отправляется на доработку.
3️⃣Когда использовать?
Когда мы понимаем, что наше решение может на многое повлиять, в контексте фронтенда это фреймворк, state-manager, router, i18n, ui-library и etc.
Когда у нас большая команда и надо договориться о каких-то общих подходах.
Это история про какие-то фундаментальные вещи в приложении.
4️⃣Подводные камни
- Внимательно отнеситесь к формированию требований, чем более четко они будут сформулированы, тем будет легче
- Команда должна согласиться с этим процессов и активно в нем участвовать (чтобы это не была работа в стол)
- Излишний формализм
- Игнорирование альтернатив
- ADR требует не мало ресурсов и надо тратить их на то, что очень важно.
5️⃣Выводы
ADR – это прекрасный инструмент, чтобы фиксировать архитектурные решения. Он помогает команде иметь общий контекст. Упрощает онбординг. Ускоряет разработку и бонусом – люди занимаясь ADR могу расти (это отличная возможность прокачать экспертность)
🔖 Шаблон
ADR-1 Название
## Статус
Черновик | _**Принят**_ | Отклонен | Устарел | Изменен | Обсуждение
## Контекст
Здесь пишем о том, почему возникла проблема.
### Требования
Перечисляем наши требования
## Варианты
Описываем все варианты и соответствия требованиям
## Последствия
Какие у выбора предлагаемых вариантов последствия (а они почти всегда есть, это не нулевая работа)
## Выводы
На чем останавливаемся