Проблемы агентной разработки

Знакома ли вам ситуация, когда никак не получается найти нужный чат в истории Cursor, Codex или Claude Code? Или когда чат настолько вырос, что запустилось сжатие контекста, а важные факты и промежуточные результаты потерялись?

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

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

Это применимо даже в том случае, если работа с кодом реально выполняется субагентами, а в основном чате остаётся только координатор. Часто возникают ситуации, когда в рамках одного чата нужно проработать разные аспекты задачи. В результате агент поднимает релевантные фрагменты кода, которые вытесняют исходный контекст. Можно под каждый вопрос заводить отдельный чат и добавлять туда нужную информацию. Но в реальности редко получается придерживаться такого правила. Намного удобнее иметь возможность сослаться на конкретную задачу по номеру или описанию, чтобы агент сам нашёл нужную информацию в её артефактах.

Следующий уровень зрелости

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

Агенты очень хорошо работают с файлами: они прекрасно ориентируются в коде, зависимостях, правилах проекта (AGENTS.md) и навыках (skills/). Нативные инструменты любой среды агентной разработки заточены на эффективный поиск информации и другие операции с файлами. Так почему бы не использовать файлы и для хранения контекста задач?

Выделение каждой задачи как отдельной сущности позволило перейти на следующий уровень зрелости агентной разработки. Это task-first подход: сама задача становится инструментом непрерывного контекста, долговременной памяти и надёжной передачи состояния между человеком и командой агентов.

Task-first подход переносит центр тяжести из переписки в рабочую папку задачи. Задача становится не сообщением в чате, а изолированным каталогом с файлами: исходным запросом, планом, контрактом, текущим статусом, используемыми источниками, логом выполнения, подтверждением прохождения gate и итоговыми результатами. Чат остаётся транспортом, через который пользователь запускает работу и получает ответ, но источник правды живёт в файловых артефактах.

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

Задача как рабочая папка

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

Структура задачи может выглядеть так:

tasks/231-amazing-feature/
  attachments/
  task.md
  plan.md
  task_contract.json
  status.json
  trace.md
  sources.md
  findings.md

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

plan.md описывает порядок выполнения. Он нужен для того, чтобы агент мог восстановить намерение: что уже сделано, что осталось, какие шаги ожидаются.

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

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

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

sources.md — источники информации, найденные в ходе работы над задачей. Например, если агент провёл исследование, конкретные адреса, даты, цены, контакты, найденные варианты и ссылки должны остаться в исходном виде в файлах.

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

Чтобы агенту не приходилось читать исходные файлы всех задач, в корневом каталоге с задачами есть индекс tasks/INDEX.md со списком задач, их статусами и другой краткой метаинформацией. Это ускоряет поиск предыдущих релевантных задач, которые позволяют сформировать полный контекст для новой задачи.

Верхнеуровневая структура задач и зависимости

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

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

tasks/INDEX.md помогает быстро найти активные и завершённые задачи.
Это простая, но важная часть памяти: без индекса каталог задач быстро превращается в архив, с которым невозможно эффективно работать.

data/projects/ хранит долговременные записи по инициативам, которые состоят из многих задач и решений.
Например, если серия запросов развивает один продукт или исследовательское направление, проектная запись должна аккумулировать ключевую информацию из отдельных каталогов задач. Там уместны устойчивые решения, долгосрочные цели, принятые архитектурные направления и связи между задачами.

Модель «координатор — субагенты»

Task-first процесс хорошо сочетается с моделью «координатор — субагенты» (parent-child). Основной агент остаётся координатором: создаёт артефакты задачи, запускает субагентов, читает status.json и trace.md, отправляет результат пользователю. Субагенты делают основную работу: исследуют код, пишут файлы, запускают проверки, обновляют артефакты и подготавливают подтверждающие итоговые материалы.

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

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

Управление задачами с разных поверхностей

Возможность запустить задачу через единый навык помогает инициировать задачи с любой поверхности, а не только из интерфейса IDE или CLI агентной среды: Cursor, Codex, Claude Code. Минималистичные требования к контексту облегчают работу с задачами через мессенджеры.

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

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

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

Инструменты саморазвития, правила и навыки

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

Ключевые правила (AGENTS.md):

• почти каждый нетривиальный запрос получает отдельный каталог tasks/...;

• task.md и plan.md обязательны;

• trace, status, findings, sources и подтверждения прохождения проверок сохраняются рядом с задачей;

• каталог задачи является передаточным контрактом между координатором и дочерними агентами;

• для изменений в коде или поведении работающего сервиса нужна проверка реального сервиса, а не только заглушки;

• после инцидента агент должен разобрать причину и риск повторения;

• если меры предотвращения проблем в будущем очевидные и низкорисковые, уточняются правила и навыки;

• если такие меры меняют поведение, совместимость или права доступа, агент спрашивает подтверждение у пользователя;

• все изменения отражаются в документации как для агентов (AGENTS.md), так и для людей (README.md).

