Архитектурные решения принимаются каждый день. Записываются — почти никогда.

Если вы когда-нибудь открывали проект, которому больше двух лет, и задавались вопросом «почему здесь используется Kafka, а не RabbitMQ?» — поздравляю, вы столкнулись с классической проблемой. Человек, который принял это решение, уже уволился. Его коллега, который «вроде бы помнит», помнит неправильно. А в Confluence лежит страница «Архитектура v2 (ФИНАЛ) (копия)», последний раз обновлённая в 2023 году.

Architecture Decision Records (ADR) — это практика, которая решает именно эту проблему. Не революционная, не модная, не требующая новых инструментов. Просто привычка записывать, почему вы решили сделать так, а не иначе. И делать это в формате, который переживёт и вас, и ваш текущий проект.

Что такое ADR и почему это важно для системного анализа

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

ADR — это не техническое задание и не RFC. Это запись в бортовом журнале корабля. Капитан сменится, но журнал останется — и следующий капитан поймёт, почему корабль повернул именно сюда.

Почему это критично именно для системных аналитиков и архитекторов:

• Контекст теряется быстрее, чем код. Через полгода вы сами не вспомните, почему выбрали синхронное взаимодействие вместо асинхронного. А через год придёт новый архитектор и «оптимизирует» — сломав всё, что вы так аккуратно выстраивали.
• Решения без документации превращаются в догмы. «Мы всегда так делали» — худший аргумент в архитектуре. ADR превращает догму обратно в обоснованный выбор, который можно пересмотреть при изменении условий.
• Онбординг ускоряется в разы. Новый член команды читает 15–20 ADR и понимает не только как устроена система, но и почему.

Если вы уже знакомы с предметно-ориентированным проектированием (DDD), то ADR — это естественное дополнение. DDD говорит что проектировать, ADR фиксирует почему вы спроектировали именно так.

Из чего состоит ADR: анатомия артефакта

ADR — это не свободная проза и не эссе на тему «как я провёл архитектуру». У него есть чёткая структура, и именно эта структура делает его полезным. Давайте разберём каждый элемент.

graph TD
  ADR["ADR — Architecture<br/>Decision Record"]
  ADR --> ID["Номер и заголовок<br/><i>ADR-001: Выбор брокера сообщений</i>"]
  ADR --> STATUS["Статус<br/><i>Proposed → Accepted → Deprecated</i>"]
  ADR --> CONTEXT["Контекст<br/><i>Какая проблема или задача стоит?</i>"]
  ADR --> DECISION["Решение<br/><i>Что именно мы решили?</i>"]
  ADR --> ALTS["Рассмотренные альтернативы<br/><i>Что ещё рассматривали и почему отвергли?</i>"]
  ADR --> CONS["Последствия<br/><i>Что получим, чем заплатим?</i>"]
  ADR --> META["Метаданные<br/><i>Дата, автор, участники обсуждения</i>"]

  style ADR fill:#4a90d9,stroke:#2c5f8a,color:#fff
  style ID fill:#7b68ee,stroke:#5a4db2,color:#fff
  style STATUS fill:#f0a500,stroke:#c88400,color:#fff
  style CONTEXT fill:#50c878,stroke:#3a9a5c,color:#fff
  style DECISION fill:#50c878,stroke:#3a9a5c,color:#fff
  style ALTS fill:#e0e0e0,stroke:#999,color:#333
  style CONS fill:#f0a500,stroke:#c88400,color:#fff
  style META fill:#e0e0e0,stroke:#999,color:#333

На диаграмме выше — полная структура ADR как артефакта. Каждый блок — обязательный элемент, без которого запись теряет смысл. Разберём подробнее.

Номер и заголовок

Формат: ADR-NNN: Краткое описание решения. Номер — порядковый, никогда не переиспользуется (даже если ADR отменён). Заголовок должен быть понятен без контекста: не «Про базу данных», а «Выбор PostgreSQL в качестве основной СУБД для сервиса заказов».

Статус

ADR проходит через жизненный цикл:

