ADR (Architecture Decision Record) или Мы же теперь умные?

«Свобода не делает людей счастливыми, она просто делает их людьми.»

Меня зовут Евгений, я ведущий разработчик отдела SAP разработки, и в зависимости от настроения надеваю маски Техлида или Архитектора.

Большинству из нас рано или поздно приходится сталкиваться с ситуацией, когда есть проблема, достаточно сложная и долгоиграющая. Неважно даже, техническая она или организационная.
Главное что ее не решить с наскока, более того, даже чтобы эту самую проблему сформулировать, нужно поговорить с людьми, посидеть, подумать, описать, и… повторить раз несколько.
А еще есть одна особенность, что бы вы не решили, обязательно через некоторое время придет человек с вопросом «А почему так? А зачем?» и совсем немного подумав, скажет «Да у вас лапки не из того места растут. Я могу лучше!». Пфф.
Так как с этим приходится жить, то я решил сформулировать буквами некоторые наблюдениявыводы о подобных ситуациях. В первую очередь для себя, но может и вы что то полезное найдете.

Если подойти более формально, то статья описывает подход к документированию архитектурных решений с помощью ADR.
Целевая аудитория статьи (по классике) — Архитекторы и ТехЛиды. Начинающие естественно, так как опытные сами кого хочешь научат. Если время найдут.
Хотя, сейчас скажу крамольную мысль, ADR (Architectural Decision Record) это совсем не про IT, или не только про IT. ADR это о том, что что головой можно думать, а не только в нее есть.
Неплохо пошутил да? Надеюсь тапком не прилетит:)
А поэтому, материал про запись архитектурных решений будет полезен любым специалистам, которым приходится думать и принимать сложные решения.

Интересно? Читайте статью под катом.

Оглавление

• Введение. Зачем нам ADR или Амнезия она такая ^[1]

• 1.Что такое ADR? ^[2]

• 2. Анатомия ADR — основные разделы ^[3]

• 3. Роли в процессе работы с ADR ^[4]

• 4. Кто и зачем использует ADR? ^[5]

• 5. Достоинства, ограничения и антипаттерны ^[6]

• 6. Как внедрить ADR — пошаговый план ^[7]

• 7. Как измерить эффективность ADR ^[8]

• 8. Метод «Заземление» как полезная практика для работы ADR ^[9]

• 9. ADR за пределами ИТ архитектуры и ИТ в целом ^[10]

• Выводы, чеклист и прочее разное ^[11]

• Список литературы ^[12]

Введение. Зачем нам ADR или Амнезия она такая

Что такое потеря контекста?

Что же такое потеря контекста? Термины же важны, и не важны одновременно.

Можно взять какое‑нибудь псевдо‑академическое определение — утрата информации о причинах принятия технического решения в результате смены состава команды, с течением времени или из за отсутствия документации.

А можно вспомнить какой‑нибудь случай, когда к вам приходит новый разработчик и говорит:
«А почему у нас нет индексов для этой таблицы?»
«А почему мы используем SOAP, а не REST API»
“А почему у нас тут X, а не Y?”
«А кто это решил и когда? А можно переделать?»

Все эти формулировки в свободной форме сводятся к одной проблеме: команда через относительно небольшое время (от 3 — до 12 месяцев ) не помнит, почему было сделано именно так.
Ну не помнит и ладно, что тут такого. Кто из нас без греха?

Проблема в том, что подобная амнезия дорого обходится.
Начинаются:

• Повторные обсуждения уже принятых решений. Длительные обсуждения с привлечением широкого круга заинтересованных лиц, которые в итоге заканчиваются словами «а, ну понятно, так и нужно было сделать».

• Ошибочный рефакторинг существующего кода. Потому что не поняли, почему было сделано именно так, и решили переделать как лучше. А получилось, как получилось.

• Длительное подключение новых разработчиков. Поиск «гуру» и археологические раскопки в коде и email.

• Конфликты между командами из‑за разного понимания ситуации «моделей мира».

Согласен, в большинстве случаев подробное документирование решений не имеет значения.
У нас есть agile, scrum, задачи в (не)любимом менеджере задач jiraкайдзен и прочее разное. А все это лишняя бюрократия, бумагомарательство, и вообще у нас у всех отличная память ^[13].

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

Итого, АDR это про память и документацию?

Конечно да, и конечно нет. ADR это не только и столько про документацию, а скорее про про принятие важных (архитектурных) решений. Как правильно их принимать, на что обращать внимание ^[14], какие вопросы себе задавать, какие ошибки ^[15] можно совершить, это все тоже про ADR.

В литературе упоминаются три «основных архитектурных антипаттерна» (неправильных подходов к принятию архитектурных решений), для работы с которыми помогает ADR.

