«Почему у нас здесь Kafka, а не RabbitMQ?» — спрашивает новый разработчик. «Почему заказы хранятся в отдельной базе?» — спрашивает аудитор. «Почему мы не используем GraphQL?» — спрашивает новый архитектор, и команда в третий раз за год начинает то же обсуждение. Люди, принимавшие решения, ушли или не помнят деталей, протоколы встреч потерялись, в коде видно что сделано, но не почему. Architecture Decision Records (ADR) — простой способ сохранить ответ на вопрос «почему» в момент, когда он ещё известен.
Что такое ADR
ADR — короткий документ, фиксирующий одно архитектурно значимое решение: в каком контексте оно принималось, какие были варианты, что выбрали и какие у этого последствия. Набор таких записей — журнал решений (decision log) проекта.
Подход популяризировал Майкл Найгард в статье 2011 года «Documenting Architecture Decisions». С тех пор ADR стали стандартной практикой: их рекомендуют Thoughtworks Technology Radar, руководства AWS, Google Cloud и Microsoft Azure по архитектуре, их используют открытые проекты и государственные команды.
Ключевые свойства:
- одно решение — одна запись;
- коротко: обычно одна-две страницы;
- неизменяемость: принятую запись не переписывают; если решение меняется, пишут новую, которая заменяет старую;
- рядом с кодом: в репозитории, в текстовом формате.
Какие решения записывать
Архитектурно значимое решение — то, которое дорого изменить потом. Признаки:
- влияет на структуру системы: разбиение на сервисы, границы модулей;
- влияет на нефункциональные характеристики: производительность, надёжность, безопасность;
- определяет технологию: СУБД, брокер, фреймворк, облачный сервис;
- определяет способ интеграции: синхронно или через события, формат контрактов;
- затрагивает несколько команд;
- принималось через спор, и альтернативы были реальными;
- отступает от стандартов компании.
Не нужно записывать решения, которые легко отменить или которые следуют из уже принятых правил: имя переменной, версия библиотеки внутри одной мажорной версии, выбор между двумя эквивалентными способами написать цикл.
Для системного аналитика тоже есть свои значимые решения: модель данных ключевой сущности, выбор между синхронной и асинхронной интеграцией, формат идентификаторов, политика хранения истории, источник истины для данных, используемых несколькими системами.
Шаблон Найгарда
Исходный шаблон из пяти разделов до сих пор самый популярный:
# 7. Публиковать события заказов через Transactional Outbox
Дата: 2026-03-14
Статус: Принято
## Контекст
Сервис заказов должен публиковать события в Kafka для склада,
доставки и аналитики. При текущей реализации событие отправляется
после фиксации транзакции, и при сбое между фиксацией и отправкой
события теряются: за квартал — 14 потерянных заказов на складе.
Распределённые транзакции между PostgreSQL и Kafka не поддерживаются.
## Решение
События записываются в таблицу outbox в той же транзакции, что и
заказ. Публикацию в Kafka выполняет Debezium (CDC) по журналу
транзакций PostgreSQL.
## Последствия
+ события не теряются; заказ и событие фиксируются атомарно
+ сервис заказов не зависит от доступности Kafka при записи
− доставка «хотя бы один раз»: потребители обязаны быть идемпотентными
− новый компонент инфраструктуры (Debezium) — нужна эксплуатация
− задержка публикации до 1–2 секунд
Раздел «Контекст» — самый важный и самый часто недописываемый. Через два года решение может выглядеть странным, и только контекст объяснит, почему оно было разумным: какие ограничения, сроки, требования и факты действовали тогда.
MADR и другие шаблоны
MADR (Markdown Architectural Decision Records) — более подробный шаблон, в котором явно описываются рассмотренные варианты:
- Контекст и проблема — описание ситуации, часто в форме вопроса;
- Факторы решения (decision drivers) — что важно: стоимость, скорость, надёжность, компетенции команды;
- Рассмотренные варианты — список альтернатив;
- Итоговое решение — выбранный вариант и обоснование;
- Последствия — положительные и отрицательные;
- Плюсы и минусы вариантов — для каждой альтернативы;
- Подтверждение — как проверить, что решение реализовано (тест, ревью, метрика).
Для сравнения вариантов удобна таблица:
| Фактор | Outbox + CDC | Outbox + опрос | Отправка после commit |
|---|---|---|---|
| Гарантия доставки | да | да | нет |
| Задержка | 1–2 с | до интервала опроса | минимальная |
| Нагрузка на БД | низкая | запросы опроса | нет |
| Новая инфраструктура | Debezium | нет | нет |
Y-statement — сжатая форма в одно предложение, удобная для небольших решений:
В контексте публикации событий заказов, столкнувшись с потерей событий при сбоях, мы выбрали Transactional Outbox с CDC и отвергли отправку после commit и опрос таблицы, чтобы достичь гарантированной доставки без нагрузки на БД, приняв необходимость идемпотентных потребителей и эксплуатации Debezium.
Шаблон выбирают под команду. Главное — единообразие и обязательные разделы «контекст» и «последствия».
Жизненный цикл
У каждой записи есть статус:
- Предложено (proposed) — запись открыта на обсуждение, обычно как пул-реквест;
- Принято (accepted) — решение согласовано и действует;
- Отклонено (rejected) — рассмотрели и не приняли; запись сохраняется, чтобы не обсуждать вариант заново;
- Устарело (deprecated) — решение больше не актуально, но замены нет (например, функциональность удалена);
- Заменено (superseded by ADR-N) — решение пересмотрено, действует новая запись.
Неизменяемость — ключевой принцип. Если через год команда переходит с Debezium на опрос таблицы, ADR-7 не переписывают. Создают ADR-23 «Перейти на опрос таблицы outbox» с новым контекстом, а в ADR-7 меняют только статус: «Заменено ADR-23». Так сохраняется история рассуждений, а не только итоговое состояние.
Отклонённые записи не менее ценны, чем принятые: они избавляют от повторных обсуждений и показывают, что альтернатива была рассмотрена.
Где хранить
- В репозитории — самый распространённый вариант: каталог
docs/adr/илиdocs/decisions/, файлы0001-use-postgresql.md,0002-kafka-for-events.md. Записи проходят ревью вместе с кодом, история видна в git. - Отдельный репозиторий — для решений уровня нескольких систем или всей компании.
- Вики — допустимо, если в команде нет практики Docs as Code, но теряются ревью и связь с кодом.
Есть утилиты для создания и нумерации записей: adr-tools, log4brains (ещё и публикует журнал как сайт), шаблоны MADR. Но начать можно и без них — с одного Markdown-файла.
Как встроить в процесс
- Решение начинается с ADR. Если на обсуждении звучит «давайте сделаем так», кто-то берёт задачу написать запись со статусом «Предложено».
- Обсуждение — в пул-реквесте. Комментарии к записи остаются в истории; итог переносится в раздел «Решение».
- Принятие — слияние пул-реквеста со статусом «Принято». Кто одобряет — зависит от уровня решения: команда, архитектор, архитектурный комитет.
- Ссылки из постановок, задач и кода на номер ADR: «см. ADR-7».
- Регулярный просмотр — раз в квартал пробежать по журналу: какие решения устарели, какие стоит пересмотреть.
Типичные ошибки
- Нет контекста — «Решили использовать Kafka». Почему, по сравнению с чем, при каких условиях — неизвестно.
- Нет минусов — у каждого решения есть цена. Если последствия только положительные, запись выглядит как реклама и не помогает при пересмотре.
- Задним числом — запись пишут через полгода, контекст уже восстановлен по памяти и подогнан под результат.
- Слишком подробно — десять страниц вместо двух; такие записи не пишут и не читают.
- Слишком мелко — запись на каждое решение, журнал превращается в шум.
- Переписывание принятых записей — теряется история, и непонятно, что действовало раньше.
- ADR без связи с реализацией — решение принято, но в коде сделано иначе, и никто не заметил.
ADR и роль аналитика
Системный аналитик часто оказывается ближе всех к контексту решения: он знает требования, ограничения, договорённости с бизнесом и смежными системами. Поэтому аналитик может и должен:
- писать ADR для решений в своей зоне: модели данных, способы интеграции, контракты;
- дополнять контекст в записях архитекторов: бизнес-требования, объёмы, SLA;
- ссылаться на ADR из постановок, вместо того чтобы пересказывать обоснование;
- проверять, что постановка не противоречит принятым решениям.
Итог
ADR — минимальная, но очень эффективная практика: одна короткая запись на каждое значимое решение, с контекстом, вариантами и последствиями. Записи не переписываются, а заменяются новыми, и журнал решений становится историей рассуждений проекта. Это экономит время на повторных спорах, ускоряет вход новых людей и помогает осознанно пересматривать решения, когда контекст меняется.
ADR удобно писать в редакторе Markdown и хранить в проекте вместе с остальной документацией — так видна история изменений каждой записи (гайд «История версий»), а обсуждать их можно вместе с командой (гайд «Совместная работа над проектом»). Как устроен процесс документации рядом с кодом — в статье «Docs as Code».