Важно: ADR никогда не удаляется. Даже если решение отменено — запись остаётся с пометкой Superseded by ADR-042. Это и есть главная ценность: история решений, а не только текущее состояние.

Контекст

Самая важная секция. Здесь вы описываете ситуацию, в которой принималось решение. Какие ограничения были? Какие требования? Какие технические и бизнесовые факторы влияли?

Плохой контекст: «Нам нужен брокер сообщений». Хороший контекст: «Сервис уведомлений обрабатывает до 50 000 событий в минуту. Текущая синхронная модель через REST приводит к таймаутам при пиковых нагрузках (Black Friday). Нужно асинхронное взаимодействие с гарантией доставки. Бюджет на инфраструктуру ограничен, команда из 4 человек, опыт работы с Kafka — у одного разработчика».

Решение

Формулировка: что именно решили сделать. Конкретно, без воды.

«Используем RabbitMQ как брокер сообщений для асинхронного взаимодействия между сервисом заказов и сервисом уведомлений. Протокол — AMQP, паттерн — pub/sub с durable queues».

Рассмотренные альтернативы

Здесь перечисляются варианты, которые рассматривались, и причины отказа от каждого. Это ключевая секция для будущих читателей — она отвечает на вопрос «а почему не X?».

Последствия

Честный анализ того, что вы получаете и чем платите. И положительные, и отрицательные последствия.

• Плюсы: снижение связанности, устойчивость к пиковым нагрузкам, гарантия доставки сообщений
• Минусы: дополнительная инфраструктура, eventual consistency вместо strong consistency, необходимость мониторинга очередей

Жизненный цикл ADR в проекте

ADR — это не одноразовая записка. Он живёт вместе с проектом и проходит через несколько этапов.

stateDiagram-v2
  [*] --> Proposed: Инициатор создаёт ADR
  Proposed --> Accepted: Команда согласовала
  Proposed --> Rejected: Команда отклонила
  Accepted --> Superseded: Новое решение заменяет старое
  Accepted --> Deprecated: Решение устарело
  Rejected --> [*]
  Superseded --> [*]
  Deprecated --> [*]

  note right of Proposed
      Обсуждение на review,<br/>комментарии в PR
  end note

  note right of Accepted
      Решение действует,<br/>команда следует ему
  end note

  note left of Superseded
      Ссылка на новый ADR,<br/>старый не удаляется
  end note

Диаграмма показывает жизненный цикл ADR: от предложения до принятия (или отклонения), и далее — до замены или устаревания. Обратите внимание: состояние Rejected — это тоже ценная информация. Оно говорит: «мы рассматривали этот вариант и обоснованно отказались».

Когда создавать ADR

Не нужно записывать каждое решение — иначе вы утонете в бюрократии (и через месяц забросите практику). ADR стоит создавать, когда:

• Решение влияет на структуру системы — выбор базы данных, протокола, архитектурного стиля
• Решение трудно или дорого отменить — миграция на другой фреймворк, выбор облачного провайдера
• Решение вызывает дискуссию в команде — если двое и больше людей не согласны, запишите аргументы обеих сторон
• Решение связано с компромиссом — вы осознанно жертвуете чем-то ради чего-то другого

Не нужен ADR для: выбора библиотеки форматирования дат, решения использовать camelCase вместо snake_case, или того, на каком порту запускать dev-сервер (хотя, зная некоторые команды, и на этот счёт бывают баталии).

Где хранить ADR: рядом с кодом, а не в Confluence

Это принципиальный момент. ADR должны лежать в репозитории проекта, вместе с кодом. Не в Confluence, не в Google Docs, не в голове тимлида.

1
project-root/
2
├── docs/
3
│   └── adr/
4
│       ├── 001-выбор-postgresql.md
5
│       ├── 002-rabbitmq-для-уведомлений.md
6
│       ├── 003-переход-на-модульный-монолит.md
7
│       └── template.md
8
├── src/
9
└── ...

Почему именно в репозитории:

