Решил написать вводный обзор функциисубагентов в Claude Code (далее — сокращаем до общепринятого СС). Субагенты — базовая технология, которую используют во многих современных методиках разработки программного обеспечения ИИ агентами. Удивительно, но до сих пор (на сентябрь 2025) эта фича СС остаётся эксклюзивной среди фронтирных агентов — Gemini CLI и Codex CLI так и не получили субагентов. Почему это им бы не помешало — обсудим тоже.

История вопроса уходит к первому публичному релизу СС. В ту пору субагенты были «обычным» инструментом Task — так он указывался в интерфейсе. В исходном коде они сразу были названы AgentTool. Желающие убедиться в этом могут погуглить по github в поисках репозитория ANON KODE, где лежит утечка исходного кода СС примерно от апреля 2025 — ссылку не даю на всякий случай. Давайте для ясности далее будем называть его Задачей/Task — именно так, не субагентом или агентом, почему — объясню далее.

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

Простой практический пример с картинками - оркестратор и задача

Давайте рассмотрим простой пример с картинками - запустили СС, попросили промптом выполнить некую задачу, и СС запускает инструмент Task (1).

Можно увидеть что в ui действия задачи с инструментами отражаются, далее инструмент завершает работу, и отдаёт результат оркестратору, и оркестратор распоряжается ими в своём контексте. В нашем случае - сообщает пользователю (2).

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

"Под капотом" действия немного более многословны - проанализировав сессию, можно увидеть запуск инструмента задачи, увидеть промпт от оркестратора, который сформулирован на английском языке (3). Смотрим сессию приложением Claudia, которое с недавнего времени называется opcode.sh

Следом начинается лог работы задачи, запуск инструментов (4).  Посмотреть подробнее можно, перейдя в режим просмотра деталей - он включается сочетанием клавиш Ctrl+R.

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

СС может по своей инициативе запускать задачи через инструмент Task, обычно это будет поиск по кодовой базе, анализ большой группы файлов или прочие read only задачи.

Чтобы "намекнуть" CC использовать инструмент Task для ваших задач нужно в промпте так и сказать - "используй инструмент agentTool для выполнения задачи ...".

Ещё один неочевидный момент в СС: несколько инструментов задачи могут работать параллельно, одновременно выполняя разные задачи. То есть если у вас есть задача поиска по всему проекту - вы инструктируете оркестратор разбить поиск, например, по подсистемам (api, worker, dashboard, ...). Далее применяем "магическую фразу": "ВАЖНО: обязательно запусти эти задачи поиска параллельно, сделав вызов нескольких инструментов agentTool для каждой задачи В ОДНОМ СВОЕМ СООБЩЕНИИ". Вы увидите, как оркестратор сделает 5-7 одновременно работающих экземпляров Task.

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

Оркестратор вызывает инструмент Task, передаёт ему "задание" (промпт). Далее задача работает в отдельном контексте самостоятельно и возвращает результат оркестратору. В ходе работы задачи в интерфейсе СС мы видим некие сообщения о происходящих событиях, и все это пишется в json в сессию. Если есть желание почитать подробнее - можно использовать инструменты типа Claudia (нынче - opcode.sh).

Что нам дал инструмент "задача" для работы в СС? Уже довольно немало - за счёт важного свойства, самостоятельного отдельного контекста задачи. При старте Task происходит создание новой цепочки работы системы с моделью. Это свойство позволяет делать длинные сессии работы оркестратора, промптом заставляя вести основную работу внутри задач. Можно не "засорять" контекст оркестратор вызовом инструментов, оставляя в зоне его ответственности только координацию основной задачи. В результате, последовательные линейные воркфлоу даже из значительного количества шагов выполняются в целом уже неплохо. Главное не допускать исчерпания контекста оркестратора! Задачами уже можно доводить длительность сессии оркестратора до десятков минут, а самых удачных случаях можно "выжимать" часы! Это важно, потому что длительность сеанса в определённой степени отражает количество полезной работы.

Лайвхак: сам СС регулярно использует свой "задачник" (todos) для фиксации плана работы. Эффективно будет промптить агента принудительно просить фиксировать план работы в todo. Это позволит не отклоняться от плана даже при длительных воркфлоу. В последних версиях у пользователя появились даже пара инструментов для работы с этим "задачником" - команда /todos для просмотра текущего списка задач, и Ctrl+T для вывода списка задач в зоне индикатора текущей задачи над строкой ввода.

