ADR: Architecture Decision Records

ADR (Architecture Decision Record) — короткий документ, фиксирующий важное архитектурное решение: контекст, варианты, выбор и причины.

Зачем нужно

Архитектурные решения теряются в переписках, commit-сообщениях и головах людей, уволившихся год назад. ADR создаёт постоянный письменный след: новый член команды читает папку docs/adr/ и понимает, почему проект устроен именно так. Это снижает bus factor и ускоряет onboarding.

Где используется

  • Любой долгосрочный проект — когда решений накапливается больше 5–10
  • Open source — объясняет внешним контрибьюторам причины устройства кодовой базы
  • Стартапы и аутсорс — при смене команды или передаче проекта

Структура ADR

Классический формат по Michael Nygard:

# ADR-001: Использование PostgreSQL вместо MongoDB

## Статус
Принято

## Контекст
Нужна СУБД для хранения заказов. Данные строго реляционные:
пользователи → заказы → позиции → товары.

## Рассмотренные варианты
1. MongoDB — гибкая схема, но JOIN-ы неудобны
2. PostgreSQL — реляционная, ACID, JSON-поддержка есть
3. MySQL — похоже, но хуже с JSON и оконными функциями

## Решение
PostgreSQL. Данные реляционные по природе, нужны транзакции,
команда знает SQL.

## Последствия
+ Строгая схема, легко делать отчёты
+ ACID-транзакции из коробки
− Миграции схемы при изменениях

## Дата
2026-03-15

Статусы ADR

Proposed   → обсуждается
Accepted   → принято и применяется
Deprecated → устарело, но оставлено для истории
Superseded → заменено ADR-XXX

Где хранить

project/
  docs/
    adr/
      0001-использование-postgresql.md
      0002-rest-vs-graphql.md
      0003-монорепо-vs-polyrepo.md

Нумерация — монотонно возрастающая, никогда не удалять, только менять статус.

Когда писать ADR

Пишите ADR, когда:

  • выбираете технологию/фреймворк/БД
  • меняете архитектурный стиль (MVC → event-driven)
  • принимаете решение, с которым коллеги могут не согласиться
  • делаете что-то нестандартное

Не нужно для: выбора библиотеки форматирования дат, правил именования переменных.

Частые ошибки

Ошибка Проблема Решение
Писать ADR после того, как решение устарело Теряется контекст Писать в момент принятия решения
Описывать только выбранный вариант Нет понимания trade-off Всегда включать отвергнутые альтернативы
Обновлять ADR вместо создания нового Теряется история Создавай новый ADR со статусом Superseded
ADR только в головах Tech Lead Знания уходят с человеком Коммитить в репозиторий

Связанные темы

Ресурсы