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

• Первоисточник: Create custom subagents — Claude Code Docs.

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

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

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

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

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

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

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

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

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

Запуск:

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

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

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

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

Формат файла

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

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

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

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

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

Выдавай только те инструменты, которые нужны для результата. 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 дает отдельный каталог, который сохраняется между диалогами:

В системный промпт попадают первые 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 может быть выгоднее, когда новой ветке нужен почти весь текущий контекст.

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

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

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

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

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