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

URL: https://agentvera.dev/ru/blog/claude-code-subagents/ · Опубликовано: 2026-10-23

Что такое субагенты Claude Code, как написать их в .claude/agents, что делают поля tools и model и когда лучше отдельные параллельные агенты.

**Коротко:**

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

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

В статье разобрано, как работают субагенты, формат файла, поля `tools` и `model`, как их вызывать и где проходит граница между субагентом и отдельным агентом, работающим рядом с первым. Факты взяты из официальной [документации по субагентам](https://code.claude.com/docs/en/sub-agents "Документация Claude Code по субагентам"). Краткую версию в одном абзаце см. в [статье глоссария о субагенте](/ru/glossary/subagent/ "Субагент").

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

Когда 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 — системный промпт субагента.

```markdown
---
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` | Усилие рассуждения субагента |

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

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

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

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

```bash
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», «подведи итог этих логов». Работа короткая, важен её результат, и следить за ней не нужно.

Используйте отдельных агентов, когда каждая часть — настоящая самостоятельная работа: фича, миграция, набор тестов. Вы хотите видеть, что делает каждый, отвечать на его вопросы и проверять его изменения как ветку. Именно такая схема описана в статьях о [параллельных агентах для кода](/ru/blog/parallel-coding-agents/ "Параллельные агенты для кода") и [запуске нескольких агентов Claude Code](/ru/blog/run-multiple-claude-code-agents/ "Запуск нескольких агентов Claude Code"), где каждый агент работает в своём [git worktree](/ru/blog/git-worktree-parallel-agents/ "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», чтобы вы их не пропустили. В [обзоре проекта и карте кода](/ru/features/project-tour-and-code-map/ "Обзор проекта и карта кода") тоже есть временная шкала субагентов с типом, статусом, числом инструментов и длительностью. Оба вида читают локальные транскрипты и пока работают для агентов Claude Code.

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

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

## Итоги

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

Читайте также:

- [Субагент (глоссарий)](/ru/glossary/subagent/ "Субагент")
- [Параллельные агенты для кода](/ru/blog/parallel-coding-agents/ "Параллельные агенты для кода")
- [Обзор проекта и карта кода](/ru/features/project-tour-and-code-map/ "Обзор проекта и карта кода")
- [Parallel team](/ru/features/parallel-team/ "Parallel team")
- [Агент Claude Code](/ru/agents/claude-code/ "Claude Code в AgentVera")

Чтобы попробовать AgentVera, начните с [главной страницы](/ru/ "AgentVera").

## Частые вопросы

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

**Как создать субагента 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 дают это; субагенты подходят для коротких целевых задач, результат которых нужен основному агенту.

---

**Об AgentVera.** AgentVera — настольное приложение для macOS, Windows и Linux от Solviera Teknoloji. Оно запускает 18 ИИ-агентов для программирования (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) рядом, по проектам, в настоящих терминалах с собственными установками CLI и входами пользователя. В бесплатном тарифе количество агентов не ограничено. Скачать: https://agentvera.dev/ru/download/ · Цены: https://agentvera.dev/ru/pricing/