Как создать субагента Claude Code?

Добавьте файл Markdown в .claude/agents/ вашего проекта или в ~/.claude/agents/ для всех проектов. В YAML frontmatter нужны name и description; тело — системный промпт. Необязательные поля: tools, model, permissionMode и isolation.

Какую модель использует субагент?

Поле model принимает алиас вроде sonnet, opus или haiku, полный ID модели или inherit. Если оно не задано, субагент использует модель основной сессии, если только переменная окружения CLAUDE_CODE_SUBAGENT_MODEL не говорит иное.

Экономят ли субагенты токены?

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

Когда использовать отдельных агентов вместо субагентов?

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

Субагенты Claude Code: как создавать и использовать

Q: Что такое субагент в Claude Code?

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

Субагенты Claude Code — это помощники, которым основная сессия Claude Code поручает одну задачу. Каждый работает в собственном контекстном окне со своим системным промптом, списком инструментов и моделью, а в основной разговор возвращается только его итоговый ответ. Субагента вы описываете файлом Markdown в .claude/agents/, и Claude использует его сам, когда задача подходит под описание, или когда вы просите его по имени.

В статье разобрано, как работают субагенты, формат файла, поля tools и model, как их вызывать и где проходит граница между субагентом и отдельным агентом, работающим рядом с первым. Факты взяты из официальной документации по субагентам. Краткую версию в одном абзаце см. в статье глоссария о субагенте.

Как работают субагенты

Когда Claude решает делегировать, он вызывает инструмент Agent (до версии 2.1.63 он назывался Task) с коротким заданием. Субагент стартует со свежим контекстом. Он получает собственный системный промпт, сообщение о делегировании, ваш CLAUDE.md, статус git и все skills, которые вы для него заранее загрузили. Истории основного разговора он не видит.

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

Несколько ограничений, о которых стоит знать:

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

Встроенные субагенты

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

Субагент	Инструменты	Типичное применение
Explore	Только чтение	Поиск и чтение по кодовой базе на глубине quick, medium или very thorough
Plan	Только чтение	Исследование в режиме plan
General-purpose	Все инструменты	Многошаговые задачи, где нужны и исследование, и изменения

Чаще всего вы увидите Explore. Когда Claude нужно найти, где что-то определено или как фича работает через несколько файлов, он часто отдаёт это Explore, чтобы содержимое файлов не попадало в ваш основной контекст.

Где лежат файлы субагентов

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

Расположение	Область действия
Managed settings	Вся организация, задаётся администраторами
Флаг `--agents` (JSON)	Одна сессия
`.claude/agents/`	Один проект, общий через git
`~/.claude/agents/`	Все ваши проекты
Папка `agents/` плагина	Везде, где установлен плагин

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

Формат файла субагента

Обязательны только name и description. Тело после frontmatter — системный промпт субагента.

---
name: code-reviewer
description: Reviews code changes for bugs, security issues and readability. Use after writing or changing code.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior code reviewer. When called:

1. Run git diff to see the recent changes.
2. Read the changed files and the code around them.
3. Report problems by priority: bugs, security, then readability.
4. For each problem, give the file, the line and a concrete fix.

Do not edit files. Report only.

description важнее, чем кажется. Именно его читает Claude, решая, делегировать ли задачу, так что пишите, что делает субагент и когда его использовать. Фразы вроде «use after writing code» помогают Claude подхватывать его самостоятельно.

Поле tools

tools — это список разрешённого. С tools: Read, Grep, Glob, Bash ревьюер выше может читать и запускать команды, но не может править файлы. Если tools не указать, субагент унаследует все инструменты основной сессии, включая инструменты MCP. Есть и disallowedTools, когда проще сказать, что убрать, чем что оставить.

Держите список как можно короче для задачи. Ревьюеру не нужен Edit. Исследователю не нужен Bash. Меньше инструментов — меньше сюрпризов и яснее задача.

Поле model

model принимает алиас (sonnet, opus, haiku), полный ID модели или inherit, чтобы использовать модель основной сессии. Когда субагента вызывают, Claude Code выбирает модель в таком порядке: модель, переданная с этим вызовом, затем поле model файла, затем переменная окружения CLAUDE_CODE_SUBAGENT_MODEL, затем модель основной сессии.

Здесь субагенты могут сэкономить реальные деньги. Широкому поиску по файлам и чтению логов редко нужна самая сильная модель. Отдайте их Haiku, а основную сессию оставьте на более крупной модели для решений. О других способах сократить расходы рассказывает статья о расходе токенов Claude Code.

Другие полезные поля

Поле	Что делает
`permissionMode`	Режим разрешений субагента, например plan или acceptEdits
`skills`	Skills, которые загружаются в контекст субагента при старте
`mcpServers`	Серверы MCP, доступные субагенту
`hooks`	Hooks, действующие, пока работает этот субагент
`memory`	Постоянная память на уровне user, project или local
`maxTurns`	Верхний предел числа ходов субагента
`background`	Запускать в фоне по умолчанию
`isolation: worktree`	Запуск во временном git worktree
`effort`	Усилие рассуждения субагента

