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

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

- **Первоисточник:** [Create custom subagents — Claude Code Docs](https://code.claude.com/docs/en/sub-agents).

## Что такое субагент

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

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

## Что дают субагенты

- изолируют объемный поиск и вывод инструментов;
- ограничивают доступ к инструментам и операциям;
- переиспользуют одну настройку в разных проектах;
- задают узкую специализацию через системный промпт;
- позволяют отправлять простые задачи на более быструю и дешевую модель.

Claude выбирает субагента по полю `description`. Описание должно быть коротким и однозначным. Подробные правила лучше переносить в тело файла: они загрузятся только после запуска агента.

## Быстрый старт

Попроси Claude Code создать личного read-only агента:

```
Создай личного субагента code-improver в ~/.claude/agents/. Он должен проверять файлы и предлагать улучшения читаемости, производительности и практик разработки. Для каждой проблемы объясняй причину, показывай текущий код и улучшенную версию. Агент работает только на чтение и использует Sonnet.
```

Проверь файл `~/.claude/agents/code-improver.md`:

```
---
name: code-improver
description: Проверяет код после изменений и предлагает улучшения читаемости, производительности и практик разработки.
tools: Read, Grep, Glob
model: sonnet
---

Ты специалист по улучшению кода. Для каждой найденной проблемы:
1. Объясни причину.
2. Покажи текущий фрагмент.
3. Предложи улучшенную версию.
4. Укажи влияние изменения.
```

Запуск:

```
Используй агента code-improver и предложи улучшения для этого проекта.
```

Если каталог `~/.claude/agents/` появился уже после старта текущей сессии и агент не найден, перезапусти Claude Code.

## Где хранить агентов

| Расположение | Область действия | Приоритет |
| --- | --- | --- |
| Управляемые настройки организации | Вся организация | Самый высокий |
| Флаг `--agents` | Текущая сессия | 2 |
| `.claude/agents/` | Текущий проект | 3 |
| `~/.claude/agents/` | Все проекты пользователя | 4 |
| Каталог `agents/` плагина | Проекты, где включен плагин | Самый низкий |

Проектные агенты можно хранить в Git вместе с кодом. Claude Code рекурсивно сканирует каталоги агентов, поэтому определения разрешено группировать по подпапкам. Идентификатор берется из поля `name`, а не из имени файла.

Имена должны быть уникальными. Если одно имя определено в нескольких областях, побеждает файл с более высоким приоритетом. Для поиска конфликтов используй `/doctor`.

## Формат файла

Файл состоит из YAML-frontmatter и системного промпта в Markdown. Обязательны только `name` и `description`.

| Поле | Назначение |
| --- | --- |
| `name` | Уникальное имя в нижнем регистре с дефисами. |
| `description` | Условие, при котором Claude должен выбрать этого агента. |
| `tools` | Разрешенные инструменты. Если поле пропущено, агент наследует доступный набор. |
| `disallowedTools` | Инструменты, которые нужно исключить из унаследованного или заданного списка. |
| `model` | `haiku`, `sonnet`, `opus`, `fable`, полный ID модели или `inherit`. |
| `permissionMode` | Режим подтверждений: `default`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, `plan`. |
| `maxTurns` | Максимальное число агентных ходов до остановки. |
| `skills` | Skills, которые полностью загружаются в контекст при старте. |
| `mcpServers` | MCP-серверы по имени или встроенная конфигурация сервера только для этого агента. |
| `hooks` | Lifecycle-хуки, действующие внутри агента. |
| `memory` | Постоянная память: `user`, `project` или `local`. |
| `background` | При значении `true` агент остается фоновым. |
| `isolation` | При `worktree` агент работает в отдельном Git worktree. |

## Как выбрать модель

- **Haiku** — извлечение данных, простые проверки, классификация, форматирование.
- **Sonnet** — основная разработка, ревью, диагностика и большинство аналитических задач.
- **Opus** — архитектура, сложные неоднозначные решения и многошаговое рассуждение.
- **inherit** — агент использует модель основной сессии.

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

## Промпт для аудита моделей

```
Проверь .claude/agents и ~/.claude/agents. Для каждого агента укажи его задачу, заданную модель и оценку: простая или сложная работа. Найди простых агентов, которым можно поставить model: haiku без заметной потери качества. Ничего не меняй — выдай готовые правки.
```

## Инструменты и разрешения

Выдавай только те инструменты, которые нужны для результата. Read-only ревьюеру достаточно `Read`, `Grep` и `Glob`. Отладчику может понадобиться `Edit` и `Bash`. Агент без `Agent` в списке `tools` не сможет делегировать работу другим субагентам.

```
---
name: code-reviewer
description: Проверяет измененный код после реализации.
tools: Read, Grep, Glob, Bash
disallowedTools: Write, Edit, Agent
model: sonnet
permissionMode: plan
maxTurns: 12
---
```

Для выборочного контроля команд используй `PreToolUse`-хук. Например, агент для базы данных может получать доступ к Bash, а хук будет блокировать `INSERT`, `UPDATE`, `DELETE` и другие операции записи.

## MCP только внутри агента

Поле `mcpServers` позволяет подключить сервер только на время работы конкретного агента. Это полезно, если инструменты Playwright, GitHub или базы данных не должны попадать в основной контекст.

```
---
name: browser-tester
description: Проверяет готовую функцию в реальном браузере.
mcpServers:
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
tools: Read, Bash
model: sonnet
---

Открой локальное приложение, выполни заданный сценарий и верни краткий отчет с найденными ошибками.
```

Встроенный сервер подключается при старте агента и отключается после завершения. Основной диалог не получает его описания инструментов.

## Skills и постоянная память

Поле `skills` загружает выбранные навыки в контекст агента при старте. Используй его только для знаний, которые нужны почти в каждом запуске этого агента.

Поле `memory` дает отдельный каталог, который сохраняется между диалогами:

| Значение | Путь | Когда использовать |
| --- | --- | --- |
| `user` | `~/.claude/agent-memory/ /` | Знания полезны во всех проектах. |
| `project` | `.claude/agent-memory/ /` | Знания относятся к проекту и могут храниться в Git. |
| `local` | `.claude/agent-memory-local/ /` | Знания относятся к проекту, но не должны попадать в репозиторий. |

В системный промпт попадают первые 200 строк или 25 КБ файла `MEMORY.md`. Память нужно регулярно очищать от повторов и устаревших деталей.

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

- **Естественным языком:** «Попроси code-reviewer проверить последние изменения».
- **Через @-упоминание:** выбери агента в подсказке после символа `@`, чтобы гарантировать запуск конкретного определения.
- **На всю сессию:** `claude --agent code-reviewer`.

При запуске всей сессии с флагом `--agent` системный промпт агента заменяет стандартный системный промпт Claude Code. Ограничения инструментов и модель сохраняются при возобновлении сессии.

## Автоматическое делегирование

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

## Когда использовать основной диалог

| Основной диалог | Субагент |
| --- | --- |
| Нужны частые уточнения и итерации. | Работа самодостаточна и возвращает итоговую сводку. |
| Планирование, реализация и тестирование используют общий контекст. | Будет много логов, результатов поиска или файлов. |
| Нужно быстро внести одно небольшое изменение. | Нужны отдельные ограничения инструментов и разрешений. |
| Задержка важнее изоляции. | Задачу можно выполнить параллельно или на другой модели. |

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

## Параллельность и вложенность

Субагенты могут запускать других субагентов до установленной глубины. В текущей документации стандартный предел — три слоя ниже основного диалога. Переменная `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` меняет глубину; значение `1` отключает дальнейшее вложенное делегирование.

По умолчанию одновременно может работать до 20 субагентов в одной сессии. Предел меняется через `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS`. Большое число допустимых запусков не означает, что их нужно использовать: каждый агент держит собственный контекст и увеличивает расход.

## Обычный субагент и fork

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

| Параметр | Fork | Обычный субагент |
| --- | --- | --- |
| Контекст | Полная история основной сессии | Новый контекст и переданный промпт |
| Системный промпт и tools | Как у основной сессии | Из файла агента |
| Модель | Как у основной сессии | Из поля `model` |
| Кэш | Общий с основной сессией | Отдельный |

Для ручного ответвления используй `/subtask` с описанием задачи. Fork полезен для параллельной проверки нескольких подходов от одной точки.

## Практический шаблон ревьюера

```
---
name: code-reviewer
description: Проверяет измененный код после реализации на качество, безопасность и поддерживаемость.
tools: Read, Grep, Glob, Bash
disallowedTools: Write, Edit, Agent
model: sonnet
permissionMode: plan
maxTurns: 15
---

Ты проводишь read-only ревью изменений.

Порядок работы:
1. Посмотри git diff.
2. Работай только с измененными файлами и их прямыми зависимостями.
3. Найди ошибки поведения, риски безопасности, слабую обработку ошибок и отсутствие тестов.
4. Не редактируй файлы.

Формат ответа:
- критичные проблемы;
- важные замечания;
- предложения;
- конкретный способ исправления;
- проверка, которая подтвердит исправление.

Не перечисляй стилистические замечания без практического влияния.
```

## Чек-лист хорошего субагента

- Одна понятная специализация.
- Короткое и однозначное `description`.
- Минимально достаточная модель.
- Только необходимые инструменты.
- Явный формат результата.
- Ограничение числа ходов для предсказуемой задачи.
- Память включена только там, где накопленный опыт действительно нужен.
- MCP подключен локально к агенту, если основной диалог им не пользуется.
- Проектные определения хранятся в Git и проходят ревью.
- Периодически проверяется фактический расход через `/usage`.

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

---

Источник: https://localhost:3000/m/subagenty-v-claude-code-sozdanie-i-nastroyka