Как заставить ИИ-агента соблюдать правила проекта между сессиями

Habr AI · оригинал

Материал подготовлен автоматизированной редакционной системой. Факты можно сверить по указанному первоисточнику.

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

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

Проблема «потери памяти» у AI-агентов при смене сессий становится всё более актуальной по мере распространения инструментов вайб-кодинга. Разработчик Сергей Прощаев, Tech Lead в FinTech и преподаватель ОТУС, описывает ситуацию, когда агент, обученный в одной сессии соблюдать определённые правила (например, хранение SQL в отдельном модуле или использование специфических форматов ошибок), в следующей сессии нарушает их, даже если функциональные тесты проходят успешно. Это происходит потому, что договорённости остаются в истории чата, а не в коде или файлах конфигурации.

Для решения этой проблемы автор предлагает методологию, основанную на стандартах AGENTS.md и Agent Skills. Эксперимент проводился с использованием Codex CLI и модели gpt-6.1-sol на базе небольшого Python-сервиса. Ключевой вывод первого этапа: агент самостоятельно выводит из кода большинство стандартных практик (например, использование стандартной библиотеки или корректное управление временем), но нарушает нестандартные соглашения проекта. Поэтому в файл правил следует включать только те решения, которые агент не сможет вывести из анализа существующего кода.

Важным аспектом является формат записи правил. Каждое правило должно содержать название, описание, причину его введения и явный признак нарушения. Например, запрет на создание колонок-флагов (cancelled_at) в пользу поля status должен быть обоснован тем, что флаги могут противоречить друг другу при расширении жизненного цикла сущности. Если правило противоречит существующему коду, это нужно явно указать, чтобы агент не воспринял старый код как образец.

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

Критически важным шагом является проверка правил в «чистой» среде. Личные инструкции разработчика, хранящиеся в глобальных файлах, могут маскировать проблемы проекта. Для объективной оценки необходимо изолировать окружение, отключив доступ к личным skills и глобальным AGENTS.md. Это имитирует условия работы нового участника команды или CI-пайплайна.

Исследование ETH Zurich «Evaluating AGENTS.md» подтверждает, что файлы инструкций, написанные разработчиками, незначительно повышают долю решённых задач, но увеличивают стоимость вычислений. Это подчёркивает необходимость минимализма: каждая строка в AGENTS.md должна окупаться снижением количества ошибок. Автоматические проверки (check.py) помогают верифицировать соблюдение правил, но они не заменяют полноценные тесты бизнес-логики.

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