Руководство: как научить ИИ-агента работать над большими проектами

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

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

Почему у агентов проблемы с большими задачами

Чтобы понять суть проблемы, нужно сначала разобраться с одним важным понятием — контекстное окно.

Контекстное окно — это своеобразная «рабочая память» ИИ. Всё, что агент видит и делает в рамках одной сессии, хранится в этом окне. Но у него есть лимит: когда информации становится слишком много, старые данные начинают вытесняться новыми. Это примерно как рабочий стол, на который помещается только определённое количество документов — если положить новый, какой-то старый упадёт на пол.

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

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

Именно так ведёт себя ИИ-агент на длинных проектах.

Что конкретно идёт не так

Мы протестировали, как агент на базе Claude справляется с большой задачей — созданием веб-приложения по типу claude.ai. И увидели два типичных сценария провала.

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

Второй сценарий: агент преждевременно объявляет победу. Это случается чуть позже, когда часть функций уже готова. Новый агент смотрит на проект, видит, что что-то работает, и решает: «Отлично, дело сделано!» Хотя на самом деле готово процентов тридцать.

Решение: два агента вместо одного

Мы нашли способ решить обе проблемы. Идея простая: разделить работу между двумя типами агентов.

Агент-инициализатор запускается только один раз, в самом начале проекта. Его задача — подготовить рабочее пространство так, чтобы все следующие агенты могли сразу приступить к делу, не тратя время на организационные вопросы.

Что конкретно он делает:

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

• Заводит файл для журнала прогресса. Это обычный текстовый файл (в нашем случае claude-progress.txt), куда агенты записывают, что они сделали за сессию. Что-то вроде бортового журнала или дневника проекта. Запись может выглядеть так: «Сессия 3: добавил форму авторизации, исправил баг с отображением аватарки, следующий шаг — подключить восстановление пароля». Следующий агент откроет этот файл и за минуту поймёт, на чём остановились.

• Делает первый коммит в git. Git — это система контроля версий, что-то вроде машины времени для кода. Каждый раз, когда вы делаете коммит, git сохраняет снимок всех файлов проекта в текущем состоянии. Если что-то сломается, можно откатиться к любому предыдущему снимку. Первый коммит — это точка отсчёта, «нулевой километр» проекта, от которого начинается вся история изменений.

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

Главное открытие было в том, как передавать информацию между сессиями. Мы завели специальный файл — что-то вроде журнала смены на заводе. Каждый агент в начале работы читает этот журнал и историю изменений в git, быстро понимает, что происходит, и продолжает с того места, где остановился предыдущий.

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

Как подготовить рабочее пространство для агента

Теперь разберём подробнее, что именно должен сделать агент-инициализатор и как настроить окружение так, чтобы все последующие агенты могли эффективно работать.

Список функций как карта проекта

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

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

Обратите внимание на поле passes: false. Изначально все функции помечены как невыполненные. Это создаёт для агента чёткую картину: вот полный список того, что нужно сделать, вот что уже готово, вот что ещё нет.

Важный момент: агентам-программистам разрешено только менять статус passes с false на true. Удалять или редактировать сами тесты запрещено. Мы используем довольно жёсткие формулировки в инструкциях: «Недопустимо удалять или редактировать тесты — это может привести к потере функциональности».

Почему именно JSON, а не обычный текстовый файл? Эксперименты показали, что модель реже «портит» структурированные JSON-файлы. С Markdown-файлами агент иногда начинал переписывать или удалять пункты, с JSON такое случается гораздо реже.

Маленькие шаги вместо больших прыжков

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

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

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

Поэтому мы просим агента в конце каждой сессии делать две вещи: фиксировать изменения в git с понятным описанием («Добавил кнопку нового чата, которая создаёт беседу и отображает её в сайдбаре») и записывать краткую сводку в файл прогресса.

Это даёт ещё один бонус: если агент что-то сломал, можно откатить изменения через git и вернуться к рабочей версии.

Тестирование как пользователь, а не как программист

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

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

Решение: дать агенту возможность тестировать приложение так же, как это делает человек. Для веб-приложений мы подключили инструменты автоматизации браузера (Puppeteer). Теперь агент буквально «открывает» браузер, кликает по кнопкам, вводит текст в поля и смотрит, что происходит на экране.

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

Конечно, и тут есть ограничения. Например, агент не может увидеть всплывающие окна браузера (те самые alert-окошки). Поэтому функции, которые на них завязаны, получаются чуть более «сырыми». Но в целом тестирование через браузер — огромный шаг вперёд.

С чего начинается каждая сессия

Теперь у нас есть все компоненты: список функций, файл прогресса, git-история, инструменты тестирования. Осталось научить агента правильно ими пользоваться.

Каждый агент-программист начинает работу с простого ритуала:

1. Смотрит, в какой папке находится

2. Читает журнал прогресса и историю git-коммитов, чтобы понять, что делали до него

3. Открывает список функций и выбирает следующую невыполненную задачу

4. Запускает приложение и проверяет, что базовые вещи работают

Последний пункт особенно важен. Прежде чем писать новый код, агент убеждается, что проект в рабочем состоянии. Если предыдущая сессия оставила что-то сломанным, агент сначала это чинит.

В случае с клоном claude.ai проверка выглядела так: запустить сервер, открыть приложение в браузере, создать новый чат, отправить сообщение, получить ответ. Если всё работает — можно приступать к новой функции. Если нет — сначала разбираемся с проблемой.

Вот как выглядит типичное начало сессии:

Такой подход экономит время и токены. Агенту не нужно каждый раз заново разбираться, как устроен проект и как его запустить — вся эта информация уже подготовлена.

Краткая шпаргалка: проблемы и решения

Что дальше

Описанный подход — не финальное решение, а скорее рабочий вариант, который уже даёт хорошие результаты. Но остаются открытые вопросы.

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

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