Если совсем кратно, то можно описать их так:
Covering Your Assets (излишняя перестраховка)
Архитектор избегает или откладывает решение из‑за страха ошибиться.
Как ADR помогает:
 — Фиксация «момента принятия решения» в статусе: RFCСбор ОС: до 2025-06-01
 — Явное документирование допущений: «Решение принимается при условии, что нагрузка не превысит 10k RPS(запросов в секунду)»
 — Возможность пересмотра: статус УстарелоDeprecated позволяет легитимно изменить решение при изменении контекста
Правило: По возможности откладывайте принятие решения, до появления более полной информации, но не впадайте в паралич анализа.
Groundhog Day (день сурка)
Люди не понимают причин решения и обсуждают его снова и снова.
Как ADR помогает:
 — Раздел КонтекстContext + РешениеDecision явно документирует бизнес‑аргументы (стоимость, time‑to‑market (TTM), удовлетворённость пользователей) и логику ^[16] принятия решения
 — Ссылка на ADR в обсуждениях: «См. ADR-017, раздел „Альтернативы“’»
Правило: Технические аргументы важны, но бизнес‑обоснование – критично. Если решение бесполезно для бизнеса, это не лучшее архитектурное решение.
Email‑Driven Architecture (архитектура, управляемая письмами)
Люди не знают о решении, забывают ^[17] его или не понимают, как реализовать.
Как ADR помогает:
 — Единая система записи: «См. ADR-023 по ссылке» вместо описания решения в теле письма
 — Таргетированныеперсональные уведомления: «Привет, Саша, это решение касается твоей работы — ознакомься по ссылке»
Правило: Используйте уведомления в стиле: «Привет, [Имя], я принял решение по [суть], непосредственно касающееся твоей работы. Пожалуйста, ознакомься по ссылке: [ADR‑XXX]»

Если на этом моменте вы «подвисли», рекомендую прочитать статью до конца, а потом вернуться к этому пункту.
Подробнее можно ознакомится с вопросом, например в книге Ричардс М, Форд Н, «Фундаментальный подход к программной архитектуре: паттерны, свойства, проверенные методы» приведенной в разделе Список литературы ^[12]

1. Что такое ADR?

ADR (Architectural Decision Record) — это структурированный, лаконичный документ (обычно 1–2 страницы), фиксирующий одно архитектурное решение вместе с контекстом, рассмотренными альтернативами и обоснованием выбора.

Т.е. ADR — это не просто запись «что решили», а документ, отвечающий на четыре ключевых вопроса:

1. Контекст: Какие бизнес‑требования, ограничения или проблемы привели к необходимости решения?

2. Решение: Чёткая формулировка выбранного подхода в активной, утвердительной форме.

3. Альтернативы: Какие варианты рассматривались и почему были отклонены? Подсказка: если альтернативы не рассматривались вообще, то решение изначально неверное.

4. Последствия: Положительные и отрицательные эффекты (технический долг, зависимости, риски).

Архитектурно значимые решения или Границы применимости

Что будем описыватьфиксировать? Конечно только самое важно, зачем размениваться на мелочи.
А как вы уже догадались, самые важные решения — это архитектурно значимые:)

К архитектурно значимым относятся решения, влияющие на:

• Структуру системы (паттерны, стили, границы сервисов)

• АрхитектурныеНефункциональные свойства (производительность, безопасность, масштабируемость и прочие ‑ость)

• Зависимости между компонентами иили командами

• Интерфейсы (контракты, версии)

• Технологические методыпрактики с долгосрочными последствиями (фреймворки, платформы)

Примерный список такой годноты приведен, но он как всегда не полон. Поэтому, всегда можно использовать подсказку.
Пишите ADR, если принимаемое решение:

• повлияет на работу более одной команды

• ошибка будет стоить больше 40 часов доработок

• иили оно будет актуально более 3 месяцев

• сложно объяснить новичку без понимания контекста

Пишите, бумага все стерпит (C "мой препод высшей математики")

2. Анатомия ADR — основные разделы

Базовая структура ADR состоит из 7 главныхосновных разделов и нескольких опциональных:

• Название (Title)

• Статус (Status)

• Контекст (Context)

• Проблема (Problem)

• Альтернативы (Alternatives)

• Решение (Decision)

• Последствия (Consequences)

  И двух опциональных:

• Контроль (Compliance)

• Примечания Метаданные (Notes)