• Версионируется через Git. Вы видите, кто, когда и зачем менял решение. Если вы уже знакомы с основами Git, то понимаете, насколько это ценно.
• Проходит code review. ADR создаётся через Pull Request — команда обсуждает решение до того, как оно принято, а не после.
• Не теряется. Confluence-страницы забываются, ссылки ломаются, доступы отзываются. Репозиторий живёт, пока живёт проект.
• Привязан к контексту. ADR про выбор ORM лежит рядом с кодом, который этот ORM использует.

Шаблон ADR: что писать и как оформлять

Существует несколько популярных шаблонов. Самый распространённый — формат Майкла Найгарда (Michael Nygard), автора книги «Release It!». Вот адаптированная версия:

1
# ADR-NNN: Заголовок решения
2

3
## Статус
4
Proposed | Accepted | Superseded by ADR-XXX | Deprecated
5

6
## Дата
7
YYYY-MM-DD
8

9
## Участники
10
Кто принимал участие в обсуждении
11

12
## Контекст
13
Описание ситуации, проблемы, ограничений.
14
Почему вообще потребовалось принимать решение?
15

16
## Решение
17
Что именно решили сделать. Конкретно и однозначно.
18

19
## Альтернативы
20
Какие варианты рассматривались и почему отвергнуты.
21

22
## Последствия
23
Что получаем (плюсы) и чем платим (минусы).
24
Какие новые задачи или ограничения появляются.

Практический пример: выбор архитектурного стиля

Давайте посмотрим, как выглядит реальный ADR для решения, с которым сталкивается почти каждая команда.

1
# ADR-003: Переход на модульный монолит
2

3
## Статус
4
Accepted
5

6
## Дата
7
2026-03-15
8

9
## Участники
10
Иванов А. (архитектор), Петрова М. (тимлид), Сидоров К. (аналитик)
11

12
## Контекст
13
Текущий монолит на 120k строк стал сложен в поддержке.
14
Время сборки — 12 минут, деплой — 40 минут.
15
Команда из 8 человек работает над 4 бизнес-доменами,
16
конфликты при мерже — ежедневные.
17
Переход на микросервисы обсуждался, но у команды нет
18
опыта эксплуатации распределённых систем, нет DevOps-инженера,
19
бюджет на инфраструктуру ограничен.
20

21
## Решение
22
Переводим монолит на модульную архитектуру с изоляцией
23
по бизнес-доменам: Заказы, Платежи, Каталог, Клиенты.
24
Модули взаимодействуют через внутренние контракты (интерфейсы).
25
Каждый модуль владеет своей частью схемы БД.
26

27
## Альтернативы
28
- Микросервисы: отвергнуто из-за отсутствия DevOps-компетенций
29
  и бюджета на инфраструктуру (Kubernetes, service mesh).
30
- Оставить как есть: неприемлемо, время вывода фич растёт,
31
  количество багов при релизе увеличивается.
32

33
## Последствия
34
Плюсы: чёткие границы модулей, параллельная разработка,
35
подготовка к возможному переходу на микросервисы.
36
Минусы: рефакторинг займёт ~3 месяца, потребуется пересмотр
37
CI/CD пайплайна, команде нужно освоить DDD-подход.

Этот пример показывает, как ADR связывает архитектуру с реальностью: бюджет, компетенции команды, бизнес-ограничения. Если вам интересна тема модульного монолита подробнее — загляните в полное руководство по модульному монолиту.

ADR и процесс принятия решений в команде

sequenceDiagram
  participant I as Инициатор
  participant R as Репозиторий
  participant T as Команда
  participant A as Архитектор

  I->>R: Создаёт PR с ADR<br/>(статус: Proposed)
  R->>T: Уведомление о новом PR
  T->>R: Комментарии и вопросы
  I->>R: Обновляет ADR<br/>по результатам обсуждения
  T->>A: Эскалация спорных<br/>моментов
  A->>R: Финальный review
  A->>R: Approve PR<br/>(статус: Accepted)
  R->>T: ADR принят,<br/>решение зафиксировано

  Note over I,A: Весь процесс — 2-5 дней.<br/>Решение задокументировано навсегда.

