Architecture Decision Records

«Решили в чате полтора года назад, теперь никто не помнит почему» — типичный диалог в команде без ADR. Ещё через год приходит новый инженер, не видит причин терпеть странное решение и откатывает его, потому что контекста, в котором это решение принимали, нигде нет. ADR (Architecture Decision Record) — это знание, переносимое между поколениями команды: каждый значимый выбор метода или инструмента сопровождается записью context → decision → consequences, лежит в git и проходит ревью в PR. Главная практика внутри L1 Methods & Tools; соседи (Tech Radar, Tool Standardization, RFC process) — в открытых вопросах.

Что должен уметь

Главный навык на уровне L4 — формулировать context как проблему и ограничения, а не как пересказ выбранного решения. «Мы выбрали Prometheus, потому что Prometheus хорош» — context пуст, decision висит в воздухе. Хороший context описывает проблему («нужно хранилище метрик с алертингом»), ограничения («работает в Kubernetes, дешевле $X в месяц, хранит полгода, не привязано к управляемому сервису одного облака») и критерии, по которым варианты отсекаются. Решение выводится из context, а не подставляется в него задним числом.

Понимает, что такое ADR; читает существующие ADR команды и понимает context / decision / consequences.
Различает «решение, требующее ADR» (нетривиальный выбор инструмента, паттерна, дизайна) и «не требующее» (тривиальное, обратимое, локальное).

Пишет ADR для решения, в котором участвует: явный context, рассмотренные альтернативы, выбранный вариант с обоснованием, consequences (что приобретаем, что теряем).
Использует стандартный шаблон (Nygard или MADR) и единый формат хранения (docs/adr/NNNN-slug.md); держится сквозной нумерации и жизненного цикла (proposed → accepted → superseded → deprecated).

Ведёт обсуждение ADR в команде: формулирует context так, чтобы решение выводилось через разбор альтернатив.
Поддерживает ADR во времени: при изменении контекста создаёт новую ADR с явным Supersedes: ADR-0042; не редактирует существующую: неизменяемость и есть то, на чём держится доверие к истории.
Связывает ADR с кодом: ссылки из кода (// see ADR-0042) на критичные точки.

L6+

Внедряет практику ADR в команде или организации: шаблоны, обучение, индекс записей, встраивание в code review и onboarding.
Проектирует процесс принятия решений на уровне организации: где ADR внутри команды, где RFC между командами, где документ проектирования.

Материалы

Книги и руководства

Michael Nygard — Release It!, 2-е изд. (Pragmatic Bookshelf, 2018). Автор оригинальной концепции ADR (блог-пост 2011 года заложил формат); книга — фундамент дизайна, который выживает в production.

Статьи и фреймворки

Architectural Decision Records (adr.github.io). Канонический хаб ADR-практики. Принят в Microsoft Azure Well-Architected Framework и AWS Prescriptive Guidance.
joelparkerhenderson/architecture-decision-record. Коллекция шаблонов (Nygard / Tyree-Akerman / MADR / Arc42) и реальных примеров. По моим наблюдениям, это де-факто стартовая точка для большинства команд — больше шестнадцати тысяч звёзд говорят сами за себя.
ThoughtWorks Technology Radar. Открытая модель оценки инструментов (adopt / trial / assess / hold) — соседняя практика Tech Radar.

Инструменты

docs/adr/ в репозитории команды, обычные файлы markdown — самый простой формат. По моим наблюдениям, в зрелых командах именно так и хранят: один ADR — один файл (0042-use-prometheus-not-influxdb.md), ревью через PR, git как журнал аудита.
adr-tools / adr CLI — небольшая утилита командной строки для создания, связывания и индексирования ADR (adr new, adr supersede 42).
MADR (Markdown Any Decision Records) — облегчённый шаблон с context / decision / consequences плюс явные considered options. Подходит командам, которым шаблон Nygard кажется тяжёлым.

Best practices

Три вещи важнее остальных, и первая — качество context. Это проблема и ограничения, а не пересказ уже принятого решения задом наперёд. Когда context описан честно, decision из него почти выводится, и ревьюеру остаётся спорить с ограничениями, а не с вкусами автора.

Вторая — альтернативы. Их должно быть видно: минимум три с объяснением, почему отказались, причём «не делать ничего» — полноценный вариант, а не заглушка. Без альтернатив ADR неотличим от поста в блоге «почему я люблю X».

Третья — неизменяемость. Принятую ADR не редактируют; изменилось решение — заводится новая с явной ссылкой Supersedes: ADR-0042. Правка задним числом стирает историю, и через год уже не реконструировать, почему команда ушла с X на Y. А цепочка «решили — передумали — вот почему» сама по себе обучающий материал для новичка.

Consequences — обе стороны: что приобретаем и что теряем. Только плюсы — это не consequences, а реклама. У любого решения есть цена, и раздел, где её нет, всерьёз на ревью не принимают. Что закрылось (какие будущие решения теперь сложнее), что появилось (расходы на эксплуатацию, время на освоение, привязка к вендору), что осталось открытым. Я регулярно вижу записи с одними плюсами — обычно это значит, что автор решение не обсуждал, а защищал.

ADR пишется для значимых решений, не «для всего». Практика перестаёт работать ровно в момент инфляции: десятки записей про тривиальные выборы, их никто не читает, и серьёзная ADR тонет в шуме вместе с ними. Мои критерии простые. Решение нетривиально, его последствия живут год и дольше, из кода оно не выводится, и у него есть альтернативы, между которыми правда надо выбирать. Всё остальное укладывается в сообщение коммита.

ADR ревьюится в PR, как код, не как «информационное письмо». «Вот ADR, я её принял» — это частное мнение, а не «команда решила». Ревью в PR приносит разные точки зрения, вытаскивает альтернативы, которых автор не видел, и фиксирует согласие. Без ревью ADR остаётся документацией решения одного человека.

Связанные листья

Service Ownership — каталог сервиса ссылается на релевантные ADR.
Infrastructure as Code — выбор инструмента IaC (Terraform, OpenTofu, Pulumi, Crossplane) и структуры репозиториев — типичные предметы ADR.
Programming Languages — выбор языка для нового сервиса — ADR верхнего уровня, последствия которого живут дольше всего остального.
SLO Engineering — выбор целей SLO и формула составного SLO — решения с тяжёлыми последствиями, им место в ADR.
Dev Team Partnership — контракт взаимодействия частично перекрывается с форматом ADR.

Открытые вопросы

Внутри Methods & Tools рядом с этим листом висят три незакрытых соседа. Tech Radar (TBD) — регулярная, раз в несколько месяцев, оценка инструментов по категориям adopt / trial / assess / hold. Tool Standardization (TBD) — «один инструмент на задачу» в масштабе команды или организации; тема связана с ADR, но живёт своей жизнью. RFC process (TBD) — для решений, выходящих за пределы одной команды: общий API, общая платформа. Дисциплина та же, вес больше.

Отдельно стоит Technical Design Document — формат для глубокого проектирования сервиса до реализации. ADR отвечает на вопрос «что выбрали», TDD — на «как делаем», и путать их не стоит.