Базовая структура может быть расширена за счёт любого другого раздела, при условии сохранения последовательности и лаконичности документа.
Порезать в меньшую сторону конечно тоже можно. Например можно объединить разделы (контекст, проблема, альтернативы). По классике основных разделов как раз 5. При этом, уменьшить количество разделов можно, но не стоит. Более эффективно (к.м.к.) явно выделять разделы «Контекст», «Проблема», «Альтернативы», в отдельные пункты, чтобы дополнительно обратить внимание на их важность (прямо чтобы глаза резало, почему в них пусто).

Шаблон для записи ADR

# ADR-00X: <Краткое наименование ..>

## Статус
<ЧерновикСбор ОС: до YYYY-MM-DПредложеноПринятоРеализованоУстарелоЗамененоАрхивировано>

## Контекст
< Развернутое описание ситуации, в которой нужно принять решениерешать проблему.
Укажите: инициатора(кто поднял вопрос, его роль, интересы).
Обстоятельства, предпосылкиумолчания, ограничения, архитектурные требования, 
текущее состояние системы. 
Ответьте на вопрос: "Почему это решение рассматривается именно сейчас?" 
"Что заставило меня принять это решение?" >

## Проблема
< Опишите бизнес иили техническую проблему.   
Проблема - по возможности сформулированная как противоречие проблема, 
которую необходимо решить.  
Например, "если выключится произвольный один блоксервер, то система должна продолжать работать".>

## Альтернативы
<Рассмотренные альтернативные варианты и причины их отклонения. 
Рекомендуется рассматривать не менее 3 варинатов. 
**Решение** принятое **без рассмотрения альтернатив - ошибочное** по умолчанию.

Формат
- Вариант 1: название, краткое описание, плюсы, минусы, причина отклонения 
(стоимостьсложностьрискипроизводительностьпрочее)
- Вариант 2: название, краткое описание, плюсы, минусы, причина отклонения 
(стоимостьсложностьрискипроизводительностьпрочее)
- Вариант 3: название, краткое описание, плюсы, минусы, причина отклонения
- (стоимостьсложностьрискипроизводительностьпрочее)

## РешениеЧто делаем
<Чёткая формулировка в активной форме + обоснование "почему"

**Выбран Вариант**: X
Чёткая формулировка принятого решения, без двусмысленностей.
Укажите обоснование - Почему было принято это решение 
(на основе метрик, результатов PoCProof of Concept, требований безопасности или экспертного мнения).

Если решение компромиссное, явно зафиксируйте чем жертвуем.

Формат
Четкие шаги реализации:  
1. Шаг 1 с деталями  
2. Шаг 2 с зависимостями  
3. Шаг 3 с проверками  
Указать используемыетребуемые ресурсытехнологииинструменты >

## Последствия
<Как позитивные, так и негативные последствия решения, рискиограничения, метрики влияния

**Положительные**
Укажите положительные последствия вашего решения: что получим хорошего, 
как повлияет на ситуацию, бизнес-ценность
Что улучшится в системепроцессе? Ожидаемые изменения в метриках: задержки, стоимость,
прочее?

**Отрицательные и риски**
Укажите отрицательные последствия вашего решения: 
что потеряем, как отрицательно повлияет на ситуацию, в чем заключается компромиссцена 
принятого решения. 

Возможные риски (типовая матрица рисков, и специфические для этой ситуации).
Технический долг, затраты на поддержку, зависимость от поставщика, прочее?
Минимизация рисков:
Опишите план действий, конкретные шаги по минимизации рисков
>

## Результат
<Конкретный ожидаемый рабочий продукт: что получим, метрики успеха, 
как измерим, бизнес-ценность >

## Контроль (Compliance) [опционально]
<Ответственный, Сроки, Как проверять соблюдение>

## Примечания  Метаданные [опционально]
<Автор, дата, утверждающий, ссылки>

Давайте разберём каждый раздел подробнее.

Название

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

• Последовательная нумерация (ADR-001, ADR-002…)

• Краткая, информативная фраза: «Выбор протокола межсервисной коммуникации для ядра платформы»

• Избегать двусмысленности: не «Кэширование», а «Выбор Redis vs. Memcached для сессий пользователей»

Статусы

Хорошо «смазанная» и устойчиво работающая «машина состояний» упорядочивает процесс с организационной точки зрения ^[18], и позволяет «продвигать» ADR по всему конвейеружизненному циклу с минимумом усилий и накладок.

Итак, список статусов и последовательность их изменений:
[DraftЧерновик] → [RFCСбор ОС: до YYYY‑MM‑DD] → [ProposedПредложено] → [AcceptedПринято] → [ImplementedРеализовано] → [DeprecatedУстарело] → [Superseded byзаменено на ADR‑XXX] → [ArchivedАрхивировано]

