Главная / Блог / ADR в веб-разработке

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 или в инструкциях проекта.

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

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

Частые вопросы

Чтобы не пропустить новые материалы

Короткий дайджест вечером в понедельник. Без спама.

Выберите, что получать

Обсудим ваш проект

Расскажите о вашем бизнесе, покажите текущий сайт или просто опишите задачу в свободной форме. Я изучу вводные, предложу решение и сориентирую по срокам и смете.

Отвечаю в течение нескольких часов в рабочее время.

Защита от спама – Yandex SmartCaptcha

Если вам удобнее обсудить всё текстом без заполнения форм – напишите напрямую: в Telegram или на sergei@kruglov.net

Удобнее голосом? Напишите пару слов о задаче - договоримся об удобном времени созвона на 15-20 минут, и я пришлю свой номер телефона.