Architecture Decision Records

Почему архитектурные решения исчезают

Заходишь в новый проект, открываешь репозиторий — сервис авторизации на Go, хотя остальной стек на Java. Очереди на RabbitMQ, хотя в компании корпоративный стандарт — Kafka. Один микросервис ходит к другому через gRPC, остальные — через REST. Спрашиваешь у коллег «почему так», и в ответ либо «исторически сложилось», либо «Серёга знал, но уволился в прошлом году».

Решения, скорее всего, были адекватные для своего момента. Беда в том, что момент испарился. Альтернативы, ограничения, осознанные компромиссы и случайные побочные эффекты — всё это нигде не зафиксировано. Дальше каждый новый разработчик выбирает между двумя стратегиями: либо боится трогать («вдруг там какая-то причина»), либо переделывает по живому и наступает на грабли, от которых однажды уже отскочили.

Формат Nygard

В ноябре 2011 года Майкл Найгард, автор книги Release It!, опубликовал заметку «Documenting Architecture Decisions» — короткую, страницы на две. Формат, который он там описал, постепенно стал стандартом де-факто. Идея простая до предела: каждое значимое архитектурное решение живёт в отдельном текстовом файле с четырьмя секциями.

Title — короткая именная фраза вида «ADR-0005: Использование PostgreSQL вместо MongoDB для сервиса заказов».

Status — proposed, accepted, deprecated, superseded. Жизненный цикл решения: предложили, приняли, через два года заменили — и в старом ADR появляется ссылка на новый.

Context — что за ситуация была на момент принятия решения. Какие силы действовали: технические ограничения, требования бизнеса, сроки, экспертиза команды, существующая инфраструктура. Самая ценная секция ADR, потому что контекст теряется первым.

Decision — что выбрали и почему. Не «выбрали PostgreSQL», а «выбрали PostgreSQL, потому что у команды уже есть DBA с экспертизой, данные реляционные, а MongoDB потребовал бы нового специалиста и переписывания слоя доступа».

Consequences — что из этого следует. Какие двери открылись, какие закрылись, что придётся доделать. «Следствие: данные из прототипа на MongoDB надо мигрировать, это займёт спринт. Получаем транзакции и joins, теряем гибкость схемы для быстрого прототипирования».

MADR и другие форматы

Оригинальный формат Найгарда сознательно минималистичен, и со временем у него появились расширения. Самое популярное — MADR (Markdown Any Decision Records). Там есть отдельная секция «Considered Options» с явным перечислением альтернатив и анализом trade-offs по каждой. MADR также предлагает фиксировать decision makers и статус подтверждения — пригождается там, где архитектурные решения проходят через формальное ревью.

В репозитории Joel Parker Henderson на GitHub собраны десятки шаблонов ADR — от ультра-минималистичных до развёрнутых, с секциями про бизнес-обоснование, метрики успеха и план отката. На практике лучше стартовать с формата Найгарда и наращивать секции по мере появления реальной потребности. Если стартовать с тяжёлого шаблона, команда быстро бросит ADR совсем.

Инструменты

adr-tools — набор bash-скриптов. adr new "Use PostgreSQL for orders" создаёт файл с правильным номером и шаблоном, adr list показывает все решения, adr link связывает ADR между собой. Маленькая утилита, которая делает одну вещь хорошо.

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

VS Code расширение для ADR — автокомплит по шаблону и превью. С поддержкой свежих версий MADR бывают пробелы.

Хотя по-хорошему ADR — это просто текстовые файлы, и никакой специальный инструмент для них не обязателен. Достаточно создать папку docs/adr/, положить туда 0001-record-architecture-decisions.md (первый ADR традиционно описывает, что в проекте начинают вести ADR), и начать. Формат имён NNNN-kebab-case-title.md — этого хватит.

Когда это реально работает

ThoughtWorks Technology Radar в ноябре 2017 года поместил Lightweight Architecture Decision Records в категорию Adopt — высшая ступень рекомендации со смыслом «по умолчанию использовать в проектах». UK Government Digital Service (GDS) включил ADR в свои стандарты разработки как обязательную практику. Red Hat советует ADR прежде всего распределённым командам, где устные договорённости теряются особенно быстро.

ADR начинают приносить пользу, когда сходятся три условия. Первое: они лежат в том же репозитории, что и код, по принципу docs-as-code — не в отдельной вики, не в корпоративном чате, не в общих документах. Второе: создание ADR встроено в процесс. Если архитектурное изменение проходит через RFC или design review, ADR фиксирует итог этого обсуждения автоматически. Третье: ADR иммутабельны. Когда решение меняется, старый файл не редактируется — заводится новый со статусом «supersedes ADR-0005» и ссылкой на предыдущий. Так сохраняется история мышления, а не только текущее состояние.

Частые ошибки

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

Слишком длинные ADR — вторая. Если документ занимает три страницы, читать его никто не станет. Формат Найгарда сознательно скроен под один экран; это часть дизайна, а не случайность.

Не обновлять статусы — третья. ADR-0003 принят два года назад, от того решения давно ушли, а статус всё ещё «accepted» — и получается ровно та лживая документация, против которой ADR и придумывались. В таких случаях создаётся новый ADR с новым решением, а старый помечается как superseded.