Важно: Статус Superseded byЗаменено на всегда требует явной ссылки на заменяющий ADR. Это позволяет сохранить историю и отследить эволюцию ^[19] решения.

Контекст

Отвечает на вопрос: «Что именно заставило нас принять это решение?»
Необходимо сделать описание ситуации (достаточное), в которой нужно принять решениерешать проблему.

Что включать:

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

• Важно включать в явном видеописывать предпосылкиумолчания «которые все знают», так как часто оказывается, что знание в головах (контекст) у людей сильно отличается, и без его явного указания прийти к общему решениюучесть все интересы невозможно.

• Технические ограниченияархитектурные требования: «Текущее решение не масштабируется >10k RPS».

• Внешние факторы: «Поставщик X прекращает поддержку версии Y в Q3 2027»

Контекст — это также способ документировать архитектуру: описывая проблему, вы неявно описываете систему.

Проблема

Опишите бизнес или техническую проблему.

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

«Неправильно определили проблему → бесполезно потратили доступные ресурсы на выполнение непонятно чего, непонятно зачем → получили негативную обратную связь от инициатора → ушли на следующую итерацию». Классика, которой стоит всеми силами избегать.

По формату, проблему и ограничения желательно формулировать как противоречие, которое необходимо решить.

Принцип противоречия важен, потому что любая реальная проблема существует в системе с ограниченными ресурсами (время, бюджет, вычислительные мощности, профессионализм команды), а четко описанное противоречие выявляет скрытые допущения.

Если формулировка проблемы не содержит противоречия — значит, вы либо:

• Не докопались до реальных ограничений (поверхностная формулировка)

• Работаете в идеализированном мире (не заземлились)

Можно использовать следующий алгоритм:

1. Назови объект внимания Прежде чем формулировать проблему, ответь: о чем именно речь? Это сбой в API? Это недовольство клиентов? Это долгая доставка фичиобновлений? Плохо: «У нас проблемы с производительностью».
   Хорошо: «Объект внимания: Время ответа API метода /checkout в часы макс. нагрузки».

2. Отдели жалобу от проблемы Жалоба — это «всё плохо. ничего не работает. мы все умрем». Проблема — это конкретный разрывgap между тем, что есть и тем, что должно быть, который мы можем закрыть своей работой.
   Например:
   Ситуация (Аномалия): Нагрузка растет, SLA нарушается.
   Проблема: Текущая архитектура не позволяет масштабироваться в пределах утвержденного бюджета.

3. Сформулируй описание в виде противоречия
   Для формулировки цели в виде противоречия можно использовать метод «Если, То, Но». Это будет не только сама проблема, но и границы, в которых мы будем искать решение. ЕСЛИ [условиетриггер],
   ТО [желаемое поведениекритерий закрытия проблемы],
   НО [ограничениежертваресурс которым мы платим].

Пример:

**Объект внимания**: Метод /checkout API и метрика P95(95-й процентиль) латентностизадержек.

**ЕСЛИ** нагрузка на API (RPS) вырастает в 10x за 5 минут
 (временное окно срабатывания триггера),
**ТО** P95 латентности метода /checkout остается < 200мс  в течение 
всего периода пиковой нагрузки (временное окно проверкикритерий),
**НО** мы принимаем рост стоимости инфраструктуры до 30% в пики 
и холодный старт новых инстансов до 45 секунд 
(в этот момент допускается локальное нарушение SLA до 500мс).

Альтернативы

Рассмотренные альтернативные варианты и причины их отклонения.
Рекомендуется рассматривать не менее 3 вариантов. Решение принятое без рассмотрения альтернатив — ошибочное по умолчанию.

Формат

• Вариант 1: название, краткое описание, плюсы, минусы, причина отклонения (стоимостьсложностьрискипроизводительностьпрочее)

• Вариант 2: название, краткое описание, плюсы, минусы, причина отклонения (стоимостьсложностьрискипроизводительностьпрочее)

• Вариант 3: название, краткое описание, плюсы, минусы, причина отклонения (стоимостьсложностьрискипроизводительностьпрочее)

Решение

Самый важный раздел. Формулируйте решение в активной, утвердительной форме:

Правильно: «Мы будем использовать асинхронный обмен сообщениями через Apache Kafka для интеграции сервисов заказов и доставки»
Не правильно!: «Возможно, стоит рассмотреть Kafka, но нужно ещё подумать»

При принятии решения учитывайте наличие доступных ресурсов. Нет смысла принимать решения, которые вы не сможете реализовать в реальном мире.

Фокус на «почему», а не «как»:

• Понимание причины принятия решения важнее, чем понимание, как именно что‑то работает

• Диаграммы и код покажут «как это работает», ADR должен объяснить «почему приняли такое решение»

