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

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

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

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

Важные свойства:

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

В Claude Code есть встроенные субагенты: Explore (быстрый поиск и чтение кода, без права на запись), Plan (исследование в режиме планирования) и general-purpose (сложные многошаговые задачи с правом на изменения).

Где хранятся субагенты

Проектные субагенты удобно коммитить в репозиторий, чтобы ими пользовалась вся команда. Если имена совпадают, побеждает источник с более высоким приоритетом. Claude Code следит за этими папками и подхватывает новые и изменённые файлы без перезапуска. Перезапуск нужен, если папки agents не было на момент старта сессии.

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

Файл — Markdown с YAML-шапкой. Шапка задаёт настройки, тело становится системным промптом.

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

You are a senior code reviewer. When invoked:
1. Run git diff to see recent changes.
2. Focus on modified files.
3. Report issues grouped by severity: critical, warning, suggestion.
Include a concrete fix for every critical issue.

Обязательные поля — только name и description. Полезные необязательные:

• tools — список разрешённых инструментов. Если поле не указано, субагент наследует все доступные инструменты;
• disallowedTools — какие инструменты убрать из списка;
• model — модель (подробнее ниже);
• permissionMode — режим разрешений: default, acceptEdits, plan, dontAsk и другие;
• maxTurns — лимит шагов, после которого субагент остановится;
• mcpServers, hooks, skills — MCP-серверы, хуки и навыки только для этого субагента;
• isolation: worktree — работа во временном git worktree, а не в вашей рабочей копии.

Названия полей пишутся в camelCase. Неизвестное поле Claude Code молча игнорирует, поэтому опечатка в maxTurns ни к какой ошибке не приведёт. Поля для размера контекста у субагента нет.

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

1. Автоматически. Claude сам делегирует задачу, если она подходит под description. Фраза «use proactively» в описании подталкивает к делегированию.
2. По имени в тексте: «Use the code-reviewer subagent to check my recent changes». Решение остаётся за Claude.
3. Через @-упоминание. Наберите @ и выберите субагента в подсказке или напишите @agent-code-reviewer. Так этот субагент гарантированно будет запущен.
4. Вся сессия как субагент: claude --agent code-reviewer. Основной поток получает системный промпт, инструменты и модель этого субагента. То же самое для проекта задаёт настройка "agent": "code-reviewer" в .claude/settings.json.

Есть ещё форк: /subtask с описанием задачи (в версиях 2.1.161–2.1.211 команда называлась /fork). Форк, в отличие от обычного субагента, наследует всю текущую беседу, работает в фоне и возвращает итог сообщением. Его первый запрос использует тот же кэш промптов, что и основная сессия.

Субагенты могут запускать своих субагентов: по умолчанию до трёх уровней вложенности. Лимит задаётся переменной CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH, значение 1 выключает вложенность.

Выбор модели и подключение к Zukko

Поле model принимает алиас (sonnet, opus, haiku), полный id модели или inherit — ту же модель, что в основной сессии. Если поле не задано, порядок такой: параметр, переданный при вызове, затем model из файла, затем переменная CLAUDE_CODE_SUBAGENT_MODEL, затем модель основной сессии.

При работе через шлюз надёжнее указывать inherit или полный id из списка Zukko: claude-sonnet-5 или claude-opus-5-5. Алиасы раскрываются в конкретные версии, которых в списке шлюза может не быть. Если всё же нужны алиасы, их можно перенаправить переменными ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL и ANTHROPIC_DEFAULT_HAIKU_MODEL.

Подключение Claude Code к Zukko:

export ANTHROPIC_BASE_URL=https://api.zukko.pro
export ANTHROPIC_AUTH_TOKEN=fetch_ваш_ключ
export ANTHROPIC_MODEL=claude-sonnet-5

Адрес без /v1. Подробности — в инструкции по Claude Code↗. Актуальный список моделей — GET https://api.zukko.pro/v1/models или страница «Модели» в кабинете.

Сколько стоят субагенты

В Zukko claude-sonnet-5 и claude-opus-5-5 стоят одинаково: $0.3 за 1M входных и $0.3 за 1M выходных токенов. Поэтому выбор модели для субагента — вопрос качества на ваших задачах, а не цены. Сравните обе на нескольких реальных задачах и оставьте ту, что лучше справляется.

Экономия от субагента — в размере основного контекста. Пример: субагент прочитал логи и код на 200 000 токенов и вернул сводку на 2 000.

• Расход субагента: 200 000 × $0.3 / 1 000 000 = $0.06 на вход плюс его выходные токены.
• Основной диалог получил 2 000 токенов вместо 200 000. Каждый следующий ход основной сессии отправляет меньше контекста.

Субагент начинает с чистого контекста, и ему иногда приходится заново читать файлы, которые основная сессия уже видела. Для мелких правок дешевле и быстрее остаться в основном диалоге. Ещё одна оговорка про кэш: у вендора чтение из кэша промптов стоит около 10% входной цены, а в Zukko кэшированные токены оплачиваются по обычной входной цене. Поэтому для длинных агентных сессий реальная разница с официальным прайсом меньше, чем при прямом сравнении цен. Контролировать расход удобно отдельным ключом с дневным лимитом в кабинете↗.

Практические советы

• Пишите узкое description: на основе этого текста Claude решает, звать ли субагента.
• Ограничивайте tools. Ревьюеру хватит Read, Grep, Glob, писателю тестов нужны Edit и Bash.
• Просите в промпте субагента краткий итог в заданном формате. Всё, что он вернёт, попадёт в основной контекст.
• Запускать несколько субагентов параллельно имеет смысл, когда исследования не зависят друг от друга. Учтите, что каждый тратит свои токены.

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

Есть ли команда для создания субагента?

В актуальных версиях /agents только напоминает, что субагента можно создать, попросив об этом Claude или положив файл в .claude/agents/ либо ~/.claude/agents/. В старых версиях (до 2.1.197) это был интерактивный мастер.

Получает ли субагент мой CLAUDE.md?

Да, кастомные субагенты загружают CLAUDE.md, если в шапке не задано omitClaudeMd: true. Встроенные Explore и Plan его пропускают.

Как узнать, на какой модели работает субагент?

Команда /tasks показывает модель в строке запущенного субагента.

Можно ли запретить Claude запускать субагентов?

Да. Отдельный тип запрещается через permissions.deny, а все сразу — запретом инструмента Agent.