Типичные ошибки

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

1. Размытая постановка

Симптом: «сделай нормально», «почини», «улучши», а результат каждый раз «не то», и приходится переделывать.

Почему: агент не читает мысли. Всё, что не сказано, модель додумывает по самому статистически вероятному сценарию, а он редко совпадает с вашим.

Как правильно: проговаривайте цель, контекст, ограничения и критерий готовности в каждой постановке. Подробно с примерами: Промптинг.

2. Одна бесконечная сессия на всё

Симптом: к вечеру агент «тупеет»: забывает договорённости, путает задачи, повторяет уже отвергнутые решения.

Почему: контекстное окно забито историей десятка задач; важное вытеснено или тонет в шуме.

Как правильно: новая задача — новая сессия; долгоживущие знания храните в файлах, а не в диалоге. Разбор: Контекст-инжиниринг.

3. Слепое принятие результата

Симптом: «выглядит хорошо, вливаем», а через неделю выясняется, что тест был удалён, а цифра в отчёте выдумана.

Почему: результаты агента выглядят увереннее и аккуратнее человеческих, и это отключает бдительность. Уверенность модели никак не связана с корректностью.

Как правильно: результат агента — черновик; тесты, запуск, чтение диффа, факт-чекинг обязательны. Чек-лист: Проверка результатов.

4. «Агент = поисковик»

Симптом: агенту задают только вопросы «как сделать X?», получают ответ текстом и идут делать руками.

Почему: привычка к чат-ботам: люди не знают, что агент может сам прочитать проект, внести правки, прогнать тесты и показать дифф.

Как правильно: давайте агенту задачи, а не вопросы: не «как настроить линтер», а «настрой линтер в этом проекте и почини найденное». Что агент умеет: Что такое агент.

5. Всё одним промптом, без декомпозиции

Симптом: задача на неделю поставлена одним сообщением «сделай всю фичу»; агент долго работает и приносит гору изменений, которую невозможно ни проверить, ни принять.

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

Как правильно: план → шаги → после каждого шага проверка и коммит. Процесс: Рабочий цикл.

6. Игнор памяти проекта

Симптом: каждую сессию вы заново объясняете одно и то же: как запускать тесты, какой стиль кода, чего не трогать.

Почему: агент не помнит прошлых сессий: постоянные знания сами себя в файл не запишут.

Как правильно: заведите файл памяти проекта (CLAUDE.md / AGENTS.md) и пополняйте его каждый раз, когда ловите себя на повторном объяснении. Как это работает: Память.

7. Перегрузка контекста лишним

Симптом: подключено пятнадцать MCP-серверов «про запас», в промпт вставлен весь лог целиком, и агент стал медленнее, дороже и глупее.

Почему: каждый подключённый инструмент и каждая вставленная простыня занимают контекстное окно и размывают внимание модели ещё до начала работы.

Как правильно: только нужные для задачи серверы и скилы; ссылки на файлы вместо вставки содержимого. Принцип дозирования: Контекст-инжиниринг.

8. Секреты в промптах

Симптом: «вот конфиг с ключом API, посмотри, что не так», и ключ ушёл на внешний сервер.

Почему: кажется, что чат — это приватный блокнот. На деле всё содержимое контекста отправляется провайдеру модели и может храниться.

Как правильно: секреты храните в переменных окружения, .env держите вне зоны доступа агента; попавший в контекст секрет перевыпустите. Подробнее: Безопасность и приватность.

9. Ожидание телепатии («он же видит проект»)

Симптом: «зачем объяснять, где что лежит, код же открыт», а агент правит не тот модуль или изобретает параллельную реализацию существующей функции.

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

Как правильно: называйте файлы и системы явно, показывайте образцы («сделай как в X»), неписаные правила записывайте. Анатомия постановки: Промптинг.

10. Отказ после первой неудачи

Симптом: первый результат оказался плохим: вывод «агенты не работают», возврат к ручному труду.

Почему: ожидание магии: кажется, что инструмент должен работать идеально сразу. Но работа с агентом — навык, как работа с отладчиком или git: первый блин комом у всех.

Как правильно: разберите неудачу как инцидент: чего не хватило в постановке? был ли перегружен контекст? был ли шаг проверяемым? Почти всегда причина находится в одном из пунктов этой страницы. Дайте инструменту десять задач, а не одну, и сравнивайте не с идеалом, а с тем, сколько времени заняло бы то же самое вручную.

Что дальше

Обзор харнесов: пора выбрать инструмент и применить всё это на практике.
Рабочий цикл: если хотите ещё раз пройтись по процессу целиком.

Автор учебника — Шахматов Алексей