В IT часто хорошо документируют что построено, но слабо фиксируют почему выбрано именно так. В итоге через полгода команда уже не помнит, зачем отказалась от Kafka, почему выбрала монолит вместо микросервисов или откуда взялась PostgreSQL. Здесь и помогают ADR — Architecture Decision Records.
Что такое ADR
ADR — это короткий документ, который фиксирует важное архитектурное решение, его контекст, альтернативы и последствия. Это не толстая документация ради документации, а понятный след принятия решений.
Зачем нужны ADR
- сохраняют логику выбора, а не только итог
- ускоряют онбординг новых разработчиков
- снижают количество повторных обсуждений одних и тех же вопросов
- помогают в аудите и техдолге
- упрощают развитие системы при смене команды
Когда писать ADR
ADR стоит создавать, если решение:
- влияет на архитектуру или инфраструктуру
- затрагивает производительность, безопасность, масштабируемость
- дорого в изменении
- вызывает споры в команде
- задаёт стандарт для будущих задач
Типичная структура ADR
- Title — название решения
- Status — proposed / accepted / deprecated / superseded
- Context — в какой ситуации принимается решение
- Decision — что именно выбрано
- Alternatives — какие варианты рассматривались
- Consequences — плюсы, минусы, риски, компромиссы
Пример
ADR-007: Использовать REST вместо GraphQL для публичного API
- Context: нужен API для внешних интеграций, важны предсказуемость, простая поддержка и низкий порог входа
- Decision: выбрать REST
- Alternatives: GraphQL, gRPC
- Consequences:
- — проще документация и отладка
- — быстрее запуск интеграторов
- — меньше гибкости в выборке данных
- — возможен overfetching
Лучшие практики ✅
- пишите ADR коротко: 1 документ = 1 решение
- храните рядом с кодом в репозитории
- используйте нумерацию: 0001-record-architecture-decisions.md
- не переписывайте историю задним числом — создавайте новый ADR, если решение изменилось
- делайте формулировки проверяемыми и конкретными
Частые ошибки
- превращать ADR в многостраничный трактат
- фиксировать очевидные мелочи, а не значимые решения
- не описывать альтернативы
- не обновлять статус документа
- писать абстрактно: “выбрали современный стек” без критериев
Итог
ADR — это простой инструмент архитектурной памяти команды 🧠. Он помогает не терять контекст, принимать решения осознанно и уменьшать хаос в развитии системы. Чем сложнее продукт и выше текучка в команде, тем ценнее такой подход.
📌 Сохраняйте в практику: один важный архитектурный выбор — один ADR.
И загляните в подборку каналов про IT — там много полезного про архитектуру, разработку и инженерные практики.