• Это защищает от ошибочного рефакторинга: зная причину, команда не заменит решение на «похожее, но не то»

Последствия

Каждое решение имеет цену. Всегда лучше подумать о последствиях заранее. Поэтом, документируйте и плюсы, и минусы

Положительные последствия

• Снижение связности между сервисами заказов и доставки

• Возможность независимого масштабирования нагрузки

• Улучшение отказоустойчивости: буферизация при пиках нагрузки

Отрицательные последствия Компромиссы Риски

• Усложнение отладки: асинхронный поток труднее трассировать

• Необходимость внедрения системы мониторинга

• Дополнительная инфраструктура: кластер Kafka, мониторинг, бэкапы

Анализ компромиссов заставляет архитектора задуматься: не перевесит ли отрицательный эффект пользу?

Контроль (Compliance)

Как вы будете проверять, что решение соблюдается?

• Метрика в Prometheus: kafka_consumer_lag_seconds с предупреждением при превышении >30s

• Автоматизированный тест в CI: проверка, что все сервисы используют утверждённый клиент

• Ежеквартальный аудит: проверка, что новые интеграции соответствуют шаблону

Метаданные

Даже при хранении ADR с использованием системы контроля версий ( например в Git ) дополнительные метаданные полезны:

author: "Иван Петров"
created: "2025-05-15"
decided_by: "Архитектурный комитет"
decided_date: "2025-05-20"
superseded_by: "ADR-042"  # если применимо
last_updated: "2025-11-03"
updated_by: "Мария Сидорова"
tags: ["messaging", "kafka", "integration"]

Пример: ADR-001

# ADR-001: Выбор стратегии кэширования для сервиса заказов
**Статус**: Принято (2025-03-12)  
**Автор**: Анонимизировано  
**Утверждено**: Архитектурный комитет

## Контекст
Инициатор: Василий Васильевич из отдела Продаж. 
Не устраивает скорость работы инет магазина в момент оформления заказа. 
Вечером с 18:00 до 19:17 пользователи массово жалуются на трудности с оформлением заказа.
Сервис заказов обрабатывает ~5000 RPS в пике. 
Текущее решение - прямые запросы к основной БД - приводит к:
- задержка >800ms при пиковой нагрузке
- Риску каскадных отказов при деградации БД
- Невозможности масштабирования без вертикального апгрейда

Рассмотренные альтернативы:
1. Оптимизация запросов БД + индексы 
(отклонено: не даёт нужного прироста)
2. In-memory кэш 
(отклонено: не масштабируется между инстансами)
3. Redis-кластер (выбран)
4. Memcached-кластер 
(отклонено: отсутствие нативной поддержки TTL на уровне ключа в нашей версии)

## Решение
Мы внедрим двухуровневое кэширование:
1. L1: in-memory кэш на 30 секунд для "горячих" данных (идентификаторы, статусы)
2. L2: Redis-кластер (3 ноды, репликация) для агрегированных данных на 5 минут
Использовать паттерн Cache-Aside с явной инвалидацией.

## Последствия
### Положительные
- Ожидаемое снижение задержки до <200ms в 95-м перцентиле
- Возможность горизонтального масштабирования сервиса
- Снижение нагрузки на основную БД на ~40%
### Отрицательные  Компромиссы
- Усложнение архитектуры: необходимость управления инвалидацией кэша
- Риск рассинхронизации: кэш может отдавать устаревшие данные до 5 минут
- Дополнительные операционные расходы: мониторинг кластера, бэкапы, тесты

## Контроль
- Метрика `cache_hit_ratio` >85% в продакшене
- Автоматический тест: при изменении схемы данных все ключи с префиксом `order_v*` инвалидируются
- Ежеквартальный аудит: проверка, что новые эндпоинты используют утверждённую стратегию

## Метаданные
tags: ["caching", "redis", "performance", "orders-service"]

3. Роли в процессе работы с ADR

Важно понимать: роли — это не должности. Роль — это про вашу точку зрения, интересы и то, что вы делаете, а не как формально называетесь в контрактетрудовом договоре.

Базовые критерии утверждения архитектурного решения:

• Стоимость: если превышает установленный порог — требуется одобрение более высокого уровня

• Влияние на другие команды: требует согласования затронутых сторон

• Последствия для безопасности: обязательное участие команды ИБ

Необходимо установить критерии и ограничения до того, как начнёте писать ADR. Это избавит от споров «кто имел право утверждать решение».

4. Кто и зачем использует ADR?

Типичные сценарии применения:

• Выбор между монолитом и микросервисами для нового продукта

• Определение стратегии хранения данных (SQLNoSQL, шардированиеsharding)

