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

Переполнение контекста - одна из самых раздражающих проблем при долгой работе с Claude Code. Час работы, сорок открытых файлов, 70% контекста занято - и качество ответов ощутимо проседает. Anthropic решила это через делегирование.

Что такое subagent

Subagent - это отдельный экземпляр Claude, который запускается из основной сессии и работает независимо. У него собственное контекстное окно, собственный системный промпт, собственный allowlist инструментов и опционально собственная модель.

Парент-агент видит только финальный summary, который вернул subagent. Ни один промежуточный шаг рассуждений в основной контекст не попадает. Это и есть главный смысл механизма: изоляция.

Как это устроено технически

Subagent - это markdown-файл с YAML-frontmatter. Никакого SDK, никакой регистрации, никаких компилируемых артефактов.

Файл кладётся в .claude/agents/<name>.md (для проектного скопа) или ~/.claude/agents/<name>.md (для пользовательского). Claude Code обнаруживает его автоматически при старте сессии.

Frontmatter содержит четыре основных поля:

• name - идентификатор, по которому агент вызывается
• description - текст, по которому парент-агент решает, делегировать ли задачу
• tools - allowlist инструментов, доступных subagent
• model - конкретная модель: sonnet, opus или haiku

Тело файла после frontmatter - это системный промпт subagent.

Как работает роутинг

Claude Code использует description каждого зарегистрированного subagent как сигнал для роутинга. Парент сравнивает намерение задачи с описаниями всех доступных агентов и выбирает подходящего - та же логика, что при выборе tool.

Отсюда практическое правило: description пишется не для людей, а для модели. Конкретно, в активной форме, с триггерами на использование.

«Use immediately after writing or modifying code» работает лучше, чем «Reviews code quality». «Use when the user asks about database performance issues» лучше, чем «Database expert».

Если автоматическое делегирование не срабатывает, можно форсировать вызов вручную: директива @code-reviewer в чате или флаг claude --agent code-reviewer в shell.

Три встроенных subagent

В Claude Code есть три агента, которые работают по умолчанию без конфигурации.

Explore - быстрый read-only агент на Haiku для поиска и анализа кода. Write и Edit запрещены, чтобы ничего случайно не мутировал.

Plan - используется в plan mode для сбора контекста перед написанием плана.

general-purpose - catch-all для сложных multi-step задач, под которые не подходит ни один специализированный subagent.

Ограничение инструментов - не опция, а необходимость

Каждый subagent может получить полный набор инструментов парент-сессии, но в production это плохая идея.

Поле tools - это allowlist: если задано, subagent видит только перечисленные инструменты. Поле disallowedTools - denylist, который вычитается из всего доступного. Если заданы оба, сначала применяется denylist, потом allowlist резолвится против оставшегося.

В материале приводится конкретный кейс: refactor-architect subagent с полным доступом к Bash решил «протестировать» свой рефакторинг через git reset и пересборку. Итог - 40 минут несохранённой работы в парент-сессии стёрты. После этого практика стала простой: каждый subagent получает явный tools allowlist, без исключений.

Дополнительный уровень защиты - session-level permissions в .claude/settings.json. Там можно задавать bash-pattern allow и deny правила на уровне всей сессии.

Паттерны оркестрации: sequential, parallel, fan-out

Subagents можно запускать тремя способами, и выбор паттерна напрямую влияет на стоимость и время выполнения.

Sequential - парент ждёт результата от первого subagent, использует его для запуска следующего. Подходит для конвейерных задач: нельзя начать тесты до того, как написан код.

Parallel - парент запускает несколько независимых subagents одновременно, ждёт результаты от всех. Поиск в кодовой базе по нескольким направлениям, генерация тестов и документации параллельно с code review. Время сокращается в несколько раз, токены тратятся пропорционально количеству агентов плюс координационный overhead.

Fan-out - массивный параллельный запуск десятков или сотен subagents. Примеры из источника: прогон бенчмарка по 80 комбинациям модель-промпт, проверка кода в 200 микросервисах одним security-агентом, генерация миграций под каждую таблицу базы данных.

Для повседневной работы оптимум - 3-5 параллельных subagents. Дальше парент тратит больше времени на оркестрацию summaries, чем экономит на параллелизме. Dynamic Workflows нужны только когда задача реально fan-out по природе.

Пример: ship-it pipeline

В источнике описана конкретная композиция агентов:

• spec-writer и implementer работают sequential (код без спеки не пишется)
• test-writer и code-reviewer запускаются параллельно после implementer (оба анализируют один диф, не зависят друг от друга)
• pr-author объединяет результаты

Это наглядно показывает, как sequential и parallel комбинируются в одном пайплайне.

Что это значит для тебя

Если ты работаешь с большими кодовыми базами и регулярно упираешься в потолок контекста, subagents - прямой ответ на эту проблему. Механизм не требует никаких внешних зависимостей: просто файл в нужной директории.

Ключевые вещи, которые стоит сделать сразу:

• Пиши description как инструкцию для модели, а не как человекочитаемое описание
• Всегда задавай явный tools allowlist - не жди инцидента с git reset
• Для большинства задач хватит 3-5 параллельных агентов; fan-out нужен редко

Источник: Хабр (OTUS), 3 июля 2026 - читать оригинал

FAQ

Нужно ли что-то устанавливать дополнительно? Нет. Subagents - это часть Claude Code. Достаточно положить markdown-файл в .claude/agents/ и перезапустить сессию.

Можно ли использовать разные модели для разных subagents? Да. Поле model в frontmatter позволяет указать sonnet, opus или haiku под каждый конкретный агент.

Когда Dynamic Workflows не нужны? Когда задача не имеет природы fan-out. Для линейной работы последовательный или небольшой параллельный запуск дешевле и быстрее.