Architectural Decision Records (ADR)

ADR — это единичная запись, которая:

1. описывает исходную проблему и контекст;
2. формулирует принятое решение и его обоснование;
3. перечисляет альтернативы с причинами отказа от них;
4. указывает потенциальные последствия решения.

Цели применения:

• сохранение коллективной памяти проекта;
• обеспечение прозрачности и подотчётности;
• ускорение онбординга новых участников;
• предотвращение повторных дискуссий^[1].

Обязательные поля^[2]:

• Title — номер и краткое название;
• Status — proposed / accepted / rejected / deprecated / superseded;
• Context — описание проблемы, требований и ограничений;
• Decision — суть принятого решения;
• Alternatives — рассмотренные варианты;
• Consequences — последствия (в MADR v3.0 — единый текст без деления на «плюсы» и «минусы»)^[3];
• Date — дата утверждения.

Необязательные поля:

• drivers
• confirmation
• participants

• Шаблон Майкла Нигарда — формат «Контекст — Решение — Последствия»^[4];
• MADR — Markdown-ориентированный шаблон с явным перечислением альтернатив и драйверов;
• Any Decision Records — использование MADR для любых значимых решений^[3].

Процесс применения ADR состоит из пяти повторяющихся этапов^[5].

На этом этапе выявляются архитектурно значимые требования (ASR) и принимается решение о необходимости создания отдельного ADR для каждого из них. Команда определяет, какие вопросы требуют формализации в виде записи архитектурного решения.

Команда собирает необходимый контекст, формулирует возможные альтернативы и заполняет черновик ADR по выбранному шаблону^[6]. На этом этапе фиксируются все исходные данные, ограничения, требования и варианты решений.

Варианты обсуждаются с заинтересованными сторонами, проводится анализ плюсов и минусов каждого подхода. После достижения консенсуса команда фиксирует принятое решение и обновляет поле «Status» в ADR^[7].

Утверждённый ADR публикуется в общем репозитории или корпоративной вики. Для информирования команды используются pull-request, чат-боты или другие средства уведомления^[8].

Команда отслеживает актуальность принятого решения. При изменении контекста или появлении новых обстоятельств создаётся новый ADR, который ссылается на предыдущий и получает статус «supersedes»^[9].

ADR отличается от традиционной технической документации тем, что фиксирует именно обоснование решения, а не его реализацию. Документ:

• короткий (1-2 страницы);
• неизменяемый после утверждения — изменения оформляются новой записью;
• хранится рядом с кодом и проходит тот же процесс ревью.

• Историческая прослеживаемость решений;
• Прозрачность и улучшение коммуникаций;
• Быстрый онбординг новых сотрудников;
• Снижение риска повторных дискуссий;
• Поддержание согласованности архитектуры^[7].

• Дополнительные трудозатраты на поддержание актуальности;
• Риск избыточной документации при фиксировании малозначимых решений^[9];
• Возможная негибкость при восприятии ADR как «неизменяемых правил»;
• Необходима дисциплина для пометки устаревших записей^[10].

ADR применяются в самых разных областях разработки ПО^[2]:

• финансовые и банковские системы;
• госсектор и критическая инфраструктура;
• облачные и микросервисные решения;
• электронная коммерция;
• долгоживущие корпоративные проекты с частой сменой команд.

• SAP LeanIX — централизованное хранилище ADR с привязкой к корпоративному портфелю приложений^[11];
• ServiceNow EA Workspace — версионирование и жизненный цикл записей;
• Backstage ADR plugin — визуализация и поиск решений внутри портала разработчиков.

• adr-tools, pyadr, dotnet-adr — генерация и изменение статусов ADR;
• Log4brains — ведение ADR из IDE и публикация статического сайта;
• Расширения ADR Manager для VS Code и IntelliJ IDEA^[12].

• минималистичный шаблон Майкла Нигарда;
• широкораспространённый MADR (Markdown ADR);
• корпоративные кастомные шаблоны с дополнительными полями («Security impact», «Cost»).

• Git — ADR хранится рядом с кодом, проходит ревью;
• CI/CD (Jenkins, GitHub Actions) — линтинг шаблонов и автогенерация HTML-документации;
• Jira — ссылки на ADR в задачах для трассируемости;
• Confluence / MediaWiki — синхронизация текста для широкой аудитории;
• Slack / Microsoft Teams — вебхуки с уведомлениями о новых или изменённых ADR^[13].