• Выбор протоколов коммуникации (RESTgRPCGraphQL)

• Решения по безопасности: аутентификация, авторизация, шифрование

• Инфраструктурные решения: облако, on‑premise, hybrid

5. Достоинства, ограничения и антипаттерны

Что хорошего?

Что плохого? Антипаттерны

Разрешение конфликтов

Проблема: В распределённых командах новые ADR могут тихо отменять старые без явного указания, создавая противоречия в репозитории и головах команды.

Решение:

Правило «Только явное переопределение» Любой ADR, затрагивающий контекст уже принятого решения, обязан:

• Содержать ссылку на пересматриваемый ADR в разделе Context

• Установить статус ПредложеноProposed до завершения сбора ОС

• После утверждения: старый ADR получает статус УстарелоSuperseded by ADR-XXX, новый — ПринятоAccepted

Приоритезация при конфликтах:

Подобный подход предотвращает «тихую отмену» и сохраняет воспроизводимость решений для аудита.

6. Как внедрить ADR — пошаговый план

Шаг 1: Подготовка

• Выберите пилотную команду (1 продукт, 1 домен)

• Утвердите минимальный шаблон (5–7 разделов + метаданные)

• Определите роли: AuthorАвтор, ReviewersРецензенты, DeciderПринимающий решение, MaintainerАдминистратор

• Создайте репозиторийпапку для ADR с примером (docsadr000-template.md ^[21])

• Установите критерии утверждения (стоимость, влияние, безопасность)

Шаг 2: Запуск

• Напишите первые 3-4 ADR на реальных, недавних решениях (ретроспективно)

• Проведите проверку с фокусом на полноту контекста и явное описание последствий

• Настройте автоматическую базовую валидацию: проверка наличия обязательных разделов

Шаг 3: Интеграция и метрики

• Добавьте правило: «Крупный архитектурный PRизменение должен ссылаться на ADR»

• Начните собирать 2–3 простые метрики (покрытие, связность, актуальность)

• Проведите ретроспективу: что работает, что мешает, что улучшить

Краткий вид рабочего процесса

1. Автор создаёт ADR со статусом Запрос ОСRFC: до YYYY-MM-DD

2. Рассылает уведомление заинтересованным сторонам (только тем, чья работа затрагивается)

3. После дедлайна анализирует обратную связь, вносит правки, меняет статус на ПредложеноProposed

4. Принимающий решениеDecider утверждает → статус ПринятоAccepted, уведомление о готовности к реализации

Чек‑лист «Стоит ли писать ADR?»

• Решение повлияет на работу >1 команды?

• Ошибка в выборе будет стоить >40 часов переделки?

• Решение будет актуально >3 месяцев?

• Есть регуляторныеаудиторские требования к фиксации решений?

• Решение сложно объяснить новичку без знания контекста? Если ответили «Да» на 3 и более вопроса, то пишите ADR.

Как преодолеть сопротивление внедрению

• Культура без поиска виновныхBlameless Culture
  Решения всегда принимаются в условиях недостатка информациинеопределенности. ADR фиксирует решение в контексте того времени, когда оно принималось.
  Если через год решение выглядит ошибочным, это не провал автора, а изменение условий. Статус УстарелоDeprecated — это нормально.

• Психологическая безопасность
  Разрешите статус RFC с явным сроком получения ОС. Это снижает страх ^[22] «ошибиться навсегда» и спасает от «паралича анализа».

• Ротация рецензентов
  Не давайте одному человеку монополию на утверждение. Это распределяет знания и снижает «фактор автобусаbus factor», зависимость проекта от одного человека.

• Признание ценности
  Включайте качество ADR в ретроспективы (не количество, а полезность).

7. Как измерить эффективность ADR

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

При этом важно помнить, что с любыми оценками есть как минимум две проблемы:

• показатель необходимо корректно измерить не потратив на это много ресурсов

• если люди начинают фиксировать внимание на КПЭKPI, то со временем показатели подменяют цели которых стремились достичь, и неизбежно «взламываются» со стороны оцениваемых. Поэтому, смотрим в эту сторону, но не делаем из КПЭKPI фетиш.

Категория 1: Процессные метрики

Процессные метрики показывают, что процесс идёт, но не что он хорошо работает.

Категория 2: Качественные метрики

Категория 3: Экономические метрики

Формула условного ROI ADR:

ROI_ADR = ( ( Сэкономленное_время − Затраты_на_ведение) / Затраты_на_ведение ) × 100%

Совет: Начинайте с 1–2 простых метрик. Сложные метрики и финансовые модели вводите только если вам это действительно нужно.

8. Метод «Заземление» как полезная практика для работы ADR

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

