Субагенты Claude Code: как они работают и когда нужны

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

Субагенты Claude Code за 20 секунд

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

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

Что такое субагенты Claude Code на практике

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

Именно следующий момент чаще всего объясняют неверно. Субагент начинает с чистого листа. Он не видит историю вашего диалога, уже прочитанные Claude файлы или ранее запущенные skills. Claude составляет короткое сообщение с сутью поручения, после чего субагент работает только со своим системным промптом и базовыми сведениями об окружении — например, с текущим рабочим каталогом, — но без полного системного промпта Claude Code. По завершении обратно приходит лишь его резюме.

У такой изоляции есть и преимущество, и цена — именно этот компромисс определяет все остальное:

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

Из чего состоит файл субагента

Пользовательский субагент описывается в Markdown-файле с YAML frontmatter. Frontmatter отвечает за конфигурацию, а Markdown-текст становится системным промптом субагента. Обязательных полей всего два: name и description.

---
name: code-reviewer
description: Reviews code for quality and best practices. Use immediately after writing or modifying code.
tools: Read, Glob, Grep
model: sonnet
---

You are a senior code reviewer. When invoked, run git diff to see recent
changes, focus on modified files, and review for clarity, naming, error
handling, exposed secrets, input validation, and test coverage. Group your
feedback by priority: critical issues, warnings, then suggestions.

Это полноценный рабочий субагент. Поле description — не декоративная подпись: по нему Claude решает, когда делегировать задачу. Формулировка «проверяет код; запускать сразу после написания или изменения» вовремя подключит субагента, тогда как расплывчатое «помощник по коду» почти наверняка оставит его без дела. Относитесь к описанию как к вакансии для узкого специалиста.

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

Где хранятся субагенты и чья конфигурация важнее

Один и тот же файл субагента ведет себя по-разному в зависимости от расположения: путь определяет, кому он доступен и какая версия победит при совпадении имен.

Если имена двух субагентов совпадают, выигрывает расположение с более высоким приоритетом: управляемая конфигурация выше проектной, а проектная — выше пользовательской. Claude Code ищет проектных субагентов, поднимаясь по дереву от рабочего каталога; начиная с v2.1.178 при совпадении имен выбирается определение, расположенное ближе всего к этому каталогу. Есть и вариант только на время сессии: при запуске Claude Code можно передать субагентов в виде JSON через флаг --agents. Они будут доступны до конца сессии, не сохраняясь на диск, что удобно для сценариев автоматизации и быстрых проверок.

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

Модель и инструменты: два главных рычага

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

Модель. Поле model принимает псевдоним (sonnet, opus, haiku, fable), полный идентификатор модели вроде claude-opus-4-8 или значение inherit. Если поле не указано, по умолчанию используется inherit: субагент работает на той же модели, что и основной диалог. Здесь скрыт важный способ контролировать бюджет. Для задачи «найти по коду все совпадения и кратко изложить результат» передовая модель не нужна. Укажите model: haiku — и рутинная часть будет выполняться более дешевой и быстрой моделью, пока в основной сессии Opus останется для сложных рассуждений.

Инструменты. По умолчанию субагент наследует все внутренние и MCP-инструменты основного диалога. Ограничить их можно одним из двух полей: tools задает разрешающий список, а disallowedTools — запрещающий, то есть оставляет доступным все, кроме перечисленного. Например, исследовательскому субагенту, который не должен менять файлы, можно назначить tools: Read, Grep, Glob, Bash — тогда редактирование будет для него физически недоступно. Это не просто способ навести порядок, а реальная граница безопасности: субагент с доступом только для чтения не сможет случайно переписать проверяемый файл.

Полезно знать и еще об одной настройке: isolation: worktree запускает субагента во временном git worktree — изолированной копии репозитория, которая автоматически удаляется, если субагент ничего не изменил. Такой режим подходит для рискованных экспериментов, которые не должны затронуть основное рабочее дерево.

Когда использовать субагента, а когда обойтись без него

Именно этого раздела обычно не хватает в подборках конфигураций на GitHub, хотя на практике он лучше всего экономит время и деньги. Субагент не бесплатен, поэтому вопрос должен звучать не «можно ли здесь применить субагента?», а «окупит ли изоляция свои затраты?».

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

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

Субагент, skill, fork или agent team: в чем разница

В Claude Code теперь есть четыре способа организовать работу, и их легко перепутать. Главное различие между ними — контекст.

Чаще всего путают skill и субагент, поскольку оба варианта выглядят как «сохраненная экспертиза». Skill — это повторно используемые инструкции, которые выполняются в контексте основного диалога и потому видят всю текущую работу. Субагент устроен наоборот: он намеренно изолирован и знает лишь то, что передано ему вместе с задачей. Если Claude должен применять редакционные правила или внутренние стандарты, продолжая работать вместе с вами, нужен skill. Если шумное исследование следует провести отдельно и вернуть только результат, нужен субагент.

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

Расширенные возможности и их ограничения

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

Вложенность. Начиная с Claude Code v2.1.172 субагент может запускать собственных субагентов. Например, субагент-рецензент способен назначить отдельного проверяющего для каждого замечания; весь промежуточный поток останется внутри, а вам вернется только резюме верхнего уровня. Глубина фиксирована: максимум пять уровней, изменить этот предел нельзя. Субагент на пятом уровне уже не получает инструмент Agent и потому не может продолжить цепочку. Такое ограничение оправданно: глубокое ветвление легко превращается в целый рой и резко увеличивает расход токенов. Считайте глубину бюджетом, а не целью.

Память. Добавьте memory: project (либо user или local), и субагент получит постоянный каталог памяти, который сможет читать и обновлять между сессиями. Например, code-reviewer с проектной памятью со временем накапливает сведения о ваших соглашениях и повторяющихся проблемах, поэтому становится полезнее с каждым запуском. Рекомендуемый вариант — project, поскольку такую память можно хранить в системе контроля версий и делить с командой. Когда память включена, при запуске Claude Code добавляет в системный промпт первые 200 строк (или 25KB) файла MEMORY.md, поэтому его содержимое стоит поддерживать в порядке.

Для начала создайте одного узкоспециализированного субагента — классический пример, code-reviewer с доступом только для чтения, — положите его в .claude/agents/ и запускайте после каждого изменения. Когда он докажет свою пользу, добавьте исследовательского субагента на более дешевой модели. Пользу получают не те команды, которые запускают тридцать агентов, а те, у кого есть три специалиста, каждый с одной четкой задачей. Если же вы пока выбираете сам инструмент для программирования, это уже другой вопрос: сравнение есть в материале Codex, Claude Code и Cursor, а более широкий обзор — в статье о лучших ИИ-агентах для разработки.

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