Интенсив 21–22.11 · БесплатноБесплатный 2-дневный интенсив по вайбкодингу 21–22 ноября в 16:00 МСК (Сб–Вс) · Живой Поток 3 стартует 23.11Записаться бесплатно →Поток 3 (23.11)
РелизКод / SDK · В работуHabr AI→ оригинал

Почему ИИ-агент пишет слоп: бывший CTO Ситидрайва объяснил, как подготовить репозиторий

Агент пишет слоп не потому, что модель плохая: он как новичок, который каждое утро забывает вчерашнее ревью, а договорённости команды в коде не записаны. Экс-техдиректор Ситидрайва советует завести AGENTS.md на пару сотен строк и проверять правила линтерами, хуками и CI. Стартовый материал для файла проще всего взять из комментариев к пул-реквестам за последний год. Так агент реже наступает на одни и те же грабли в каждой новой сессии.

AI-обработка оригинала Habr AI; редакция Hamidun News
Почему ИИ-агент пишет слоп: бывший CTO Ситидрайва объяснил, как подготовить репозиторий
Источник: Habr AI. Коллаж: Hamidun News.
Слушать статью
Паспорт материала и цифры
ПараметрДанные
ПервоисточникHabr AI ↗
Главный редактор
Ключевой факт #1Агент забывает всё между сессиями — помнит только файлы репозитория
Ключевой факт #2CI должен укладываться в 20–30 минут, иначе скорость агентов пропадёт
Ключевой факт #3Один агент пишет код, другой в свежей сессии его ревьюит

Скептики ИИ-разработки обычно рассказывают одну и ту же историю. Попробовали инструмент, код собрался и даже прошёл тесты, но написан не так, как принято в команде, копирует худшие места проекта и разваливается от первой правки. Это и есть AI slop, «помои». Автор разбора, который почти год назад ушёл с поста технического директора каршеринга Ситидрайв ради агентской разработки, считает, что чаще виновата не модель, а репозиторий, не подготовленный для агента.

Агент как новичок, который каждое утро приходит впервые

Автор начинает с истории 2019 года. Он руководил разработкой «Такси ВКонтакте» на VK Mini Apps, и в команду из двух человек наняли третьего, сильного разработчика с другими привычками. Записанных правил не было, поэтому на один пул-реквест в полторы тысячи строк оставили рекордные сто комментариев. Через десяток пул-реквестов комментарии можно было пересчитать по пальцам. Но часть знаний новичку взять было неоткуда. Что-то жило только в головах, а от каких-то подходов команда отказалась, обжёгшись, и следа в репозитории не осталось.

Теперь представьте, что этот разработчик каждое утро обнуляется. Агент ведёт себя так же. У модели нет памяти: при каждом запросе ей отправляют всю историю разговора, а когда контекст заполняется, разговор сжимается и указания из начала сессии теряются. Проект целиком агент в голове не держит и видит только то, что сам нашёл.

Автор приводит три типичные ловушки:

  • В проекте сто модулей, десять свежих написаны хорошо, девяносто старых — легаси. Агент не знает, какие из них образец, и может взять за пример самый первый и самый плохой.
  • Интеграционные тесты в Java-проекте запускают командой mvn test -P integration. Агент запустит обычный mvn test, получит «No tests to run» и BUILD SUCCESS и решит, что всё зелёное.
  • Только что записанные данные в команде читают с мастера, потому что реплика может отставать. Новичка поправят один раз, а агент будет повторять ошибку в каждой сессии.

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

Записать знания и дать агенту увидеть результат

Первый шаг — файл AGENTS.md в корне репозитория. Его читают Claude Code, Codex и другие агенты. Автор сравнивает его с листочком А4, который выдают новичку в первый день: он должен занимать пару сотен строк, а не пятьдесят страниц вики. Внутри пять вещей: что это за репозиторий, где что лежит, команды сборки и тестов, неписаные договорённости и словарь терминов команды. Пересказывать в нём код не нужно, иначе появятся два источника правды, а настоящий — только код, работающий на проде.

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

Ещё агенту нужна среда, где он увидит результат своей работы. Если проект небольшой, он разворачивается локально. Цепочку команд лучше оформить скриптом: текст инструкции агент каждый раз читает по-своему, а скрипт выполняется одинаково. Для больших проектов нужен превью-стенд на каждый пул-реквест, а такие стенды умеют поднимать Vercel, Netlify, GitLab Review Apps и Argo CD. Агент забирает адрес стенда, дёргает эндпоинты, смотрит данные в базе или прокликивает браузер по тест-кейсам.

