АссистентНовый вопросИсторияОбласти знаний
Партнёрские проектыМатериалы БРЭСпецпроектыСтать автором
Настроить видСменить языкИнформация
О РУВИКИ
Ответ на вопрос
ТехнологииБизнес и корпоративные ИТКорпоративная архитектура и моделированиеArchitectural Decision Records (ADR)

Architectural Decision Records (ADR)

Pause

Экспертиза РАН

Logo-ran-black.png
Проведена экспертиза
Российской академией наук
Подробнее
Aprove.svg

Экспертиза РАН

Arrow-Right.png
Logo-ran.png
Проведена экспертиза
Российской академией наук
Подробнее

Architectural Decision Records (сокр. ADR; рус. «записи архитектурных решений») — лаконичные документы, фиксирующие каждое архитектурно значимое решение, его контекст, рассмотренные альтернативы и последствия для программной системы.

Общие сведения
Что важно знать
Записи архитектурных решений
англ. Architectural Decision Records
Область использования Разработка программного обеспечения, Программная архитектура

Определение

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

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

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

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

Типы и виды

Структурные элементы ADR

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

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

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

  • drivers
  • confirmation
  • participants

Шаблоны ADR

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

Этапы работы

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

1. Планирование

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

2. Сбор и оформление информации

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

3. Анализ и принятие решения

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

4. Распространение

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

5. Обратная связь

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

Сравнение и отличия от смежной технологии

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

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

Преимущества и недостатки

Преимущества

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

Недостатки

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

Сферы применения

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

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

Инструменты для использования ADR

Платформы

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

Командные утилиты

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

Шаблоны

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

Интеграция с другими системами

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

Примечания

  1. ↑ Реестр архитектурных решений — devMix // tekBlueprint. Architectural Decision Record. Дата обращения: 20 июня 2025.
  2. ↑ 1 2 Architecture Decision Records - База знаний - Антон Агальцов. Шаблон ADR и рекомендации. Дата обращения: 20 июня 2025.
  3. ↑ 1 2 The Markdown ADR (MADR) Template Explained and Distilled. MADR Template Primer. Дата обращения: 20 июня 2025.
  4. ↑ ADR handout. ADR handout. Дата обращения: 20 июня 2025.
  5. ↑ ADR process - AWS Prescriptive Guidance. ADR Process – AWS Prescriptive Guidance. Дата обращения: 20 июня 2025.
  6. ↑ 8 best practices for creating architecture decision records — TechTarget. 4 best practices for creating ADRs. Дата обращения: 20 июня 2025.
  7. ↑ 1 2 Architecture decision record - Microsoft Azure Well-Architected Framework — Microsoft Learn. Architecture decision record – Microsoft WAF. Дата обращения: 20 июня 2025.
  8. ↑ Architecture Decision Records (ADR): Documenting Your Project’s Decisions - DEV Community. Documenting your project’s decisions. Дата обращения: 20 июня 2025.
  9. ↑ 1 2 Немного о подходе Architecture Decision Records / Хабр. ADR как «append-only log». Дата обращения: 20 июня 2025.
  10. ↑ Architecture Decisions: Rethink Decision-Making. Architecture Decisions in LeanIX. Дата обращения: 20 июня 2025.
  11. ↑ ADR Manager - Visual Studio Marketplace. ADR Manager VS Code extension. Дата обращения: 20 июня 2025.
  12. ↑ Slack & Teams Chat Interoperability: The Setup Guide. Slack-Teams interoperability. Дата обращения: 20 июня 2025.

Категории

© Правообладателем данного материала является АНО «Интернет-энциклопедия «РУВИКИ».
Использование данного материала на других сайтах возможно только с согласия АНО «Интернет-энциклопедия «РУВИКИ».
Pause