ADR — чек-лист самопроверки
Проверьте проект по пунктам ниже. Подробности — глава 1, итоги и FAQ.
Каталог и процесс
- Есть каталог ADR с нумерацией (
0001,0002…) и оглавлением. - ADR хранятся в Git (docs-as-code), не только в wiki.
- Новый ADR проходит Pull Request и review.
- В онбординге указана ссылка на каталог ADR (онбординг-пакет).
- Есть договорённость, кто инициирует ADR (архитектор, SA, тимлид).
Содержание записей
- Крупные решения за последний год имеют Accepted ADR.
- В ADR есть контекст и последствия (не только "выбрали X").
- Зафиксированы отвергнутые варианты для спорных тем.
- ADR ссылаются на PR/тикеты, где решение применено.
- Статусы актуальны: устаревшее — Deprecated или Superseded, не удалено.
Темы, которые обычно требуют ADR
- Выбор основной СУБД и стратегия миграций.
- Аутентификация (сессии, JWT, SSO, ЕСИА в госпроектах).
- Синхронные vs асинхронные интеграции (если влияет на систему).
- Монолит / сервисы или границы модулей.
- Кэш, сессии, очереди — если от них зависит масштабирование.
- Среды и секреты — если неочевидно из README.
Команда и онбординг
- Новый разработчик может ответить "почему Redis" за 15 минут чтения ADR.
- Архитектор в отпуске — есть Accepted ADR по критичным интеграциям.
- Postmortem с архитектурным выводом порождает новый или обновлённый ADR.
- В PR на архитектурное изменение есть ссылка Relates to ADR-NNN.
Аутсорс и госсектор
- В договоре или регламенте — нужно ли согласование ADR с заказчиком.
- ADR передаются заказчику при сдаче этапа (копия в репо или пакет документов).
- Для госэкспертизы ADR дополняют ТЗ обоснованием технических развилок.
Антипаттерны (отметьте, если есть)
- ADR пишут, но никто не читает — нет ссылок в PR и онбординге.
- Один ADR на всю архитектуру на 50 страниц.
- Accepted без review — решение одного человека.
- Старые ADR удалены — история потеряна.
- Confluence расходится с Git — две версии правды.
Три и более антипаттерна — аудит процесса с тимлидом.
Вопросы для устной самопроверки
- Где лежит каталог ADR в репозитории?
- Назовите номер ADR по выбору основной БД.
- Чем Proposed отличается от Accepted?
- Что сделать со старым ADR при переходе на Kafka?
- Кто ревьюит ADR в вашей команде?
- Есть ли ADR, порождённый postmortem?
- Как ADR связан с NFR?
- Нужен ли ADR на мелкий рефакторинг одного класса?
- Как заказчик в аутсорсе узнаёт об архитектурном решении?
- Что быстрее — spike или ADR при неизвестном брокере?
Минимальный план улучшения за спринт
Если чек-лист в основном пустой:
- Создать
docs/adr/README.mdс оглавлением. - Написать 3 Accepted ADR на уже принятые решения (БД, auth, деплой).
- Добавить в шаблон PR поле "ADR".
- Упомянуть ADR в wiki для онбординга.