ADR в веб-разработке: какие решения фиксировать, если вы работаете один
ADR - это короткая запись принятого архитектурного решения с контекстом, вариантами и последствиями. Для небольшого проекта достаточно нескольких записей только на решения, которые дорого менять.
Запись нужна не для отчета, а для памяти. Через три месяца забывается не само решение, а причина: почему выбрана эта СУБД, почему доступ устроен так, почему введен отдельный слой для данных. Без причины старое решение выглядит случайным и его хочется переписать. AI-агент ускоряет этот процесс: он предлагает альтернативную архитектуру или тихо сдвигает границы, потому что не знает ограничений, которые были учтены полгода назад.
Правило отбора простое: фиксируйте то, что больно откатывать. Если изменение затрагивает базу, доступ, API или деплой - это кандидат в ADR. Если изменение локальное, не затрагивает архитектурные границы и легко обратимо без существенных последствий, отдельная запись обычно избыточна.
Когда ADR нужны, а когда нет
Размер проекта и CMS сами по себе не определяют необходимость ADR. Определяет характер решений: есть ли нестандартная логика, интеграции, данные и доступ, цена ошибки.
| Ситуация | ADR |
|---|---|
| Лендинг без нестандартной логики | Обычно не нужны |
| Типовой WordPress-сайт | Обычно не нужны |
| WordPress с нестандартными интеграциями | По необходимости, на стыки и синхронизацию |
| CRM, SaaS, личный кабинет | Рекомендуются для ядра |
| Проект с несколькими сервисами | Рекомендуются для границ и контрактов |
| Долгая разработка с AI-агентами | Рекомендуются для ключевых решений |
Для небольшого продукта ориентиром могут быть 3-5 записей. Это не норма, а стартовая оценка: столько обычно набирается дорогих решений. Если их меньше - это нормально.
Минимальный формат
За основу удобно взять классический шаблон Майкла Найгарда: название, статус, контекст, решение, последствия. Альтернативы добавляют отдельным разделом, если важно сохранить причины отказа от других вариантов.
Для небольшого проекта достаточно фиксировать контекст, принятое решение, его последствия и статус. Этого хватает, чтобы через полгода понять, что нельзя менять без пересмотра соседних модулей.
Название: 0001 - слой доступа к данным.
Контекст: доступ к данным нужен серверным компонентам, Server Actions и Route Handlers. Проверки доступа должны выполняться в одном месте.
Решение: доступ к базе выполняется через серверный слой доступа к данным. Компоненты интерфейса и обработчики запросов не обращаются к ORM напрямую.
Альтернативы: прямые обращения к ORM из каждого модуля - отклонены, затрудняют централизованный контроль доступа и повторное использование логики.
Последствия: запросы к базе проходят через выделенный слой, проверки авторизации и прав выполняются на сервере при каждом вызове. Server Actions при этом считаются публичными точками входа и тоже требуют проверки. Новые модули соблюдают то же разделение. Статус: принято.
Название: 0002 - проверка прав на сервере.
Контекст: в CRM есть роли менеджера и администратора, часть записей привязана к владельцу.
Решение: авторизация и проверка доступа к записи выполняются на сервере при каждом запросе с учетом роли пользователя и принадлежности записи.
Альтернативы: проверка только в клиенте - отклонена, обходится; отдельные таблицы на роль - отклонены, усложняют миграции.
Последствия: клиент получает только флаг для отображения кнопки, доступ к операции флаг не определяет. Новое действие без серверной проверки не допускается. Статус: принято.
Записи занимают полстраницы и читаются за минуту. Хранение простое: папка docs/adr в репозитории, файлы 0001-db-dal.md, 0002-auth.md с номером, датой и статусом.
Регламент для AI-агента
Просто показать агенту папку с ADR недостаточно. Агент может не прочитать записи или принять решение, которое формально им не противоречит, но меняет ограничения. Нужен короткий регламент, его удобно держать в AGENTS.md или в инструкциях проекта.
- Перед изменением архитектуры агент читает записи, связанные с задачей.
- В плане указывает, какие решения затрагиваются.
- Если задача противоречит принятому ADR, сообщает об этом и ждет подтверждения, а не меняет архитектуру молча.
- Если решение действительно нужно изменить, предлагает новый ADR со ссылкой на предыдущий.
- После согласования нового решения создает ADR или обновляет связанные документы, сохраняя историю предыдущих решений.
Так ADR превращается из архива в рабочий инструмент контроля архитектурной последовательности: агент сверяется с принятыми решениями до изменения кода, а не после.