Навыки (skills/) превращают повторяемые операции в проверяемые процедуры и позволяют экономить контекст. Например:

• task-creator создаёт или переименовывает задачу и обновляет tasks/INDEX.md;

• task-runner запускает субагента, ведёт .runner, status и trace;

• project-organizer выносит долгоживущие решения в data/projects/;

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

Организация рабочего пространства и доступов агента

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

В моём случае агент имеет доступ сразу к нескольким проектам: часть из них являются компонентами сложного сервиса, а часть — независимыми сервисами. Каталог task-agent/ размещается в корне каталога projects/, содержащего все исходники проектов, к которым я хочу предоставить доступ агенту. Именно отсюда запускается агентный процесс координатора; здесь лежат правила проекта, навыки, документация и дерево задач.

Крайне важно, что широкий доступ не означает отсутствие границ. Чтобы не получилась ещё одна история «ИИ удалил базу на проде», task-first модель задаёт границы, опираясь на условия задачи:

• что именно попросил пользователь;

• какие каталоги относятся к задаче;

• какие действия запрещены;

• какие проверки обязательны;

• какие артефакты должны остаться после выполнения.

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

Как это реализовано технически?

Первый слой — правила проекта. Они лежат в AGENTS.md и docs/task-execution.md. Там зафиксировано, что удалённые запросы могут выполнять ограниченную работу в соседних проектах под projects/, если это явно относится к задаче, но не могут повреждать несвязанные репозитории или выполнять деструктивные действия, выходящие за рамки задачи. Это важная граница: доступ шире одного репозитория разрешён не вообще, а только в рамках конкретной задачи.

Практически это означает такую формулу:

можно: изменить projects/<target-project>, если задача явно про него
нельзя: трогать соседние проекты просто потому, что они доступны
нельзя: выполнять широкие деструктивные действия без прямого и узкого запроса

Второй слой — навык task-runner. Именно этот навык превращает правило в рабочий запуск субагента. Для обычной задачи можно запустить субагента так:

.venv/bin/python skills/task-runner/scripts/task_runner.py start \
  tasks/NNN-some-task \
  --runner codex

Но если задаче нужен доступ к соседним проектам, режим доступа нужно указать явно:

.venv/bin/python skills/task-runner/scripts/task_runner.py start \
  tasks/NNN-some-task \
  --runner codex \
  --sandbox-mode danger-full-access

Тут важны две детали.

Во-первых, при sandbox-mode=danger-full-access, Codex запускается с рабочим каталогом projects/, а не только из projects/task-agent. Субагент видит задачу через абсолютный путь к каталогу задачи, но его рабочий каталог достаточно широкий, чтобы открыть и изменить нужный соседний проект:

task artifact:
projects/task-agent/tasks/NNN-some-task/
target project:
projects/<sibling-project>/
child workdir under full access:
projects/

Во-вторых, -C /opt/projects задаёт широкий рабочий каталог. Это нужно, чтобы относительные операции, git-команды, проверки запуска сервиса и переходы между соседними репозиториями происходили внутри общего дерева проектов, а не изнутри одной рабочей копии.

Если задачу нужно выполнить через мультиагентный конвейер:

.venv/bin/python skills/task-runner/scripts/task_runner.py start \
  tasks/NNN-some-task \
--runner codex \
  --workflow multi-agent-dev

Для Codex этот конвейер по умолчанию получает danger-full-access. В skills/task-runner/scripts/codex_multi_agent.py это дополнительно уточняется по ролям. Субагенты с ролями Разработчик и Ревьюер кода при danger-full-access запускаются из projects/, а не из корня task-agent/. Там же перед запуском вложенных Codex-процессов чистится унаследованный контекст Codex, чтобы вложенный агент действительно получил переданный режим доступа, а не унаследовал его от оркестратора.

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

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

Практический эффект

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

Триггером для решения был мой опыт работы с OpenClaw. Я понял, что агент может эффективно дописывать себя сам. Однако я пошёл не по пути развития OpenClaw, а взял проверенный Codex с подпиской ChatGPT и построил поверх него инфраструктуру для работы с задачами. Фактически Codex построил эту инфраструктуру сам, опираясь на описанные в этой статье базовые принципы. Эффекты такого подхода оказались очень заметными.

Первый эффект — возобновляемость. Агент читает task.md, plan.md, status.json, trace.md и понимает, где находится работа.

Второй эффект — проверяемость. trace, status, findings, sources, скриншоты, логи и результаты тестов не зависят от памяти чата. Агент видит не только текущее состояние проекта, но и путь к нему.

Третий эффект — универсальность. Можно ставить агенту не только задачи на разработку. Он может, например, провести исследование, подготовить презентацию, собрать документы на поездку, даже осознанно поздравить знакомого через мессенджер, предварительно собрав контекст переписки с ним. Разные типы задач могут использовать разные навыки, но общий принцип остаётся: каталог задачи является первоисточником.

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

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

Шаблон для переиспользования

На github выложен шаблон рабочего пространства для работы с задачами с базовыми правилами и навыками.