Эффективные обвязки для долгосрочных агентов

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

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

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

Проблема долгосрочных агентов

Claude Agent SDK — мощная универсальная обвязка для агентов, хорошо справляющаяся с написанием кода и другими задачами, требующими использования инструментов для сбора контекста, планирования и выполнения. В SDK есть механизмы управления контекстом, в том числе компакция, которая позволяет агенту работать над задачей, не исчерпывая контекстное окно. Теоретически при такой конфигурации агент должен быть способен выполнять полезную работу сколь угодно долго.

Однако компакции недостаточно. Даже фронтирная модель для написания кода, такая как Opus 4.5, запущенная в Claude Agent SDK в цикле по нескольким контекстным окнам, не справится с созданием production-качества веб-приложения, если ей дать только высокоуровневый промпт вроде «сделай клон claude.ai».

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

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

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

В ходе внутренних экспериментов мы решили эти проблемы с помощью двухкомпонентного решения:

Агент-инициализатор: самая первая сессия агента использует специализированный промпт, который просит модель настроить начальную среду: скрипт init.sh, файл claude-progress.txt с журналом действий агентов и начальный git-коммит, показывающий добавленные файлы.
Агент-кодировщик: каждая последующая сессия просит модель делать инкрементальный прогресс, а затем оставлять структурированные обновления.1

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

Управление средой

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

Список фич

Чтобы решить проблему попытки агента реализовать приложение за один подход или преждевременного объявления проекта завершённым, мы попросили агент-инициализатор написать исчерпывающий файл с требованиями к фичам, расширяющий исходный промпт пользователя. В примере с клоном claude.ai это означало более 200 фич, например: «пользователь может открыть новый чат, ввести запрос, нажать Enter и увидеть ответ AI». Все эти фичи изначально помечались как «не пройденные», чтобы у последующих агентов-кодировщиков был чёткий ориентир полной функциональности.

{
    "category": "functional",
    "description": "New chat button creates a fresh conversation",
    "steps": [
      "Navigate to main interface",
      "Click the 'New Chat' button",
      "Verify a new conversation is created",
      "Check that chat area shows welcome state",
      "Verify conversation appears in sidebar"
    ],
    "passes": false
  }

Мы инструктируем агентов-кодировщиков редактировать этот файл только путём изменения значения поля passes, используя категоричные формулировки вроде «недопустимо удалять или редактировать тесты, поскольку это может привести к пропуску функциональности или появлению багов». После ряда экспериментов мы остановились на JSON для этого файла, поскольку модель реже неуместно изменяет или перезаписывает JSON-файлы по сравнению с Markdown-файлами.

Инкрементальный прогресс

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

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

Эти подходы также повысили эффективность, устранив необходимость агента угадывать, что произошло, и тратить время на восстановление работоспособности базового приложения.

Тестирование

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

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

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

Некоторые проблемы остаются — например, ограничения зрения Claude и инструментов браузерной автоматизации затрудняют обнаружение всех видов багов. Так, Claude не видит нативные браузерные модальные окна alert через Puppeteer MCP, и фичи, опирающиеся на эти модальные окна, как правило, содержали больше багов.

Вхождение в курс дела

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

Выполнить pwd, чтобы увидеть рабочую директорию. Редактировать можно только файлы в этой директории.
Прочитать git-логи и файлы прогресса, чтобы войти в курс последних изменений.
Прочитать файл со списком фич и выбрать наиболее приоритетную незавершённую фичу для работы.

Этот подход экономит Claude несколько токенов в каждой сессии, поскольку ему не нужно разбираться, как тестировать код. Также полезно попросить агент-инициализатор написать скрипт init.sh, который запускает dev-сервер, а затем проводит базовый end-to-end тест перед реализацией новой фичи.

В случае клона claude.ai это означало, что агент всегда запускал локальный dev-сервер и использовал Puppeteer MCP для открытия нового чата, отправки сообщения и получения ответа. Это позволяло Claude быстро определить, не осталось ли приложение в нерабочем состоянии, и немедленно исправить существующие баги. Если бы агент вместо этого сразу начал реализовывать новую фичу, он, скорее всего, усугубил бы проблему.

С учётом всего этого типичная сессия начинается со следующих сообщений ассистента:

[Assistant] I'll start by getting my bearings and understanding the current state of the project.
[Tool Use] <bash - pwd>
[Tool Use] <read - claude-progress.txt>
[Tool Use] <read - feature_list.json>
[Assistant] Let me check the git log to see recent work.
[Tool Use] <bash - git log --oneline -20>
[Assistant] Now let me check if there's an init.sh script to restart the servers.
<Starts the development server>
[Assistant] Excellent! Now let me navigate to the application and verify that some fundamental features are still working.
<Tests basic functionality>
[Assistant] Based on my verification testing, I can see that the fundamental functionality is working well. The core chat features, theme switching, conversation loading, and error handling are all functioning correctly. Now let me review the tests.json file more comprehensively to understand what needs to be implemented next.
<Starts work on a new feature>

Паттерны ошибок агентов и решения

Дальнейшая работа

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

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

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

Благодарности

Автор: Justin Young. Особая благодарность David Hershey, Prithvi Rajasakeran, Jeremy Hadfield, Naia Bouscal, Michael Tingley, Jesse Mu, Jake Eaton, Marius Buleandara, Maggie Vo, Pedram Navid, Nadine Yasser и Alex Notov за их вклад.

Эта работа отражает совместные усилия нескольких команд Anthropic, благодаря которым Claude смог безопасно выполнять долгосрочную автономную разработку ПО, — особенно команд code RL и Claude Code. Заинтересованные кандидаты, желающие внести вклад, могут подать заявку на anthropic.com/careers.

Сноски

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