РАЗРАБОТКА

Почему AI-агент забывает правила проекта и как это исправить

18 сессий Codex показали: AGENTS.md помогает AI-агенту соблюдать архитектурные правила между запусками, если инструкции можно проверить.

✍️ Редакция iTech News | 14.11.2026 | ⏱ 4 мин | Источник: Habr / Карьера
🛠

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

Об этом сообщает Habr / Карьера со ссылкой на разбор Сергея Прощаева, Tech Lead и руководителя направления Java/Kotlin-разработки в FinTech и e-commerce. Автор проверил подход на небольшом Python-сервисе со SQLite, миграциями, собственным логгером и исключением AppError. Задача у всех запусков была одной: добавить подписки с ценой в рублях, отмену и отчёт по выручке за период. Каждый запуск стартовал в новом временном каталоге, без истории диалогов и без персональных инструкций.

Проблема знакома любому, кто попробовал собирать функциональность через Codex, Claude Code или другой агентный инструмент. В одной сессии разработчик объясняет архитектуру: запросы к базе живут в отдельном модуле, изменения сущностей попадают в аудит, денежные значения имеют определённый формат. Затем начинается новая задача — и агент действует так, будто вчерашнего разговора не было. Формально он может написать рабочий код и не сломать приёмочные тесты. Но через несколько таких «маленьких» отступлений проект превращается в коллекцию локальных исключений, которую дорого поддерживать и ещё дороже передавать следующему инженеру.

Главная мысль эксперимента не в том, что модели якобы не умеют читать код. Часть соглашений агент воспроизводил и без отдельного файла: во всех трёх сессиях без правил он использовал целые копейки для денег, обращался к проектному механизму времени, поднимал AppError, не добавлял внешние пакеты, создавал миграции и не удалял записи физически. Но из восьми проверок два требования он нарушил: назвал денежную колонку price_kopecks вместо принятого формата и разместил SQL непосредственно в сервисе, хотя соседний код работал через модуль базы данных. Это хороший аргумент против привычки превращать файл инструкций в энциклопедию репозитория.

В AGENTS.md стоит хранить не всё подряд

Прощаев предлагает сначала отделить очевидное для агента от решений, которые он не сможет надёжно вывести из существующего кода. Для каждого правила полезно провести простой тест: запустит ли агент такую реализацию, если не сообщать ему о договорённости? Если ответ подтверждён сессией без инструкций, правило действительно заслуживает места в AGENTS.md. Иначе файл быстро разрастается пересказом структуры каталогов, известных команд и образцов, которые модель и так видит при чтении репозитория.

Рабочая инструкция должна не только запрещать, но и задавать наблюдаемый критерий. Например: SQL разрешён только в app/db.py; остальные модули не импортируют sqlite3 и не вызывают execute. Для сущностей с жизненным циклом состоянием служит поле status со значениями active и cancelled, а колонки вроде cancelled_at или is_active не создаются. Каждое новое изменение данных обязано вызывать db.add_audit(...). У таких требований есть причина и понятный признак нарушения, поэтому их можно обсуждать на ревью и проверять автоматически, а не гадать, «правильно ли агент понял дух архитектуры».

Особенно важна оговорка о старом коде. Если существующий модуль уже нарушает новое правило, это нужно назвать прямо. Иначе кодовый агент закономерно воспримет старую реализацию как образец и продолжит её копировать. В примере из разбора прежний users.py ещё не писал аудит, но для нового функционала запись в журнал была обязательна. Такая формулировка снимает ложную дилемму: либо срочно переписывать весь легаси-код, либо позволять новым изменениям наследовать его технический долг.

Инструкции без проверки остаются пожеланием

Второй слой — skills: отдельные каталоги с файлом SKILL.md, где описан специализированный рабочий процесс. Если AGENTS.md хранит короткие постоянные соглашения проекта, skill помогает подтянуть подробную инструкцию только для подходящей задачи: например, при работе с миграциями, аудитом или выпуском релиза. Это снижает шум в основном контексте, но не отменяет необходимости проверить, что агент действительно выполнил правила. В разборе для этого использовались скрытые от агента приёмочные проверки: они оценивали не только внешний результат отчёта, но и архитектурные ограничения.

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

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

Поделиться: Telegram X LinkedIn