Типичные ошибки и как из них выходить

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

1. Один чат на весь проект

Признак. Сессия идёт с утра. В ней была фича, потом баг в соседнем модуле, потом вопрос про nginx. Агент путает файлы, вспоминает отменённые решения, забывает правила.

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

Выход. Новая задача — новый чат (/new в CLI). Если нужно продолжить, но контекст разросся, — /compact. Если задача долгая и переходит на следующий день, попросите агента записать состояние в файл плана или в карточку задачи: что сделано, что осталось, какие команды запускать. Утром новая сессия начнётся с этого файла.

2. Третья поправка подряд

Признак. «Нет, не так». «Опять не то». «Я же просил без этого». С каждой поправкой результат не приближается к нужному, а уходит в сторону.

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

Выход. Остановитесь после второй неудачной поправки. Два варианта:

• нажмите Esc дважды на пустом поле ввода, отредактируйте исходное сообщение с учётом того, что поняли, и Codex ответвится от этой точки;
• начните новый чат с исправленной постановкой.

Разговор так «откатывается», но не рассчитывайте, что вместе с ним откатятся файлы на диске. Состояние кода возвращайте через git: git restore, git stash или откат к коммиту.

3. Постоянные правила в промпте

Признак. Каждый промпт начинается с одного и того же абзаца: «используй BEM, не трогай vendor, тесты запускай через make test».

Почему. То, что сказано в чате, живёт только в этом чате. После сжатия или в новой сессии правило теряется, и вы снова его повторяете — или забываете.

Выход. Перенесите в AGENTS.md (см. урок AGENTS.md: инструкции проекта). Хорошее правило из рекомендаций Codex: если агент совершил одну и ту же ошибку дважды, попросите его разобрать, что пошло не так, и предложить правку в AGENTS.md. Повторяющиеся процессы — в навыки.

4. Агенту нечем себя проверить

Признак. Агент заканчивает словами «изменения внесены, должно работать». Тесты он не запускал, потому что не знает как: в проекте Docker, особая команда, нужна база.

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

Выход. Команды сборки, тестов и линтера — в AGENTS.md, с точными строками для копирования. В каждой задаче — условие «готово, когда»: какие команды прошли, какое поведение изменилось. Для вёрстки — скриншоты (см. урок Вёрстка по макету).

## Проверка перед «готово»
- PHP: `docker compose exec app composer test`
- Фронт: `cd themes/site && npm run build`
- E2E по затронутой странице: `npx playwright test tests/e2e/<страница>.spec.ts`
- В отчёте — команды и их фактический вывод, а не пересказ.

5. «Готово» без доказательств

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

Почему. Отчёт агента — его версия событий. Агент может искренне считать задачу решённой.

Выход. Просите команды и их вывод, читайте дифф сами, запускайте /review перед коммитом. Отдельно смотрите на изменения в тестах: агент не должен менять ожидания теста, чтобы тот прошёл, если вы об этом не просили. Это правило тоже стоит записать в AGENTS.md. Подробно — в уроке Как ревьюить код, написанный агентом.

6. Задача разрастается

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

Почему. Агент видит то, что можно улучшить, и улучшает. Ограничения ему никто не поставил.

Выход. В постановке — явная граница: «меняй только LeadForm::onSubmit и его тест». Перед коммитом — /diff или git diff --stat. Лишнее откатывайте точечно (git restore -p) и говорите агенту, что откатили и почему, иначе он вернёт это на следующем шаге. Найденные по дороге проблемы просите не чинить, а выписать списком в конце.

7. Полные права слишком рано

Признак. Надоели запросы одобрения, и вы запускаете --yolo в рабочей папке с доступом к ~/.ssh, продовым ключам в .env и сети.

Почему. Одобрения раздражают, пока процесс не настроен. Но полный доступ снимает и песочницу, а не только вопросы.

Выход. Начинайте с прав по умолчанию. Если агенту не хватает конкретного каталога — --add-dir. Если надоело одобрять одну и ту же безопасную команду — правило для неё (см. Rules). Для промежуточного варианта есть автоматическое ревью одобрений (--approve-for-me): решения о выходе за песочницу принимает отдельный агент-проверяющий, а сама песочница остаётся. Полный доступ — только внутри изолированного контейнера.

8. Параллельные задачи в одной папке

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

Выход. Каждой параллельной задаче — свой worktree, а веб-проекту — ещё и свой стенд (см. урок Несколько задач параллельно).

9. Смотреть на каждый шаг

Признак. Агент работает двадцать минут, и все двадцать минут вы смотрите в терминал.

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

Выход. Хорошо поставленная задача с условием «готово» не требует присмотра. Включите уведомления о завершении хода — в CLI за это отвечает секция [tui] в config.toml (ключ notifications), — и занимайтесь своим. Возвращайтесь на запросы одобрения и к готовому диффу.

10. Автоматизация раньше ручного успеха

Признак. Задача по расписанию или бот в CI, который каждый раз выдаёт что-то разное.

Выход. Сначала добейтесь стабильного результата руками в обычном чате, потом упакуйте процесс в навык, и только потом ставьте на расписание. В документации Codex это сформулировано так: навык задаёт метод, расписание — время запуска.

Общий выход из любой ямы

Когда непонятно, что пошло не так, помогает одна и та же последовательность:

1. Прервите текущий ход.
2. Посмотрите на код, а не на разговор: /diff, git status.
3. Верните код в известное хорошее состояние через git.
4. Сформулируйте, что вы теперь знаете о задаче, чего не знали в начале.
5. Начните новый чат с постановкой, в которую это вошло.
6. Если причина была в среде — нет команды, правила или доступа, — исправьте AGENTS.md или конфигурацию, чтобы в следующий раз не наступить туда же.

Последний шаг — самый ценный. Ошибка, исправленная в среде, больше не повторится ни у вас, ни у коллег. В этом и состоит идея курса Harness engineering.