Как вызвать субагента

Есть три способа:

Пусть решает Claude. Если запрос подходит под описание субагента, Claude делегирует сам.
Попросите по имени. «Use the code-reviewer subagent to check my last commit.» Можно также упомянуть его через @ из меню.
Запустите всю сессию как субагента. claude --agent code-reviewer запускает сессию с промптом, инструментами и моделью этого субагента.

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

claude --agents '{
  "code-reviewer": {
    "description": "Reviews code changes. Use after edits.",
    "prompt": "You are a senior code reviewer. Report bugs and fixes, do not edit.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

Чтобы запретить Claude использовать конкретного субагента, добавьте его в deny-список разрешений, например Agent(Explore).

Субагенты и отдельные параллельные агенты

И субагенты, и параллельные агенты делят работу, но решают разные задачи.

	Субагенты	Отдельные параллельные агенты
Кто запускает	Основная сессия Claude	Вы
Что вы видите	Итоговый результат внутри основного чата	Полную сессию каждого агента
Контекст	Свежий на каждую задачу, потом отбрасывается	Долгоживущий, по одному на агента
Файлы	Та же рабочая папка, если не `isolation: worktree`	Обычно по одному git worktree на каждого
Ваше участие по ходу задачи	Нет, с ним говорит основной агент	Вы можете направлять каждого
Подходят для	Поиск, ревью, исследование, короткие целевые задачи	Фичи, рефакторинги, долгие задачи, заканчивающиеся веткой

Используйте субагента, когда основному агенту нужен ответ, чтобы продолжать: «найди все вызовы этой функции», «проведи ревью этого diff», «подведи итог этих логов». Работа короткая, важен её результат, и следить за ней не нужно.

Используйте отдельных агентов, когда каждая часть — настоящая самостоятельная работа: фича, миграция, набор тестов. Вы хотите видеть, что делает каждый, отвечать на его вопросы и проверять его изменения как ветку. Именно такая схема описана в статьях о параллельных агентах для кода и запуске нескольких агентов Claude Code, где каждый агент работает в своём git worktree.

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

У Claude Code есть ещё отдельная функция agent teams, где несколько сессий Claude работают вместе. Это не то же самое, что субагенты, и она выходит за рамки статьи.

Советы для субагентов, которые работают

Одна задача на субагента. «Ревьюер» и «запускатель тестов» работают лучше, чем «помощник».
Пишите описание для Claude. Говорите, когда его использовать, а не только что это такое.
Ограничивайте инструменты. Субагенты только для чтения для исследования и ревью, инструменты правки только там, где нужно.
Выбирайте модель осознанно. Haiku для поиска и сводок, более сильная модель для проектирования и сложных исправлений.
Просите короткий отчёт. Результат попадает в основной контекст, так что скажите субагенту возвращать выводы, а не содержимое файлов.
Коммитьте субагентов проекта. .claude/agents/ в git означает, что у всех одни и те же помощники.

Как AgentVera показывает субагентов

AgentVera — десктопное приложение для запуска многих агентов для кода, Claude Code, Codex и других, бок о бок. Оно работает с субагентами двумя способами.

Вы их видите. В панели агента Claude Code кнопка «Subagents» открывает живой вид субагентов, которых запустил этот агент, и того, что они делают сейчас. У каждого показан статус (Running, Done, Error, Stopped), работает ли он «in background», полученное им «Assigned task» и его «Report». Пока кто-то работает, появляется строка «{count} subagents running — show», чтобы вы их не пропустили. В обзоре проекта и карте кода тоже есть временная шкала субагентов с типом, статусом, числом инструментов и длительностью. Оба вида читают локальные транскрипты и пока работают для агентов Claude Code.

Более дешёвый Explore. В Settings → «Token saving» опция «Explorer subagent» даёт агентам Claude explorer только для чтения для широких поисков. Сканирование файлов идёт на более дешёвой модели, по умолчанию Haiku, и в основной разговор возвращается только результат. Если у вас уже есть собственный файл субагента Explore, AgentVera оставляет ваш на месте. Опция находится рядом с smart tools в том же разделе.

Отдельные агенты, когда работа крупнее. Командный вид показывает до 24 агентов одновременно. Parallel team (тарифы Pro и Team) делит цель на части, запускает каждую в своём worktree и сливает их в один PR. Обмен сообщениями позволяет агентам задавать друг другу вопросы, даже между разными CLI, а координация агентов предупреждает, когда два агента трогают один файл. Так вы получаете сторону отдельных агентов из таблицы выше, а субагенты по-прежнему доступны внутри каждого агента Claude.

Итоги

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