В чём подводные камни конструкции Task? Их несколько:

• управление работой инструмента "задача" осуществляется целиком и полностью оркестратором: при накоплении у оркестратора в контексте значительного количества информации происходит деградация внимания модели, и оркестратор уже не может внимательно и с требуемыми деталями прописывать задачи;

• задача наследовала от родительского процесса инструменты, возможностей настройки нет; в результате аналитические или поисковые задачи работали в контексте с абсолютно не нужным им условным менеджером БД postgres;

• работа всей системы (оркестратора и задач) велась с единственной выбранной моделью

☑️ Резюмируем проблемы: точность промпта, настройка инструментов, модель.

Что мы могли видеть в реальной работе, в чем проявляются симптомы проблем?

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

• Убедить оркестратора писать длинные подробные промпты почти невозможно: они выходят краткие и без требуемых деталей.

• Оркестратор может заниматься "самодеятельностью" и добавлять в промпт чего то "от себя" в зависимости от полученного контекста текущего этапа. Например, задача поиска информации могла потом чего то этой информацией обновить, если оркестратору показалось что это актуально.

? Субагенты

Так мы жили до версии 1.0.60, в которой появились "Sub-Agents" - субагенты. Добавлены принципиально важные дополнения к функциональности:

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

• агенты определяются в специальной папке "agents" конфигурации: для отдельного проекта, или на уровне пользователя - для всех проектов;

• указываем модель, которая будет использована для субагента: opus/sonnet/haiku

• указываем набор инструментов, доступный субагенту

• для визуальной индикации запуска субагента в UI можно указать цвет

Чем принципиально важны нововведения?

Может показаться, что важность субагентов происходит от расширения контекста — но это не совсем так. Действительно, субагент стартует с «чистым» контекстом, что объективно расширяет возможности системы.

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

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

Далее — указание модели. Для целого класса задач это критически важно! Теперь стало возможным задачи планирования и анализа проводить «более умной» моделью opus (те, у кого она доступна на тарифе — это планы max), а непосредственное написание кода — дефолтным Sonnet. Простые задачи вроде работы с документацией или проставление тэгов в jsDoc можно делегировать быстрому haiku. Удобно, и дополнительно повышает качество работы!

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

В результате мы получили возможность очень точной настройки процессов, построенных на субагентах. Качество работы всей системы заметно повысилось, особенно при выполнении сложных workflow с многими этапами.

▶️ Как происходит выбор агента? Когда СС необходимо запустить субагента, система смотрит список доступных ей агентов. В зависимости от контекста команды запуска, по описаниям субагентов выбирается нужный. Стартуется субагент с указанием нужной модели и инструментов, ему загружается его системный промпт, а также задание оркестратора, и субагент приступает к работе. Деталь реализации: если отдельные настройки СС могут быть обновлены «налету», то описания субагентов загружаются только при старте. Следовательно, после добавления новых субагентов или обновления описаний требуется перезапуск СС.

▶️ Чем «субагент» отличается от «задачи»? Задача не кастомизируется — нет отдельного промпта, только промпт от оркестратора. Нет выбора модели или инструментов. Технически «под капотом» это один и тот же инструмент agentTool, но возможности кастомизации субагентов выводят их на новый уровень, делая заметной инновацией.

▶️ Какие остались ограничения у субагентов СС? Прежде всего это «глубина» рекурсии вызова субагентов — всего два элемента. То есть работает схема «оркестратор» — «субагент», но нельзя делать вызов «Оркестратор» — «субагент» — «субагент». То есть, если вы в вашем воркфлоу вызовете другой воркфлоу на субагентах, это не сработает, субагенты другого воркфлоу не смогут запуститься (для субагента уже нет инструмента agentTool, через который запускаются субагенты). Да, можно использовать обходной путь: запуск из субагента внешнего процесса Claude Code SDK, в котором внутри снова будет связка «оркестратор» — «субагент». Поэтому для сильно желающих такое дизайн‑решение не будет таким уж неодолимым ограничением!

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

