Architecture Decision Records — краткие записи о принятых архитектурных и значимых технических решениях.
Назначение
- Зафиксировать контекст, варианты и обоснование решения.
- Дать возможность новым участникам и командам понять «почему так».
- Сохранять историю решений при смене людей.
Формат записи
Каждый ADR обычно содержит:
- Заголовок — краткое название решения.
- Статус — принято / отложено / устарело.
- Контекст — какая проблема или возможность.
- Варианты — рассмотренные варианты (кратко).
- Решение — что выбрано и почему.
- Последствия — что меняется, какие ограничения или риски.
Хранятся в репозитории (например, docs/governance/adr/) с нумерацией: ADR-001-short-title.md.
Примеры тем для ADR
- Выбор Transactional Outbox для публикации событий в Kafka.
- Использование gRPC для internal API и REST для public.
- Database per Service и отказ от распределенных транзакций.
- Выбор Argon2id для хранения паролей и constant-time verification.
- Структура слоев Clean Architecture в Python-сервисах.
- Версионирование proto-контрактов и политика обратной совместимости.
Связанные страницы
- Принципы архитектуры — принципы проектирования
- Обзор бэкенда — реализованные решения
- Поток событий — решение по событиям