Объяснение сабагентов Claude Code: что это такое и когда их использовать.

Агенты — это не просто навыки в обличии чего-то другого

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

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

Четыре значения термина «агент»

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

1. Claude Code сам по себе является агентным окружением. Anthropic представляет его как агентного помощника для программирования: у него есть инструменты и цикл выполнения, он может планировать действия и выполнять их в несколько шагов без постоянных указаний. Он уже обладает агентными функциями до того, как вы что-либо настроите.
2. Подагенты — это пользовательские примитивы агентов внутри продукта. Когда разработчики говорят о создании агента в Claude Code, они почти всегда имеют в виду подагентов. Согласно официальной документации, это специализированные помощники для определённых типов задач, у каждого из которых есть отдельное окно контекста, собственный системный промпт, определённый доступ к инструментам и независимые права.

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

Claude Agent SDK представляет собой четвертый уровень. Он предоставляет те же инструменты и механизмы взаимодействия агентов, что используются в Claude Code, в виде библиотек на Python и TypeScript для команд, создающих собственные приложения-агенты вне интерфейса командной строки.

Остальная часть посвящена второму пункту — подагентам. С командами стоит разобраться отдельно позже; подробное объяснение одного подагента — правильный способ начать.

Почему существуют подагенты

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

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

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

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

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

Основной причиной является изоляция контекста, а также три дополнительные:

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

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

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

Создание первого пользовательского подагента

Технически подагент — это всего лишь документ в формате Markdown с заголовком YAML. Допускаются два места хранения:

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

~/.claude/agents/ в домашнем каталоге — для личных агентов, доступных в каждом проекте.

Фронтматер заслуживает внимания

Люди обычно просматривают YAML-фронтматер поверхностно, но Claude Code сохраняет его в памяти основной сессии, чтобы понять назначение каждого агента. По сути это краткое описание агента. Два поля являются обязательными, а несколько других — факультативными. Простой пример показывает, как они взаимосвязаны:

---
name: code-reviewer
description: Reviews code changes for quality, security, and best practices.
             Use proactively after any significant code change.
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, read the changed files and provide
specific, actionable feedback on code quality, security, and best practices.
Focus on what matters. Don't restate what the code does — say what's wrong
or good about it. Flag security issues first, then logic problems, then style.

Рассмотрим поля по отдельности:

• name — уникальный идентификатор, написанный строчными буквами с использованием только дефисов. Он отображается в логах, а Claude использует его для внутреннего обозначения агента.
• description имеет наибольшее значение. Claude обращается к нему, чтобы определить, относится ли задача к этому агенту; поэтому в нем следует описать его функции: какую работу выполняет агент и в каких случаях его следует вызывать. Указание «использовать проактивно» является официальным сигналом для Claude, предписывающим активировать агента без ожидания прямой просьбы. Исключите эту фразу, если агент должен отвечать только при прямом запросе.

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

model направляет агента к конкретной модели: sonnet, opus, haiku или полному идентификатору вроде claude-opus-4-6. Без этого параметра агент использует режим inherit, то есть ту же модель, что и в основной сессии.

Все элементы, находящиеся в разделе frontmatter, становятся системным промптом агента. Этот промпт вместе с рабочей директорией — всё, что агент получает от основной сессии.

Полный список необязательных полей показывает, сколько ещё можно настроить: permissionMode, maxTurns, skills, mcpServers, effort, memory, hooks, disallowedTools, color и другие.

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

Куда сохранять файл

Сохраните пример как .claude/agents/code-reviewer.md в проекте. Результат будет выглядеть следующим образом:

your-project/
├── .claude/
│   ├── agents/
│   │   └── code-reviewer.md          ← your new agent file
│   ├── skills/
│   └── rules/
├── src/
├── tests/
├── README.md
└── package.json

После сохранения Claude обнаруживает агента. Попросите его проверить изменения в коде, и он самостоятельно передаст задачу code-reviewer, исходя из того, насколько хорошо запрос соответствует описанию. Для личного агента, работающего во всех проектах, переместите файл в ~/.claude/agents/code-reviewer.md. Формат и содержимое остаются неизменными; меняется только местоположение.

Агенты против навыков

Почему их часто путают

Три сходства объясняют большинство путаницы:

1. Оба настраиваются с помощью обычной структуры папок внутри .claude/skills или .claude/agents.
2. Оба используют frontmatter, причем описание является самым важным параметром в обоих случаях.
3. Оба представляют собой наборы инструкций, другими словами — подсказок. Навык и агент могут содержать совершенно одинаковые слова.

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

Где происходит работа

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

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

Параметры настройки

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

Одна задача, два решения

Возьмём пример необходимости последовательного применения стандартов код-ревью в вашей команде.

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

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

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

Эффективные практики работы

Рассматривайте описание как интерфейс маршрутизации

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

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

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

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

Целенаправленно ограничивайте инструменты

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

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

Ограничение набора инструментов способствует повышению безопасности и ясности. Узкий набор инструментов делает поведение предсказуемым, и когда агент терпит неудачу или возвращает необычные результаты, короткий список возможных инструментов ускоряет диагностику. Это также делает возможные способы сбоев ограниченными и понятными. Поле disallowedTools позволяет агенту наследовать инструменты основной сессии, а затем исключить определенные из них, что подходит для сценариев вроде «всё, кроме Bash» или «всё, кроме функции Write».

Предоставьте каждому агенту одну задачу

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

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

Используйте поле «модель» для контроля затрат

Люди, которые ещё не были удивлены своим счётом за использование, обычно больше всего игнорируют это поле. Установка параметра model: haiku у лёгких агентов значительно снижает затраты, когда в одной сессии запускается несколько агентов. Использование параметра model: opus у агента, который должен длительно обрабатывать большой объём информации, оправдывает его стоимость. Оставление значения по умолчанию inherit означает, что каждый агент будет работать с тем же моделем, что и основная сессия, часто самым мощным моделем, причём это будет применяться одинаково к задачам, которые его не требуют.

Что выбрала сообщество

Каталог подагентов VoltAgent включает более ста специализированных подагентов — от экспертов по языкам до специалистов по безопасности, отлаживающих программы, помощников с инфраструктурой и оркестраторов. Ещё один набор подобных агентов находится в репозитории Everything Claude Code. Лишь немногим понадобится даже пятая часть из них, поэтому количество здесь не является главным фактором; важна структура. Каждый элемент этих коллекций имеет узкую специализацию: будь то специалист по TypeScript, эксперт по SQL, оператор Kubernetes или аудитор безопасности. Ни один из них не пытается охватить более одной области. Таков консенсус после более чем года практического использования: множество специализированных агентов превосходят одного универсального.

Kраткий обзор команд агентов

Стоит ознакомиться с командами агентов, но это отдельная функция от подагентов.

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

Команды агентов — это независимые сессии Claude Code, которые взаимодействуют друг с другом через общий список задач и прямую переписку. У каждого участника команды есть собственное окно контекста и состояние сессии; он может поручать задачи другим, а также их принимать.

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

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

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

Когда агент — неподходящий инструмент

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

Это применимо и к конкретным ситуациям, когда подагент создает лишние трудности и не приносит никакой пользы:

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

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

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

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

Краткая версия

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

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

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