Описание агента делается в markdown файле c метаданными в начале файла YAML frontmatter:

---
name: research-code
description: 'Агент для поиска по коду и тестам проекта (Code/test search/research agent)'
model: haiku
color: blue
---

Твоя основная задача: проводить эффективный поиск по файлам проекта. Ты должен внимательно изучить предоставленные сведения о структуре проекта и использовать их для выполнения задания.
 
Структура проекта:
* src/ - папка исходного кода 
  * src/sybsystem/ - подсистема ...
* data/ - папка с данными и БД
* logs/ - папка с логами, тут не ищем, это служебные данные
* SETUP.md - файл с инструкциями по развёртыванию окружения разработки
* playwright.config.ts - настройка playwright для тестов, проекты: e2e, api.
...  

структура тестов
* tests/ - папка со всеми тестами
  * tests/unit - юнит тесты
  ...  


Дополнительно к формированию резюме по выполненной работе ты должен сформировать файл markdown с подробным детальным отчётом о выполненной работе в папке .tasks/ в корне системы, используй уникальное имя файла в формате {YYYY-MM-DD, имя_файла_отчёта}.md

Некоторые комментарии к промпту агента:

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

• я использую принцип подготовки агентов под «класс» задач — некий набор действий, для которого стоит сформировать отдельный контекст; например, для агента по поиску в кодовой базе подробно рассказываем о структуре проекта; агенту для написания кода неплохо было бы рассказать о стандартах кодирования проекта (и есть небольшой шанс избежать тайпскриптовых `as any`); агенту по запуску тестов все таки следует объяснить, что треть падающих тестов — это не «production class quality», и все падающие тесты придётся таки доделать, причем без «срезания углов»;

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

• если в проекте ведётся меморибанк — контекст агента будет идеальным местом для интеграции блоков меморибанка внутрь контекста агента. Ознакомиться с вводной информацией про концепцию меморибанков можно в нашей статье.

• использовать файловую систему для обмена информацией между агентами в маркдаун файлах: да, это один из простых, но очень мощных механизмов; промпты не позволяют передать детали работы одного агента другому — эффект «глухого» телефона при двойном пересказе плюс «нежелание» оркестратора передавать детали, или «невнимательность» на фоне большого контекста; и, наконец — это же unix way! классика

• Использовали модель haiku, указав алиас общего семейства моделей, без конкретной версии — так можно, что сохранит актуальность агента при обновлении версий

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

Агентные процессы: наибольшую пользу субагенты приносят в рамках агентных процессов, также известных как агентные воркфлоу/WFs. Это прописанные естественным языком многоэтапные последовательности действий/инструкций, которые выполняет ИИ агент. Именно такие процессы нужны для реализации похода, известного как SDD, разработка основанная на спецификациях. Воркфлоу может прорабатывать спецификации фич приложения, делать из спецификаций планы реализации и прорабатывать интеграцию в код приложения, генерировать код и тесты, работать над качеством, запуская тесты и исправляя недочёты, исправлять выявленные issues в системе. Подходы к созданию агентных процессов — тема для отдельной статьи.

? Резюме

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

Похожие возможности пока реализованы только в некоторых открытых проектах (RooCode, SST OpenCode), но до сих пор субагентов нет в Gemini CLI или Codex CLI.

Казалось бы, зачем Gemini при контексте 1m токенов нужны субагенты? Ответ очевиден: не размером контекста единым. Крайне важна возможность фокусного определения задачи, модели и инструмента. Совокупность целевого контекста, целевого набора инструментов и подходящей модели делают субагента чрезвычайно мощным и полезным инструментом, «кирпичиком» в построении мощных воркфлоу. Такая возможность была бы очень полезна для любых систем, вне зависимости от размера контекстов доступных в них моделей. Именно поэтому субагенты, например — в топе запросов от сообщества к разработчикам Сodex cli.

Субагенты — очень мощный и «глубокий» механизм, который делает Claude Code по настоящему универсальным и многогранным инструментом. Надеюсь, он пригодится и вам в выстраивании ваших интересных и эффективных систем!

Желающих обсуждать практику работы в агентных системах Ai‑driven разработки приглашаю к себе в канал в Telegram.