Зачем ADR нужен frontend-команде
Без ADR одинаковые вопросы возвращаются каждый месяц: Zustand или Redux, SSR или CSR, как кэшировать API и т.д.
Минимальный шаблон ADR
# ADR-012: Выбор state management
Дата:
Контекст:
Решение:
Альтернативы:
Последствия:
Как внедрить без бюрократии
- ADR только для решений с долгим эффектом.
- 1 страница, без длинных эссе.
- PR не мержим без ссылки на ADR, если затрагивается архитектура.
Примеры тем для ADR
- i18n подход
- auth/session модель
- логирование ошибок
- кеширование в App Router
Что это даёт
Быстрее onboarding, меньше повторных споров и более предсказуемые релизы.
Когда писать ADR, а когда нет
ADR нужен не для каждой задачи. Если решение локальное и легко откатывается (например, название пропса в одном компоненте), отдельный документ избыточен.
Пишите ADR, если:
- решение влияет минимум на 2-3 модуля;
- откат дорогой или долгий;
- есть минимум две жизнеспособные альтернативы;
- решение будет жить дольше одного спринта.
Пример решения с последствиями
Тема: где хранить бизнес-логику формы onboarding.
Опции: (1) в React-компоненте, (2) в server action + validation schema.
Решение: server action + zod schema.
Последствия: выше единообразие, ниже риск дублирования правил между фронтом и бэком, но больше требований к контрактным тестам.
Именно блок "последствия" чаще всего спасает от повторного обсуждения через 3 месяца.
Workflow в команде
Рабочий процесс можно сделать очень простым:
- Автор создаёт ADR в PR.
- TL/архитектор даёт review в течение 24 часов.
- После мержа PR ADR получает статус
Accepted. - Через 1-2 месяца делается короткий revisit: решение всё ещё валидно?
Статусы ADR
Proposed— обсуждается.Accepted— принято и внедряется.Superseded— заменено новым ADR.Deprecated— решение не используется.
Это позволяет новичкам быстро понимать, что в проекте "историческое", а что текущее.
Метрики эффекта ADR
Чтобы ADR не воспринимался как "бумажная работа", полезно смотреть:
- время на архитектурные обсуждения в sprint planning;
- количество конфликтов по одним и тем же темам;
- скорость onboarding новых разработчиков.
Если эти показатели улучшаются, значит ADR-практика окупается.
Частые ошибки
- Слишком длинные ADR на 5-7 страниц.
- Отсутствие owner решения.
- Нет явного sunset/revisit для спорных компромиссов.
- Документы есть, но не используются в code review.
Итог
ADR — это не про документацию как цель. Это способ сделать архитектурные решения прозрачными и воспроизводимыми, особенно когда команда растёт и контекст теряется.