Топ 6 ошибок при работе с ИИ-агентами в коде
Шесть ошибок, которые чаще всего превращают ИИ-агента из ускорителя в источник проблем: от принятого не глядя diff до задачи без тестов, где «работает» означает «агент так сказал». Разбираем, как каждая ошибка проявляется, чем заканчивается и каким правилом закрывается.
Почему агент ошибается иначе, чем автодополнение
Помощник в редакторе предлагает строку, и вы решаете, принять ли её. Агент — Claude Code, Codex CLI, Gemini CLI, Aider и им подобные — действует: сам ищет по репозиторию, правит десяток файлов, запускает команды, ставит зависимости и приходит с готовым результатом. Ошибка агента — это не неудачная подсказка, а уже сделанное изменение, и чем больше свободы он получил, тем дороже её откатывать.
Почти все проблемы, которые мы видели у команд, начинающих работать с агентами, не связаны с качеством модели. Они связаны с процессом: как ставится задача, что агенту разрешено, кто и как проверяет результат. Модели будут становиться лучше, а эти шесть ошибок останутся, потому что они про людей. Сквозная мысль подборки простая: агент ускоряет работу, но отвечает за код человек, и каждая ошибка ниже — это способ забыть об этом.
Порядок в списке — по цене последствий, а не по частоте. Самая частая ошибка — первая, самая дорогая — вторая, и они обычно ходят парой.
Топ 6 ошибок при работе с ИИ-агентами в коде
Принимать код не читая
diff слишком большой, чтобы его читать, поэтому его не читают
Агент возвращает изменение на двадцать файлов и аккуратное описание: «добавил проверку, обновил вызовы, поправил тесты». Тесты зелёные, описание убедительное, время позднее — и изменение уходит в ветку целиком. Через неделю выясняется, что вместе с проверкой агент сменил значение по умолчанию, перехватил исключение, которое должно было всплывать наверх, удалил «лишнюю» валидацию и слегка переписал соседнюю функцию, потому что она показалась ему некрасивой. Ни одно из этих действий в описании не упоминалось.
Почему это самая частая ошибка. Агент пишет верный и неверный код одинаково уверенно, а описание изменений составляет сам — и составляет его так, как понял задачу, а не так, как её поняли вы. Читать описание вместо diff — значит проверять работу агента его же словами. Усталость и объём делают остальное: изменение, которое невозможно прочитать за один присест, никто и не читает.
Как закрыть. Правило одно: если правка слишком большая, чтобы её прочитать, она слишком большая, чтобы её принять. Просите агента делить работу на шаги, каждый шаг читайте строка за строкой и задавайте вопрос «зачем это изменение» ко всему, чего не просили. Полезная привычка — просить агента перечислить все побочные правки отдельно от основной, а потом сверять этот список с diff.
- Ловится привычкой, а не инструментом
- Маленькие шаги делают чтение возможным
- Вопрос «зачем» вскрывает лишние правки
- Проявляется через недели, а не сразу
- Описание агента маскирует побочные правки
- Зелёные тесты создают ложную уверенность
самая частая ошибка, потому что каждое непрочитанное изменение — это принятое на веру · оценка 9,6
Давать широкие права
автономный режим плюс ключи от продакшена в том же окружении
Режим без подтверждений включают ради скорости: надоело нажимать «да» на каждую команду. Агент получает право запускать что угодно, а в переменных окружения той же сессии лежат ключи от боевой базы, облачного аккаунта и репозитория с правом принудительной записи. Дальше сценарии известны: агент «чистит» тестовую базу, которая оказалась не тестовой, удаляет папку, чтобы пересоздать её, делает принудительную отправку в основную ветку, ставит пакет с похожим названием, цитирует токен из конфигурации в ответе, который потом попадает в лог.
Почему это самая дорогая ошибка. Все остальные ошибки из списка обратимы откатом коммита. Удалённые боевые данные и утёкший ключ откатом не лечатся. Агент не злонамерен, он просто выполняет задачу самым коротким путём, а самый короткий путь к «тесты проходят» иногда лежит через удаление того, что мешает.
Как закрыть. Отдельная ветка и отдельное окружение для агента. Никаких ключей от продакшена в сессии, где он работает; секреты — вне репозитория и вне файлов, которые он читает. Пользователь базы только для чтения и только на копии. Список разрешённых команд вместо полной свободы: у Claude Code для этого есть настраиваемые разрешения и хуки, у Codex CLI — режимы и песочница. Автономный режим — только внутри песочницы на проекте, который не жалко.
- Закрывается настройкой один раз
- Песочницы и режимы есть у ведущих агентов
- Отдельная ветка стоит ничего
- Последствия необратимы
- Секреты в окружении незаметны до утечки
- Соблазн отключить подтверждения велик
самая дорогая ошибка, потому что боевые данные и ключи не восстанавливаются откатом · оценка 9,4
Задача одной фразой без контекста
«сделай авторизацию» — и агент выбирает стек сам
Задача, поставленная одной фразой, оставляет агенту все решения: какую библиотеку взять, где хранить сессии, как называть таблицы, что делать с существующей моделью пользователя. Он честно принимает эти решения — быстро, уверенно и не так, как принял бы человек, знающий проект. В результате появляется новая зависимость, второй способ делать то, что уже делается в соседнем модуле, и архитектура, которую придётся обсуждать после того, как она написана.
Почему так выходит. Агент не знает, чего вы не сказали. У него нет вашего представления о том, что в проекте «само собой разумеется»: об обработке ошибок, о транзакциях, о том, что новые зависимости добавляются через обсуждение. Без контекста он подставляет самые распространённые решения из своего опыта, и они не обязаны совпадать с вашими.
Как закрыть. Контекст в задаче: что уже есть и где, какие ограничения, чего не трогать, как понять, что готово. Постоянный контекст — в файле правил проекта, который агент читает в начале каждой сессии. И привычка сначала просить план: «опиши, что собираешься менять и почему», обсудить, а потом выполнять. Пять минут на план экономят час на откат.
- Проявляется быстро, на первом же ревью
- Закрывается файлом правил проекта
- План перед выполнением ловит большинство расхождений
- Порождает лишние зависимости и дубли
- Архитектурные решения принимаются агентом
- Каждую сессию контекст приходится повторять без файла правил
ошибка постановки, из-за которой решения принимает тот, кто не знает проект · оценка 9,1
Незнакомая кодовая база и уверенный тон агента
вы не знаете код, агент тоже, но звучит так, будто знает
Самая опасная комбинация: разработчик работает с чужим или старым кодом, который сам понимает слабо, и просит агента внести правку. Агент читает часть файлов, строит правдоподобную картину и правит по ней. Картина неполная: он не заметил, что функция вызывается ещё из двух мест, что модуль обходит общую обработку ошибок специально, что «мёртвый» код на самом деле используется через отражение. Всё это он сообщает с интонацией человека, который в этом коде работал годами.
Почему это опасно. В знакомом коде вы бы заметили расхождение мгновенно. В незнакомом единственный источник знаний — агент, и проверить его словами некому. Агент на незнакомой базе уверенно делает неверное, и уверенность здесь не признак правоты, а свойство формы ответа. Выдуманные функции, несуществующие параметры и «общепринятые» соглашения, которых в проекте нет, — обычный результат.
Как закрыть. Сначала вопросы, потом правки. Попросите агента объяснить, как устроен модуль, где точки входа, кто вызывает изменяемую функцию, — и проверьте это по коду сами, хотя бы выборочно. Маленькие пробные изменения с запуском тестов покажут, насколько картина агента совпадает с реальностью. Пригодятся и способы разобраться в чужом коде — агент их ускоряет, но не заменяет.
- Вопросы до правок вскрывают неполную картину
- Пробные изменения дёшевы
- Агент хорош как проводник, если его проверять
- Уверенный тон маскирует незнание
- Некому заметить расхождение сразу
- Выдуманные API выглядят правдоподобно
ошибка доверия, при которой единственный источник знаний нельзя проверить · оценка 8,9
Огромный запрос без точек отката
«перепиши модуль» — и через час сорок файлов без единого коммита
Большая задача одним запросом кажется экономией времени: агент сам всё сделает, а вы посмотрите в конце. В конце — diff на сорок файлов, половина из которых изменилась по дороге, чтобы «согласовать» с новым кодом. Что-то в нём работает, что-то сломано, и разделить одно от другого невозможно: коммитов не было, промежуточных состояний нет, откат означает потерю всего, включая удачное.
Почему так выходит. Агент не устаёт и не останавливается сам, чтобы зафиксировать шаг. Длинная сессия ещё и переполняет контекст: к концу агент забывает, о чём договаривались в начале, и последние правки противоречат первым. Без точек отката единственный выбор — принять всё или выбросить всё.
Как закрыть. Шаг — проверка — коммит. Просите план, разбитый на пункты, и выполняйте по одному, фиксируя каждый удачный шаг в git; Aider делает это сам, остальных нужно просить. Тогда неудачный шаг откатывается одной командой, а удачные остаются. Базовые приёмы описаны в подборке вещей, которые нужно знать про git, — с агентами они нужнее, чем когда-либо.
- Закрывается дисциплиной коммитов
- Маленькие шаги читаются и откатываются
- План по пунктам виден до выполнения
- Длинные сессии теряют контекст
- Откат «всё или ничего» теряет удачное
- Соблазн «пусть сделает сам» силён
ошибка масштаба, после которой нельзя откатить неудачное, не потеряв удачное · оценка 8,7
Нет тестов и линтера как объективной проверки
«работает» означает «агент так сказал»
В проекте без тестов результат работы агента проверяется единственным способом — его собственным отчётом. Он запустил, посмотрел, решил, что нормально. Линтера нет, поэтому неиспользуемые импорты, неверные типы и опечатки в именах доживают до продакшена. Агент при этом оптимизирует ровно то, что видит: если единственный сигнал — «нет ошибки в консоли», он добьётся отсутствия ошибки в консоли, а не правильного поведения.
Почему это ошибка процесса, а не проекта. Тесты и линтер — единственная проверка, которую агент не может «убедить». Они дают ему быстрый и честный сигнал, и агенты с замкнутым циклом — написал, запустил, исправил — на проектах с тестами работают заметно лучше именно поэтому. Без них вся проверка ложится на чтение diff человеком, а первую ошибку из этого списка мы уже обсудили.
Как закрыть. Команда запуска тестов и линтера — в файле правил проекта, с требованием запускать после каждого шага. Если тестов нет, первая задача агенту — написать характеризационные тесты на то, что предстоит менять, и проверить, что они падают при намеренной поломке. Проверка типов и линтер настраиваются один раз, и с этого момента у агента появляется объективный критерий, а у вас — фильтр, который работает без усталости.
- Настраивается один раз, работает всегда
- Даёт агенту честный сигнал
- Снимает часть нагрузки с ревью
- На старом проекте требует времени на старт
- Агент может подгонять тесты под результат
- Зелёный прогон не заменяет чтение
ошибка основания, без исправления которой все остальные правила держатся на честном слове · оценка 8,5
Сравнение по главному
| Ошибка | Как проявляется | Чем закрывается |
|---|---|---|
| Принимать код не читая | побочные правки всплывают через недели | маленькие шаги, чтение diff, вопрос «зачем» |
| Давать широкие права | удалённые данные, утёкший ключ | ветка, песочница, список команд, секреты вне сессии |
| Задача без контекста | лишние зависимости, дубли, чужая архитектура | файл правил, план перед выполнением |
| Незнакомая база и уверенный тон | выдуманные API, сломанные вызовы | вопросы до правок, пробные изменения |
| Огромный запрос без отката | сорок файлов, всё или ничего | шаг — проверка — коммит |
| Нет тестов и линтера | «работает» со слов агента | команды проверки в правилах, тесты до правок |
Минимальный набор правил перед первым запуском
Отдельная ветка и отдельное окружение. Агент работает в ветке, которую не жалко удалить, и в сессии, где нет ключей от боевых систем. Это занимает минуту и закрывает самую дорогую ошибку из списка.
Файл правил в корне репозитория. Как собирать, как запускать тесты и линтер, каких соглашений держаться, куда не лезть, какие зависимости нельзя добавлять без обсуждения. У Claude Code это CLAUDE.md, у Codex CLI — AGENTS.md, у Gemini CLI — GEMINI.md; содержание одно и то же.
Объективная проверка после каждого шага. Тесты, линтер, проверка типов — запускаются агентом сами и решают, принят ли шаг. Правило «падающий тест не исправляют подгонкой ожидания» записывается явно.
План перед выполнением, коммит после проверки. Задача делится на пункты, каждый пункт заканчивается прогоном и коммитом. Diff каждого шага читается человеком до следующего.
На незнакомом коде — сначала вопросы. Прежде чем разрешить правку, попросите объяснить устройство модуля и проверьте объяснение. Уверенный тон агента — не аргумент.
Частые вопросы
Агент изменил то, чего я не просил. Что делать?
Откатить лишнее и записать в файл правил, чего не трогать без явной просьбы: соседние функции, форматирование, зависимости. Полезно просить агента перечислять побочные правки отдельным списком, чтобы сверять с diff. Если лишние изменения повторяются, задача была поставлена слишком широко — разбейте её.
Можно ли давать агенту ключи от тестового окружения?
Да, если оно действительно тестовое: отдельная база, отдельный аккаунт, данные, которые не жалко потерять, и никаких путей в продакшен. Ключи всё равно лучше держать вне репозитория и вне файлов, которые агент читает, — он может процитировать их в ответе. Проверьте, что тестовое окружение не делит учётные записи с боевым.
Как понять, что агент выдумал функцию или параметр?
Запустить. Выдуманный вызов не соберётся или упадёт на первом тесте — если тесты есть. Для библиотек просите агента показать документацию или сигнатуру из установленного пакета, а не из памяти. Признак выдумки — «общепринятый» параметр, о котором вы никогда не слышали, названный с полной уверенностью.
Насколько мелко делить задачи?
Так, чтобы diff одного шага читался за один присест и откатывался одним коммитом. Для большинства задач это одно логическое изменение: миграция, модель, обработчик — три шага, а не один. Если агент к концу шага начинает забывать начало, шаг слишком большой.
Итог
Все шесть ошибок — про одно и то же: агент получил больше доверия, чем заслужил проверкой. Непрочитанный diff, ключи в сессии, задача без контекста, незнакомый код, огромный запрос и отсутствие тестов — это шесть способов не проверять, и последствия отличаются только ценой.
Закрываются они дёшево: отдельная ветка, файл правил, команды самопроверки, маленькие шаги с коммитами и привычка читать. Агент при таком процессе действительно ускоряет работу, потому что ошибку он делает так же быстро, как и правильный код, — и только процесс отличает одно от другого.
Комментарии
0Будьте первым, кто ответит автору.