Сто комментариев на пул-реквест: почему ИИ-агент пишет слоп и что с этим делать
Habr AI · оригинал
Материал подготовлен автоматизированной редакционной системой. Факты можно сверить по указанному первоисточнику.

Качество кода, генерируемого ИИ-агентами, часто страдает не из-за ограничений моделей, а из-за отсутствия структурированных знаний в репозитории. Для решения проблемы разработчикам необходимо внедрять файлы конфигурации AGENTS.md, автоматизировать проверки и пересмотреть процессы код-ревью.
Переход к агентной разработке меняет требования к инфраструктуре проектов: без явных правил и автоматических проверок ИИ воспроизводит легаси-паттерны, создавая технический долг и снижая эффективность команд.
Скепсис многих руководителей разработки в отношении ИИ-инструментов часто обусловлен негативным опытом взаимодействия с ранними версиями таких систем. Пользователи сталкиваются с так называемым «AI slop» — кодом, который формально собирается и проходит базовые тесты, но нарушает внутренние стандарты команды, дублирует устаревшие паттерны и требует значительных доработок. Автор материала, ранее занимавший позицию технического директора в сервисе каршеринга, утверждает, что корень проблемы лежит не в самой нейросети, а в неподготовленной среде разработки. ИИ-агент функционирует как постоянный новичок: он не обладает долговременной памятью о контексте проекта и при каждом запросе опирается исключительно на данные, доступные в репозитории.
В отличие от человека, который усваивает неявные договоренности команды через общение и опыт, агент видит только код. Если в проекте отсутствуют задокументированные правила, модель будет использовать в качестве образца самые старые или неоптимальные участки кода. Это приводит к смысловым ошибкам: код может выглядеть корректно, но строиться на неверном понимании бизнес-логики или игнорировать критические edge cases. Такие дефекты сложнее обнаружить при ревью, чем синтаксические ошибки, так как они не ломают сборку, но нарушают логику работы системы.
Для решения этой задачи автор предлагает внедрять файл AGENTS.md в корне репозитория. Этот документ служит шпаргалкой для агента и должен содержать краткое описание структуры проекта, команды сборки, специфические термины и накопленные командой знания. Важно, чтобы этот файл оставался компактным и актуальным, а не превращался в объемную вики-страницу, которая быстро устаревает. Эффективным методом наполнения такого файла является анализ истории пул-реквестов: агент может собрать все комментарии ревьюеров за последний год, что позволит выявить повторяющиеся ошибки и сформировать список правил.
Помимо документации, критически важно предоставить агенту возможность проверять результаты своей работы. Если проект позволяет локальную сборку, необходимо записать четкие инструкции или скрипты для запуска тестов. Для крупных распределенных систем требуются превью-стенды (например, через GitLab Review Apps или Argo CD), где агент может протестировать свою ветку в изолированной среде. Это позволяет модели самостоятельно верифицировать изменения, обращаясь к API или базе данных, а не полагаться только на статический анализ кода.
Любые текстовые инструкции для ИИ являются лишь рекомендациями, которые могут быть потеряны при сжатии контекста. Поэтому все критические правила должны быть закреплены программными средствами: линтерами, хуками и CI-пайплайнами. Например, правило о чтении данных только из мастер-базы после записи лучше реализовать как ошибку линтера с пояснением, чем как текст в документации. Это гарантирует, что агент получит мгновенную обратную связь и не сможет обойти проверку.
Процесс код-ревью также трансформируется. При высокой скорости генерации кода ручное чтение каждой строки становится невозможным. Рекомендуется использовать двухэтапный подход: один агент пишет код, а другой, в новой сессии, выполняет ревью. Человеческое внимание следует сосредоточить на архитектурных решениях, безопасности и изменениях схемы базы данных. Для упрощения этой задачи агент должен сам выносить ключевые решения в описание пул-реквеста.
Наконец, необходимо учитывать вопросы безопасности. Агент действует от имени пользователя и имеет доступ к его правам. Для минимизации рисков рекомендуется ограничивать доступ агента к продуктивным окружениям, использовать песочницы для выполнения команд и внедрять хуки, требующие подтверждения человека перед выполнением потенциально опасных операций. Начать внедрение этих практик можно с простого теста: попросить агента найти конкретный модуль в проекте и проанализировать его путь поиска, чтобы определить, какие знания отсутствуют в текущей документации.