ADR для AI-агентов. Как сохранить причины архитектурных решений

В интернет-магазине есть обычная корзина и отдельный модуль для бронирования лимитированных товаров. Оба работают с товарами и заказами, поэтому часть логики дублируется.

Разработчик получает задачу доработать бронирование и передаёт её AI-агенту. Тот изучает репозиторий, замечает две похожие реализации и предлагает их объединить. Дублирования станет меньше, обработка ошибок будет общей, поддерживать код проще.

Но несколько месяцев назад команда уже рассматривала этот вариант и отказалась от него.

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

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

Агент об этом не знает. Он видит дублирование и предлагает рефакторинг, не учитывая причины первоначального решения.

Можно изучить историю Git, найти старую задачу или комментарии к pull request. Возможно, там сохранилось объяснение. А возможно, решение обсуждали на встрече и ничего не записали.

Зачем нужен ADR

Architecture Decision Record (ADR) представляет собой короткую запись о принятом архитектурном решении. Ещё в 2011 году Michael Nygard описал этот подход в статье Documenting Architecture Decisions.

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

# ADR-014: Отдельный модуль бронирования

Task: SHOP-284
Status: Accepted
Module: DropReservation

## Context
Обычная корзина не резервирует остатки.
Лимитированные товары требуют серверного
бронирования с ограничением по времени.

## Decision
Реализовать бронирование отдельно от Cart.

## Alternatives
Расширить существующую корзину.
Отказались из-за влияния на обычные
покупки и усложнения обработки бронирования.

## Consequences
Часть логики будет дублироваться.
Модули смогут развиваться независимо.

## Revisit
Пересмотреть при появлении общего
механизма резервирования.

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

Пересказывать задачу тоже не нужно. В ADR должно остаться то, что код ясно сказать не может, то есть почему выбрали именно это решение и почему отказались от альтернатив. Как раз это «почему» потом чаще всего и теряется.

С таким ADR разработчик или AI-агент сможет понять, почему два похожих модуля оставили раздельными. При необходимости решение можно пересмотреть с учётом первоначальных ограничений.

Что предлагает Matt Pocock

У Мэтта Покока есть skill domain-modeling, в котором предусмотрено создание ADR.

Skill предлагает создавать ADR, только если выполняются все три условия.

1. Его дорого или сложно изменить.
2. Будущему читателю без контекста будет непонятно, почему выбрали именно этот подход.
3. Были реальные альтернативы, между которыми пришлось выбирать.

Мне нравится, что Покок не предлагает документировать всё подряд. Более того, в ADR-FORMAT.md допускается ADR из одного абзаца. Если причину решения можно объяснить несколькими предложениями, нет смысла растягивать документ ради шаблона.

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

Иногда небольшая доработка приводит к решению, последствия которого проявятся намного позже. Например, при исправлении бага обнаруживается ограничение существующего модуля и приходится отказаться от общего механизма обработки ошибок. Сегодня причина очевидна, а через полгода такое отличие могут принять за ошибку.

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

Когда считать ADR окончательным

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

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

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

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

Создавать ADR с нуля по готовому коду хуже. AI может придумать убедительное объяснение архитектуры, хотя команда руководствовалась совсем другими причинами.

Поэтому ADR важно проверять самому, даже если агент собрал его по черновику. Он может пересказать задачу вместо причин или уверенно описать причину, которой не было. Неверное объяснение запутает сильнее, чем его отсутствие.

Финальный документ я бы сохранял вместе с задачей. Как минимум отдельным комментарием в Jira, Linear или другом таск-трекере.

Если агент не имеет доступа к таск-трекеру, ADR стоит дополнительно хранить в репозитории или обеспечить доступ через интеграцию. Иначе в следующей задаче он просто не найдёт нужную запись.

Готовые инструменты

Помимо skill Мэтта Покока, уже существуют инструменты для автоматического создания ADR.

auto-adr работает с Claude Code. По команде /adr агент формирует документ на основании истории текущей сессии. Это позволяет сохранить решения, которые обсуждались во время разработки, а не восстанавливать их исключительно по коду.

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

Ещё один интересный пример описал Andrew Connell в статье Architecture Decision Records as Long-Term Memory for an AI Coding Agent.

За несколько месяцев работы с Claude Code в его проекте накопился 141 ADR. Он добавил правило, по которому агент после выполнения плана предлагает зафиксировать важные решения, а автор подтверждает их.

Connell отдельно хранит правила проекта, спецификации и ADR. Первые объясняют агенту, как работать, вторые описывают требования, а ADR сохраняют причины архитектурных решений.

При изменении старого кода агент может обратиться к этим записям, вместо того чтобы заново предлагать уже отвергнутые варианты.

Сам формат и правила создания ADR лучше подстраивать под конкретную команду. Универсальный skill вряд ли сможет одинаково хорошо учитывать процессы разных проектов.

Как это можно настроить

Отдельный инструмент для старта не обязателен. Хватит короткого правила в AGENTS.md или CLAUDE.md, которое агент читает в каждой сессии. Как устроены такие инструкции, я писал в посте про AGENTS.md для Codex и Claude Code.

## ADR

Во время задачи веди черновик решений
в docs/adr/drafts/<task-id>.md.
Записывай выбранный вариант,
отвергнутые альтернативы и причину.

Перед завершением задачи проверь три условия.
1. Решение дорого или сложно изменить.
2. Без контекста будет непонятно, почему сделали именно так.
3. Были реальные альтернативы.

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

Где хранить итоговую запись, зависит от доступа агента. Если он работает с Jira или Linear через интеграцию, ADR можно оставить комментарием к задаче. Если нет, удобнее папка docs/adr/ в репозитории с номером и коротким названием в имени файла, например 0014-drop-reservation.md. Тогда агент найдёт записи обычным поиском по коду, а в задаче останется ссылка на файл.

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

Что в итоге

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

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

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