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

Что такое субагент и когда он нужен

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

Встроенных субагентов три: Explore (быстрый, только чтение, ищет по кодовой базе), Plan (собирает контекст в plan mode) и General-purpose (многошаговые задачи с правками). Свой субагент нужен, когда роль повторяется: ревьюер, который не трогает файлы; тестировщик с доступом только к Bash; агент-исследователь документации.

Для разовой задачи субагент не нужен. Если роль вы описываете в третий раз, пора завести файл.

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

• .claude/agents/*.md в проекте (Claude Code ищет вверх от текущей папки), коммитится вместе с кодом;
• ~/.claude/agents/ для личных субагентов во всех проектах;
• папка agents/ внутри плагина;
• флаг --agents '<json>' на одну сессию;
• managed-настройки организации.

Команда /agents в новых версиях лишь напоминает, что файлы правят руками или просят Claude. В версиях до v2.1.197 она открывала мастер с вкладками Running и Library.

Формат файла и поля frontmatter

Обязательных поля два: name (до 256 символов, без двоеточия) и description. Тело файла становится системным промптом.

---
name: code-reviewer
description: Ревьюит изменения перед коммитом. Используй после правок в src/.
tools: Read, Grep, Glob
model: inherit
---
Ты ревьюер. Читаешь diff, ищешь ошибки логики и пропущенные проверки.
Файлы не правишь. В конце список замечаний с путём и строкой.

Пример условный, проверьте его на своём проекте. Необязательные поля: tools, disallowedTools, model, permissionMode, maxTurns, skills, mcpServers, hooks, memory, effort, isolation, background, omitClaudeMd, color, initialPrompt.

Если tools не указать, субагент наследует все инструменты, доступные субагентам. Несколько из них снимаются всегда, например AskUserQuestion. Для ревьюера и исследователя список лучше задать явно: так он точно ничего не перепишет.

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

• Автоматически. Claude Code делегирует задачу, если она совпала с description. Поэтому описание пишут как условие запуска: «используй, когда…».
• Через @-упоминание в сообщении.
• Флагом claude --agent <имя>, чтобы вся сессия шла от его лица.
• Обычной фразой: «отдай ревью субагенту code-reviewer».

Лимиты и подводные камни

• До 20 субагентов параллельно, настраивается через CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS.
• Вложенность до трёх уровней ниже основного диалога (CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH, значение 1 отключает вложенность).
• Если описания пользовательских субагентов в сумме больше 15 000 токенов, Claude Code предупредит: описания лежат в контексте всегда.
• Предзагрузка skills берёт первые 32 скилла.
• Субагенты из плагинов игнорируют поля hooks, mcpServers и permissionMode. Если роли нужен свой хук, кладите её в .claude/agents/, а не в плагин.

Источник: документация Claude Code.

Кто ещё читает субагентов Claude Code

Cursor и VS Code берут файлы Claude Code без конвертации. Под Codex описание придётся переложить в TOML (дока Codex), под Gemini CLI хватит переноса папки и сверки полей (дока Gemini CLI). Готовые роли собраны в разделе Субагенты и подборке лучших субагентов для Claude Code.