Для этого используют подход, который называется «заземление».

Алгоритм заземления (6 шагов):

1. Обеспечьте безопасность общения: признавать реальность должно быть безопасно. Проверьте, что люди высказывают сомнения вслух, не уклоняются от беседы. Но при этом не стоит превращать обсуждения в «нытинги», придерживайтесь повестки.

2. Опишите, что должно измениться в физическом мире: явно пропишите, с точки зрения какой роли вы смотрите на ситуацию. Что именно изменится?

3. Выделите агентов и артефакты: какие агентыкомпонентымодули начали действовать иначе? Какие объекты сменили состояние? Опишите последствия.

4. Определите метод проверки: какими замерами вы подтвердите, что изменения реальны? Что будете измерять?

5. Условия успехапровала: при каких условиях результат возможен? При каких — невозможен?

6. Ранние сигналы: какие индикаторы заранее укажут, что делается что‑то не то? до того, как вы сделаете фатальную ошибку.

Как заземление связано с ADR?
Напрямую. Раздел КонтекстContext в ADR — это точка, где вы применяете шаги 2–3. Раздел КонтрольCompliance — это шаг 4 (метод проверки). А Последствия — это шаг 5–6 (условия и сигналы).

Заземление превращает абстрактное «улучшим производительность» в конкретное: «снизим задержку при обработке заказов с 800ms до <200ms при нагрузке 5k RPS, измеряем через Prometheus‑метрику order_service_latency_seconds».

Попробуйте применить заземление при написании следующего ADR. Результат заметно отличается от «стандартного» варианта.

9. ADR за пределами ИТ архитектуры и ИТ в целом

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

В качестве примера можно рассмотреть сходства ADR и PDR.
ADR и PDR (Product Decision Record) решают одну задачу — фиксацию решений, но в разных доменах: ADR для инженерныхархитектурных решений, PDR с точки зрения бизнес‑ценности и пользовательских сценариев.

Точки пересечения и риски

• Зависимость: продуктовые решения (PDR) часто генерируют технические последствия (ADR). Пример: PDR “Добавить offline‑режим” → ADR «Выбрать локальную БД и стратегию синхронизации».

• Риск рассинхронизации: изолированное ведение приводит к «архитектуре ради архитектуры» или «фичам без инженерного фундамента».

• Правило связывания: каждый PDR со значительным Technical ImpactТехническим воздействием обязан содержать ссылку на порождённый ADR. Обратная ссылка в ADR — обязательна.

Пример: PDR-012

# PDR-012: Изменение модели монетизации для сегмента B2B
**Статус**: Принято (2035-04-10)  
**Автор**: Product Team Yohoho  
**Утверждено**: Product Leader

## Контекст
Сегмент B2B показывает низкую конверсию перехода с триальной на платную версии 
(8% vs. целевые 15%). 
Гипотеза: текущая фиксированная цена не учитывает разный масштаб клиентов.

Рассмотренные альтернативы:
1. Снижение базовой цены 
(отклонено: риск канибаллизации)
2. Введение градации по количеству пользователей 
(выбрано)
3. Переход на оплату за фактическое использованиеusage-based pricing
   (отклонено: сложность прогнозирования)

## Решение
Мы внедрим 3 уровня подписки для B2B:
- Starter: до 10 пользователей, $99мес
- Growth: 11–50 пользователей, $299мес  
- Enterprise: 50+, индивидуальное ценообразование
Переход для существующих клиентов - опциональный, 
с сохранением прехних условий на 12 месяцев.

## Последствия
### Положительные
- Ожидаемый рост конверсии в платные подписки до 14–16%
- Увеличение ARPU(Average Revenue Per User)средний доход с клиента,
 за счёт Upsellпродажи более дорогих версий подписики
### Отрицательные  Компромиссы
- Усложнение биллингасистемы расчетов и поддержки
- Необходимость обновления маркетинговых материалов

## Контроль
- Метрика: конверсия перехода trial -> paid (цель: +6 п.п. за 2 месяца)
- Проверка через 90 дней: принимаем решение о масштабировании (gono go)

## Метаданные
tags: ["pricing", "b2b", "monetization"]
related_adr: "ADR-045"  # техническая реализация биллинга

Адаптация для других доменов

Возможна ли адаптация подхода для менее близких к ИТ доменов? На мой взгляд, однозначно Да.
Что можно посоветовать в этом случае?

Принцип адаптации:

1. Сохраните ядро: контекст→проблема →альтернативы→ решение → последствия → контроль

2. Замените лексику на доменную (например: не «сервис», а «процесс»)

3. Добавьте поля специфичные для конкретного доменапрофессиональной области

