Документирование решений: как внедрить ADR в команде

Команда выбрала PostgreSQL вместо MongoDB, через полгода новый разработчик снова поднимает тот же спор, а автор решения уже не помнит исходные ограничения. ADR превращает такую потерю контекста в короткую запись в Git: что решили, почему, какие варианты отвергли и какой ценой. В этом разборе — практический процесс для Git 2.x и обычного Markdown, без привязки к конкретной CMS или трекеру задач.

ADR нужен не для протокола, а для повторного выбора

ADR, или Architecture Decision Record, — это отдельный документ об одном значимом архитектурном решении. Он отвечает на вопрос, который обычная техническая документация часто пропускает: почему система устроена именно так.

Документация API описывает текущее поведение. ADR объясняет путь к нему. Это разные задачи. Если в README написано «сервис использует очередь RabbitMQ», читатель узнает факт. Из ADR он может узнать, что команда сравнивала RabbitMQ и Kafka, ограничивалась одним кластером, не хотела вводить отдельную платформенную команду и сознательно отказалась от более сложного варианта.

Термин. Архитектурное решение — выбор, который заметно влияет на структуру системы, эксплуатацию, стоимость или возможность дальнейших изменений. Выбор имени переменной к нему не относится; выбор способа хранения персональных данных — относится.

Ценность ADR — не в том, что команда записала ответ. Ценность в том, что следующий человек увидит условия, при которых этот ответ был разумным.

Когда решение стоит оформить отдельной записью

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

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

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

Рабочий процесс: от спора до записи в Git

Внедрение ADR не требует отдельной платформы. Создайте каталог вроде docs/adr в том репозитории, где живёт код или архитектурная документация. Имена делайте последовательными: 0001-use-postgresql.md, 0002-add-outbox-pattern.md. Номер нужен для навигации, а не для определения важности.

1. Сформулируйте вопрос. Не «обсудить базы данных», а «где хранить заказы и их изменения после разделения монолита». Если вопрос нельзя прочитать без устного контекста, сузьте его.
2. Зафиксируйте ограничения. Запишите объём данных, требования к задержке, допустимый простой, компетенции команды, ограничения инфраструктуры и бюджет. Без этого решение выглядит универсальным, хотя оно было принято для конкретной ситуации.
3. Соберите альтернативы. Обычно достаточно двух-четырёх реалистичных вариантов. Включите текущий подход, если он существует. Не добавляйте технологию только ради длинного списка.
4. Сравните варианты по критериям. Для каждого укажите не только преимущество, но и цену: миграцию, поддержку, обучение, мониторинг, зависимость от поставщика или рост операционной нагрузки.
5. Проведите обсуждение с теми, кого затронет решение. Комментарии в pull request подходят для небольшого изменения. Для межкомандного выбора сначала проведите отдельное обсуждение, затем приложите его результат к ADR.
6. Примите решение и укажите последствия. Запись должна честно перечислять не только выигрыш, но и новые обязанности. После этого добавьте Markdown-файл в репозиторий через обычный pull request.
7. Свяжите ADR с кодом и задачами. Ссылка в README, тикете миграции или документации сервиса помогает найти запись. Не прячьте её только в истории чата.

Минимальный шаблон

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

• Заголовок: действие и объект, например «Использовать PostgreSQL для заказов».
• Статус: предложено, принято, заменено или отклонено. Набор статусов заранее согласуйте в команде.
• Контекст: проблема, ограничения и требования.
• Решение: конкретный выбранный вариант.
• Рассмотренные альтернативы: что отвергли и по какой причине.
• Последствия: плюсы, минусы, риски и новые эксплуатационные задачи.
• Связи: заменённые ADR, задачи, RFC и документация.

Чем ADR отличается от других документов

Самая частая ошибка — складывать в каталог ADR всё, что относится к архитектуре. У разных документов разные сроки жизни и владельцы.

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

Два подхода к ведению ADR и их цена

Один ADR на каждую важную тему

В этом подходе запись создаётся для каждого решения, которое прошло согласование. Он хорошо работает в команде с несколькими сервисами: историю легко искать по репозиторию, изменения проходят code review, а текст живёт рядом с системой.

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

Общий журнал решений

Все решения хранятся в одном файле или странице. Начать проще: не нужно выбирать имена, каталоги и шаблоны. Такой вариант подходит небольшой команде для короткого проекта.

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

Когда что выбирать

Если решений меньше нескольких десятков и проект короткий, общий журнал снизит порог входа. Если есть несколько сервисов, смена команды или длительный жизненный цикл продукта, выбирайте отдельные Markdown-файлы в Git. Платформа для документации нужна только тогда, когда без неё действительно теряется поиск, навигация или контроль доступа.

Что ломается на практике

• ADR пишут задним числом. Через месяц автор помнит уже не все ограничения и подменяет аргументы результатом. Исправление: создавать черновик в момент начала серьёзного обсуждения и обновлять его по мере выбора.
• В тексте нет отклонённых альтернатив. Через полгода кажется, что команда просто забыла очевидный вариант. Исправление: для каждого отвергнутого подхода написать одну конкретную причину.
• Статус не меняется. Документ с пометкой «принято» продолжает описывать уже заменённую архитектуру. Исправление: новый ADR должен явно ссылаться на старый, а старый — получать статус «заменено».
• Последствия заменены рекламным описанием. Фраза «решение улучшит масштабирование» ничего не говорит о цене. Исправление: перечислить, что придётся мониторить, оплачивать, обучать и поддерживать.
• ADR используют как разрешение не обсуждать решение. Запись не заменяет review. Исправление: сначала дать затронутым участникам возможность проверить контекст, затем принимать документ.

Не смешивайте в одной записи несколько независимых решений. Если выбор брокера привёл к отдельному решению о формате событий, создайте две связанные записи. Так проще понять, что именно можно пересмотреть без каскадного изменения всей архитектуры.

Как понять, что формат работает

Измеряйте не количество ADR. Оно легко превращается в KPI ради KPI. Проверьте три практических сигнала: новый участник находит причину спорного решения без автора; команда не открывает повторный спор по уже зафиксированному вопросу; при пересмотре архитектуры понятно, какие ограничения больше не действуют.

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

Что делать дальше

Выберите одно решение, которое команда чаще всего объясняет устно, и оформите его как ADR в текущем репозитории. Начните с пяти полей: статус, контекст, решение, альтернативы и последствия. Проведите запись через pull request, добавьте ссылку из документации сервиса и назначьте владельца проверки при крупных изменениях. После этого смотрите не на размер каталога, а на время, за которое новый участник может восстановить логику решения.