Проверять программой и ограничивать права

Любое правило в AGENTS.md остаётся просьбой: агент может его не выполнить или потерять после сжатия контекста. Поэтому всё, что проверяется программой, стоит проверять программой:

  • Сначала тест, потом код. Иначе у агента появляется соблазн подогнать под код сам тест.
  • Линтеры с понятными сообщениями. Правило про мастер и реплику можно оформить как проверку, которая запрещает чтение из реплики сразу после записи, и в тексте ошибки объяснить, как исправить.
  • Хуки. Claude Code может сам запускать линтер после каждой правки.
  • CI, без которого нельзя смержить. Конфиги CI и тесты меняются только с одобрения владельцев из CODEOWNERS, а все проверки должны занимать 20–30 минут, иначе они съедят выигрыш в скорости.

Ревью тоже меняется. Если разработчик раньше закрывал три-четыре задачи в неделю, то теперь может закрывать три-четыре в день, и читать всё построчно физически невозможно. Автор предлагает схему: один агент пишет код, другой в свежей сессии его ревьюит, потому что автор кода проверяет его с тем же контекстом. Человек смотрит на решения, которые трудно откатить: схему базы, права доступа, безопасность, архитектуру. Чтобы не искать их в диффе на 20 тысяч строк, агент сам выносит ключевые решения в описание пул-реквеста.

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

Чтобы начать, спросите агента про часть проекта, которую вы знаете лучше всех: где лежит нужный код. Посмотрите, какие команды поиска он запускал и сколько кругов сделал. Всё, что он искал долго или нашёл неверно, станет первыми строками вашего AGENTS.md. Полную версию подхода автор выложил в бесплатной книге про Agentic SDLC на GitHub. Это личный опыт одного практика, а не измеренное исследование, цифр эффекта в тексте нет. Но советы проверяемы и ничего не стоят в попытке.

Сюжет

Вопросы и ответы по материалу

Что известно по теме: агент как новичок, который каждое утро приходит впервые?

Автор начинает с истории 2019 года. Он руководил разработкой «Такси ВКонтакте» на VK Mini Apps, и в команду из двух человек наняли третьего, сильного разработчика с другими привычками. Записанных правил не было, поэтому на один пул-реквест в полторы тысячи строк оставили рекордные сто комментариев. Через десяток пул-реквестов комментарии можно было пересчитать по пальцам. Но часть знаний новичку взять было неоткуда.

Что известно по теме: записать знания и дать агенту увидеть результат?

Первый шаг — файл AGENTS.md в корне репозитория. Его читают Claude Code, Codex и другие агенты. Автор сравнивает его с листочком А4, который выдают новичку в первый день: он должен занимать пару сотен строк, а не пятьдесят страниц вики. Внутри пять вещей: что это за репозиторий, где что лежит, команды сборки и тестов, неписаные договорённости и словарь терминов команды. Пересказывать в нём код не нужно, иначе появятся два источника правды, а настоящий — только код, работающий на проде.

Что известно по теме: проверять программой и ограничивать права?

Любое правило в AGENTS.md остаётся просьбой: агент может его не выполнить или потерять после сжатия контекста. Поэтому всё, что проверяется программой, стоит проверять программой: Сначала тест, потом код. Иначе у агента появляется соблазн подогнать под код сам тест. Линтеры с понятными сообщениями. Правило про мастер и реплику можно оформить как проверку, которая запрещает чтение из реплики сразу после записи, и в тексте ошибки объяснить, как исправить. Хуки.

ЖХ
Жемал Хамидун — CPO Alpina Digital, продакт-менеджер AlpinaGPT. Делает AI-продукты с 2019 года. Hamidun News — pet project, который вырос в production-агрегатор с 6000+ читателей.
✦ ИИ-агенты на практике · Академия & Nomad

От чтения про ИИ-агентов — к запуску своего агента за вечер

Пошаговая сборка автономных агентов и MCP-связок в Hamidun Academy (academy.hamidun.com) (72 часа бесплатно) или мгновенный запуск готовых мультишаговых агентов в облаке Nomad.

Попробовать Академию (72ч бесплатно) →Запустить Nomad Agent
Что вы думаете?
Загружаем комментарии…