Не копируйте IT‑термины буквально. Цель — передать логику принятия решений, а не навязать доменныйтехническийit‑шный жаргон.

Когда не применять ADR

Итак, ADR это «серебряная пуля», решит все ваши проблемы, и «вот это вот все». Конечно нет.
Как и у всякого метода, у описания архитектурных решений есть своя область применимости и явные ограничения. Попробуем сформулировать основные.

Когда нужно сказать Нет:

• Высоко-динамичные среды
  Пример: Стартап на этапе pre‑product‑market fit(на стадии поиска продукта), где решения меняются еженедельно. Нет смысла фиксировать решения которые завтра поменяются. Само по себе мышление письмом во время стратегирования несомненно принесет вам пользу, но желательно выбрать для этого другую формуметод.

• Однозначные, обратимые решения
  Пример: Выбор цвета кнопки, если он не влияет на конверсию. Мы помним, что фиксируются важные решения. Процесс не бесплатен. В жизни мы каждый день принимаем кучу решений на автоматес минимальными размышлениями, и это отлично. Поэтому, четко разделяйте, когда вам нужен экскаватор, а когда достаточно лопаты.

• Конфиденциальные решения
  В случаях когда сам факт документирования решения создаёт лишние риски. Без комментариев. Ваши риски, ваш выбор.

Общее правило: Если стоимость фиксации решения, больше стоимости его возможной потери — не пишите ADR.

Выводы, чеклист и прочее разное

В конце хочу привести короткий планчеклист, который вы можете применять в своей работе.

Основные принципы работы с ADR:

• Одно решение — одна запись

• Контекст важнее выбора конкретной технологии. Объясните «почему», а не только «что делаем».

• Статус, это не формальность. Отлаженная «машина статусов», это важно.

• Ссылки, это клей. Привязывайте ADR к коду, задачам, метрикам.

• Пересмотр решений — это нормально. Статус УстарелоDeprecated — признак здоровой практики.

• Помните правило: Если стоимость фиксации решения, больше стоимости возможной потери — не пишите ADR.

Чек‑лист проверки качества записи:

• Контекст описывает проблемы, а не решение

• Указан инициаторролиинтересы в контексте конкретной проблемы

• Решение сформулировано в активной форме («Мы будем…», а не «Стоит рассмотреть…»)

• Рассмотрены ≥3 альтернативы с явными причинами отклонения

• Последствия включают и плюсы, и минусы

• Статус соответствует реальному состоянию

• Есть ссылки на реализацию (если статус РеализованоImplemented)

• Есть рецензенты из затронутых доменов

Когда можно масштабировать процесс:

• Команда самостоятельно инициирует создание ADR

• Новые разработчики ссылаются на ADR во время адаптации «онбординга»

• Повторные обсуждения принятых решений сократились на ≥30%

Признаки для остановкипересмотра процесса:

• Пишут ADR “для галочки”, без реального анализа.

• Получение обратной связи занимает больше 3 дней без явных причин

• Ни один ADR не был пересмотрен за 6 месяцев (признак «ритуализации» практики)

Не смотря на достаточно большой размер статьи, описание получилось схематичным, и многие моменты были сознательно пропущены, или серьезно сокращены. Поэтому, если тема заинтересовала, посмотрите соответствующие ссылки из Список литературы ^[12]

Для меня ADR это не только про документацию технических решений, или выстраивание процессов в команде, это в первую очередь про шаблон для эффективного мышления.
Попробуйте рассмотреть процесс описания принятого решения как своеобразный чек‑лист, который позволит вам оценить проблему с разных сторон, учесть большинство интересов и будет усиливать вас лично. Сделает вас умнее.
Звучит как преувеличение. По классике жанра, в этом месте должна быть реклама какого‑нибудь варианта «волшебной таблетки» из довольно известного фильма «Области тьмы ^[23]». В этот раз обойдемся:)
Просто скажу: готов порекомендовать писать ADR всем, кому нужно подумать и взвешенно принять важное решение. Независимо от того, решаются рабочие или ваши личные проблемы.
Попробуйте, вполне возможно вам тоже понравится.

Список литературы

1. Michael Keeling, “Design It! From Programmer to Software Architect”, Chapter 16 Activity 20. Architecture Decision Records

2. Ричардс М, Форд Н, «Фундаментальный подход к программной архитектуре: паттерны, свойства, проверенные методы», Глава 19 — Архитектурные решения

3. Что может помешать видеть реальность ^[24]

4. Richards J. Heuer Jr. Randolph H. Pherson “Structured Analytic Techniques for Intelligence Analysis” ^[25]

5. Joel Parker Henderson: Architecture Decision Record ^[26]