Диаграмма показывает типичный процесс принятия архитектурного решения через ADR. Обратите внимание: решение обсуждается до того, как его начинают реализовывать. Это принципиальное отличие от подхода «сделаем, а потом задокументируем» (спойлер: «потом» — это никогда).

Кто может создавать ADR

Распространённое заблуждение: ADR — это прерогатива архитектора. На самом деле, инициировать ADR может любой член команды. Разработчик, который первым столкнулся с проблемой, видит контекст лучше всех. Аналитик, который собрал требования, понимает бизнес-ограничения. Тестировщик, который нашёл системный паттерн в багах — тоже имеет право голоса.

Архитектор в этом процессе — не единоличный принимающий решения, а фасилитатор и финальный ревьюер. Он следит за согласованностью решений между собой и с общей стратегией.

Типичные ошибки при внедрении ADR

Ошибка 1: Слишком много деталей

ADR — это не проектный документ на 20 страниц. Один ADR = одно решение. Если ваш ADR занимает больше двух экранов — вы, скорее всего, пытаетесь решить несколько вопросов сразу. Разбейте на несколько ADR.

Ошибка 2: Отсутствие альтернатив

ADR без секции альтернатив — это не ADR, а объявление о решении. Главная ценность — именно в обосновании: почему это, а не то. Если альтернатив не было — так и напишите, но объясните почему (например, «единственная СУБД, сертифицированная по требованиям регулятора»).

Ошибка 3: Запись постфактум

«Мы уже всё сделали, давайте задним числом ADR напишем» — это лучше, чем ничего, но хуже, чем ADR до реализации. Когда решение уже принято и реализовано, вы подсознательно опускаете альтернативы и преувеличиваете плюсы выбранного варианта. Старайтесь писать ADR до или во время реализации.

Ошибка 4: Забросить практику через месяц

Самый частый сценарий. Команда создаёт 5 ADR с энтузиазмом, потом «становится некогда», и папка docs/adr/ покрывается пылью. Лечится просто: добавьте пункт «Нужен ли ADR?» в чеклист code review для PR, которые затрагивают архитектуру.

ADR в контексте других практик проектирования

ADR не существует в вакууме. Он встраивается в экосистему практик:

Инструменты для работы с ADR

Минимальный набор — это Markdown-файлы в Git. Но есть и инструменты, которые упрощают работу:

• adr-tools (CLI) — генерирует шаблоны, управляет нумерацией, создаёт оглавление. Устанавливается через brew install adr-tools.
• Log4brains — веб-интерфейс для ADR, автоматически генерирует сайт из Markdown-файлов в репозитории.
• Встроенные шаблоны в GitHub/GitLab — можно добавить ADR-шаблон в .github/PULL_REQUEST_TEMPLATE/ для автоматического создания при архитектурных PR.

Но не переусложняйте. Если вам хватает папки docs/adr/ и шаблона в Markdown — этого достаточно. Инструменты — это приятное дополнение, а не необходимость. Работает — не трогай (но запиши, почему работает, в ADR).

Заключение

ADR — это, пожалуй, одна из немногих практик в архитектуре, которая стоит ровно ноль рублей, занимает 30 минут на запись и экономит десятки часов в будущем. Никаких новых инструментов, никаких сертификаций, никаких многодневных тренингов.

Просто привычка: приняли решение — записали. Рассматривали альтернативы — зафиксировали. Понимаете последствия — перечислили. Всё.

Через год, когда новый коллега спросит «а почему у нас тут MongoDB?», вы не будете чесать затылок и бормотать «ну, исторически так сложилось». Вы откроете docs/adr/007-выбор-mongodb-для-каталога.md и покажете ему точный контекст, альтернативы и обоснование.

Это не серебряная пуля. Это бортовой журнал. И корабли, которые ведут бортовой журнал, как правило, реже садятся на мель.

P.S. Если вы дочитали до конца и подумали «надо бы у нас в проекте завести» — создайте первый ADR прямо сейчас. Пусть он будет про решение завести ADR. Мета? Безусловно. Но зато практика начнётся с первого же дня.