Агенты в Claude Code: как работают субагенты

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

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

Что такое субагент и зачем он нужен

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

Отсюда два практических эффекта. Первый — экономия. Поиск по репозиторию, который съел бы 40 тысяч токенов основного диалога, обходится ему в несколько сотен: ровно столько, сколько занимает итоговый ответ. Про то, откуда вообще берётся расход, подробно написано в заметке о токенах и лимитах.

Второй — специализация. Ревьюеру кода не нужен доступ на запись, исследователю документации не нужен bash. Субагент можно ограничить так, чтобы он физически не мог сделать лишнего, и это надёжнее, чем просьба «пожалуйста, ничего не меняй» в промпте.

Важно не путать субагентов с мультиагентными системами в широком смысле. Здесь нет равноправных агентов, которые договариваются между собой: есть главный диалог-координатор и подчинённые исполнители, каждый из которых отвечает ровно один раз.

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

Субагент — это markdown-файл с YAML-заголовком. Claude Code ищет такие файлы в нескольких местах, и при совпадении имён приоритет получает источник, который выше по списку:

1. управляемые настройки организации (задаются администратором);
2. флаг --agents при запуске — только для текущей сессии;
3. .claude/agents/ в корне проекта — агенты этого репозитория, их удобно класть в git и делить с командой;
4. ~/.claude/agents/ — личные агенты, доступные во всех проектах;
5. каталог agents/ внутри подключённого плагина.

Каталоги сканируются рекурсивно, так что при желании агентов можно разложить по подпапкам вроде agents/review/ и agents/research/ — на работу это не влияет, только на порядок в репозитории. Логика та же, что у скиллов и у CLAUDE.md: проектное перекрывает пользовательское.

Заголовок файла: минимум и остальное

Обязательных полей всего два — name и description. Минимальный рабочий агент выглядит так:

---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---

You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.

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

Поле name пишется строчными буквами через дефис и должно быть уникальным. Поле description — не украшение: именно по нему основной диалог решает, кому передать задачу. Формулировка «Use after writing or modifying code» работает лучше, чем «Агент для кода», потому что описывает не тему, а момент вызова.

Дальше идут необязательные поля, и их заметно больше, чем принято думать:

• tools — белый список инструментов. Если поле не указано, субагент наследует всё, что доступно основному диалогу;
• disallowedTools — чёрный список: наследуем всё, кроме перечисленного. Удобно, когда проще запретить два инструмента, чем перечислить двадцать;
• model — sonnet, opus, haiku, fable, полный идентификатор вроде claude-opus-5 или значение inherit (взять модель основного диалога);
• permissionMode — режим подтверждений: default, acceptEdits, auto, plan и другие;
• maxTurns — потолок по числу шагов, страховка от зацикливания;
• skills — скиллы, которые нужно загрузить в контекст субагента сразу при старте;
• mcpServers — какие MCP-серверы ему видны;
• hooks — хуки жизненного цикла, действующие только внутри этого агента;
• memory — постоянная память со скоупом user, project или local;
• omitClaudeMd — не подгружать файлы CLAUDE.md;
• effort — уровень усердия от low до max;
• isolation: worktree — выполнять работу в отдельном git-worktree, не трогая рабочую копию;
• color — цвет в интерфейсе, чисто косметика.

Для MCP-инструментов в списках поддерживаются шаблоны: mcp__имя_сервера, mcp__имя_сервера__* или mcp__* для всех сразу.

Как агент выбирает, кого позвать

Есть два сценария. Автоматический: основной диалог смотрит на вашу формулировку, на описания доступных субагентов и на текущий контекст — и сам решает делегировать. Подтолкнуть к этому помогает фраза «use proactively» в описании.

Явный вызов бывает разной степени жёсткости. Можно просто назвать агента по имени — «Use the test-runner subagent to fix failing tests», — и тогда решение всё равно остаётся за моделью. Можно поставить @-упоминание вроде @agent-code-reviewer: это гарантирует запуск. А можно запустить целую сессию от лица субагента через claude --agent code-reviewer или прописать "agent" в .claude/settings.json.

Последний вариант хорош для CI и для прогонов на регрессии: поведение фиксировано и не зависит от того, как модель истолковала запрос сегодня.

Встроенные субагенты

Три агента доступны без всякой настройки. Explore — быстрый поиск по кодовой базе, только чтение (Read, Grep, Glob). Plan — исследование в режиме планирования, тоже без записи. General-purpose — универсал с полным набором инструментов под многошаговые задачи.

Explore и Plan одноразовые: продолжить их работу вторым сообщением нельзя, только запустить заново. Свои субагенты так умеют — основной диалог возвращается к ним с полной историей предыдущего разговора. Отключить встроенных можно через permissions.deny со значениями вроде Agent(Explore).

Модель под задачу

Модель выбирается по цепочке: параметр конкретного вызова → поле model в файле агента → переменная окружения CLAUDE_CODE_SUBAGENT_MODEL → модель основного диалога.

Практическое правило простое. Массовые механические операции — поиск, переименования, обход сотни файлов — отдавайте самой дешёвой модели: там нужна аккуратность, а не глубина. Ревью, рефакторинг и отладка хорошо ложатся на средний уровень. Тяжёлую аналитику вроде архитектурной критики или аудита безопасности имеет смысл оставить старшей модели. Если хочется загнать вообще всех субагентов на одну модель, к переменной CLAUDE_CODE_SUBAGENT_MODEL добавляется CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1.

Что субагент видит на старте

При запуске в его контекст попадают: собственный системный промпт, текст задачи от основного диалога, файлы CLAUDE.md всех уровней, снимок состояния git, предзагруженные скиллы и список соседних агентов. Не попадают: история вашего разговора, настройки стиля вывода и автоматическая память.

Это ровно та причина, по которой субагенты иногда «тупят на пустом месте». Он не знает, что двадцать сообщений назад вы договорились не трогать legacy-модуль. Всё существенное нужно либо класть в задачу, либо выносить в CLAUDE.md, либо включать субагенту memory — тогда он будет накапливать наблюдения между сессиями. Про разные подходы к этому есть отдельная заметка о памяти у AI-агентов.

Фоновый и передний план

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

У фоновых есть нюанс: набор инструментов им урезают сильнее. Остаются чтение, поиск, правка файлов, bash, веб-запросы и ещё несколько — но, например, интерактивные вещи вроде уточняющих вопросов недоступны в принципе. Фоновый агент, которому нужно спросить, просто не спросит.

Ограничения, о которые спотыкаются

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

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

И самое частое: описание, по которому невозможно принять решение. «Агент для работы с базой» не говорит модели ничего — непонятно, когда его звать. «Use when a query is slow or an EXPLAIN plan needs review» — говорит. Описание пишется не для человека, а для того, кто выбирает исполнителя.

Вывод

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