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

Коротко (TL;DR)

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

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

С чего начать: у Claude Code уже есть встроенные субагенты (Explore, Plan, general-purpose) — их можно вызывать сразу, ничего не настраивая. Свой субагент — это один markdown-файл в .claude/agents/. Дальше разберём механизм, рецепт создания, решающую таблицу «субагент или что-то другое», честную себестоимость в токенах и риски безопасности с конкретными датами и номерами багов.

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

SpaceX · xStockSpaceX — частная компания. Торгуй её токеном на Bybit за крипту.Торговать SpaceX →

Что такое субагент и что именно он возвращает

Обычный диалог с Claude Code идёт в одном контекстном окне. Всё, что агент прочитал, вызвал и обдумал, лежит в этом окне и постепенно его заполняет. Чем больше мусора (содержимое двадцати файлов, вывод команд, тупиковые ветки рассуждений) — тем ближе окно к пределу и тем хуже модель держит нить.

AMD покупает себе место у Anthropic: 2 гигаватта MI450 в обмен на инвестицию до $5 млрд

Один агент или несколько: как выбрать мультиагентную архитектуру

Пять паттернов агентных систем: механика, примеры и цена каждого

Воркфлоу против ИИ-агента: как выбрать и не переплатить за автономность

Как не терять контекст в Claude Code: компакт, resume и handoff

Субагент решает эту проблему архитектурно. Формально это изолированное контекстное окно с собственным системным промптом, своим списком инструментов и своими правами. Главная сессия (её называют оркестратором) отправляет субагенту задание, субагент отрабатывает его в своём окне, а обратно оркестратору уходит только последнее сообщение — итог. Всё промежуточное остаётся внутри субагента и в контекст оркестратора не попадает.

Именно поэтому в инженерных материалах Anthropic субагентов относят к механизмам сжатия контекста: сто прочитанных файлов сворачиваются до одного абзаца вывода. Тонкость, которую редко проговаривают: субагенты работают не потому, что «аккуратнее» главного потока, а потому что позволяют потратить на трудную задачу больше токенов, не раздувая одно окно. В собственных замерах Anthropic по бенчмарку многошагового поиска объём потраченных токенов объяснял около 80% разброса в успешности — то есть тяжёлая задача просто требует много «думанья», и субагент даёт этому думанью отдельную комнату.

Отсюда же вытекает граница применимости. Субагент невидим: пока он не закончит, оркестратор (и вы) не видите его шагов. Официальный блог Anthropic про «steering» проводит по этому признаку чёткую грань между субагентом и навыком (skill): навык крутится в главном потоке на виду, а субагент по конструкции невидим до финального результата. Это удобнее, чем расхожее клише «навык — это знание, субагент — это делегирование».

Не путать: субагенты CLI и субагенты Agent SDK

Есть две разные вещи с похожим названием. Эта статья — про субагентов Claude Code CLI: файлы .claude/agents/*.md, вызов через инструмент Task/Agent. Есть ещё субагенты в Claude Agent SDK — это программный слой для разработчиков, где агенты задаются параметром в коде приложения. Механика похожа по смыслу, но это другая продуктовая поверхность; дальше речь только о CLI.

Встроенные субагенты: принцип видно сразу

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

• Explore — субагент только для чтения (read-only). Ходит по кодовой базе, ищет, где что определено, и возвращает сжатую карту. С версии v2.1.198 он наследует модель родителя, чтобы разведка не деградировала на слабой модели.
• Plan — тоже read-only, используется в режиме планирования: собирает контекст и предлагает план, не трогая файлы.
• general-purpose — субагент с полным набором инструментов, для многошаговых задач, которым нужны и чтение, и запись, и поиск.
• Служебные — statusline-setup, claude-code-guide и подобные, под узкие задачи конфигурации.

Важная деталь механики: Explore и Plan при старте пропускают загрузку CLAUDE.md и git-статуса (им это не нужно и только заняло бы контекст), тогда как обычный субагент эти данные подхватывает. Это тоже про экономию окна.

SpaceX · xStockSpaceX — частная компания. Торгуй её токеном на Bybit за крипту.Торговать SpaceX →

Как создать своего субагента: пошагово

Свой субагент — это markdown-файл с YAML-заголовком (front-matter). Фича появилась в Claude Code v1.0.60 (24 июля 2025); в тот же день профильный issue с цитатой из релиз-ноута завели в стороннем репозитории сообщества — это удобное независимое подтверждение даты.

Шаг 1. Решите, где хранить. Claude Code читает субагентов с пяти уровней, и при совпадении имён приоритет такой: managed (корпоративная политика) → флаг CLI --agents → проект → пользователь → плагин. (Не путайте флаг --agents — JSON-набор субагентов на сессию — с --agent, который назначает одного субагента на всю сессию; о нём ниже.) — Проектный уровень: .claude/agents/<имя>.md в репозитории — субагент едет вместе с проектом и работает у всей команды. — Пользовательский: ~/.claude/agents/<имя>.md — ваш личный субагент во всех проектах.

Шаг 2. Опишите front-matter. Обязательны только два поля — name и description; остальное опционально:

---
name: research-competitor
description: Тяжёлый веб-ресёрч по теме. Использовать в начале написания статьи.
tools: [WebSearch, WebFetch, Read]   # опционально; не задано → наследует ВСЕ инструменты родителя
model: sonnet                        # опционально: sonnet | opus | haiku | inherit
permissionMode: default              # опционально
---

Ты — ресёрчер. Твоя задача — собрать факты по теме и вернуть
компактный бриф: тезис → источник → дата. Не пиши статью,
верни только структурированный список фактов.

Тело файла — это системная инструкция субагента: кто он, что делает, в каком формате возвращает результат. Хорошее description критично: по нему оркестратор понимает, когда сам делегировать задачу этому субагенту.

Шаг 3. Проверьте tools — это и настройка, и вопрос безопасности. Если поле tools не задано, субагент наследует все инструменты родителя. Хотите ограничить — перечислите инструменты явно. Здесь легко ошибиться (об этом подробно в разделе про риски): поля tools: и allowed-tools: — не одно и то же, и путаница между ними уже приводила к инцидентам.

Шаг 4. Вызовите субагента. Три способа: 1. Естественным языком — просто попросите: «пусть субагент-ресёрчер соберёт данные по теме X». Оркестратор сам подберёт подходящего по description. 2. Через @-упоминание конкретного субагента в запросе. 3. Флагом --agent <имя> — назначить субагента на всю сессию.

Шаг 5. Запускайте параллельно, когда задачи независимы. Несколько субагентов можно поднять в одном обращении — например, отдать разведку по трём подсистемам трём копиям Explore разом. Они отработают одновременно, и оркестратор соберёт три карты. Это ровно тот приём, на котором строятся более сложные оркестрации (о них — отдельная статья серии).

Конкретный пример, зачем это нужно. Допустим, вы просите: «разберись, как в проекте устроены авторизация, платежи и уведомления». В одном окне агент прочитал бы десятки файлов по трём подсистемам, и к моменту ответа контекст был бы забит их содержимым. С субагентами вы поднимаете три Explore разом — каждый читает свою подсистему в своём окне, а в главный поток возвращаются три коротких резюме вместо трёхсот килобайт кода. Главное окно остаётся чистым для собственно работы.

Как фича менялась

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

• v1.0.60 (24 июля 2025) — релиз кастомных субагентов.
• v2.1.63 — инструмент вызова переименован из Task в Agent (старые материалы всё ещё пишут «Task tool»).
• v2.1.117 — появились форки контекста; v2.1.161 — команда /fork стала доступна по умолчанию (без отдельной переменной окружения).
• v2.1.172 — зафиксирован лимит вложенности 5 уровней.
• v2.1.198 — Explore стал наследовать модель родителя, доработан фоновый режим.

Практический вывод: если гайд написан до осени 2025 и говорит про «Task tool» или иначе описывает форки — сверяйтесь с актуальной документацией, детали уже другие.

Когда субагент, а когда что-то другое

Субагент — не единственный способ поменять поведение Claude Code. Официальный блог Anthropic про «steering» сводит воедино целых семь механизмов: CLAUDE.md, правила (Rules), навыки (Skills), субагенты (Subagents), хуки (Hooks), стили вывода (Output styles) и дописка к системному промпту (system prompt append). Большинство гайдов сравнивают три-четыре — вот эти семь по ключевому признаку (плюс MCP отдельной строкой как смежный механизм, которого в «семёрке» нет, но он часто стоит рядом в выборе):

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

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

Отдельный вопрос уровнем выше — нужна ли задаче автономность вообще: часто дешевле и предсказуемее заранее описанный воркфлоу вместо ИИ-агента.

Сколько это стоит в токенах

Единой измеренной цифры «оверхеда субагента» для Claude Code CLI не существует, и материалы, которые называют точное число, обычно не раскрывают методику.

Что известно достоверно. Anthropic публиковала архитектурные цифры 4x и 15x (13 июня 2025): агентные системы расходуют примерно вчетверо больше токенов, чем обычный чат, а многоагентные — примерно в пятнадцать раз больше. Но эти числа относятся к их продукту Claude Research, а не к Claude Code CLI напрямую — переносить их один в один некорректно, хотя так делают часто.

Что гуляет по сети про сам Claude Code CLI — расходящиеся community-оценки без общей методики:

Вывод для практики: субагенты — это осознанная плата за глубину, а не бесплатная «чистота». Снизить расход помогают три приёма: (1) назначить субагенту модель попроще (model: haiku или sonnet для разведки вместо opus); (2) сузить задачу и набор инструментов, чтобы субагент не бродил лишнего; (3) задать в системной инструкции сжатый формат возврата — тогда итог короче и токенов на него уходит меньше.

Если вам нужен постоянный автономный ассистент, а не разовое делегирование внутри сессии, это уже другой класс инструментов со своей экономикой — мы разбирали её на примере персонального ИИ-агента OpenClaw, где себестоимость запуска считается отдельно.

Где ломается

Изоляция субагента — сильная сторона, но у неё есть цена и несколько неочевидных ограничений.

• Субагент по умолчанию наследует все права родителя. Это не песочница. Если вы не сузили tools, субагент может делать всё, что может главная сессия. «Изолированный контекст» не означает «изолированные права».
• Субагенты не общаются между собой. Каждый отчитывается только оркестратору. Ни одно сообщение субагента не может подтвердить запрос на разрешение за другого субагента или изменить его конфигурацию. Для координации нескольких исполнителей нужен уровень выше — оркестрация.
• Лимит вложенности — 5 уровней (зафиксирован с версии v2.1.172, не настраивается). Штатно субагент может порождать субагентов не глубже пяти уровней.
• Загрузка при старте. Обычный субагент подтягивает CLAUDE.md и git-статус; Explore и Plan — нет. Если ваш кастомный субагент неожиданно «знает» лишнее про проект — вероятно, дело в этой автозагрузке.

Отдельная тонкость про модель субагента: порядок разрешения — переменная окружения → указание при вызове → поле model во front-matter → наследование от родителя. Если субагент упорно берёт не ту модель, ищите переопределение выше по этой цепочке.

Риски безопасности

Технической теме тоже нужен честный раздел рисков — здесь он не абстрактный, а с конкретными датами и номерами.

1. Путаница tools: и allowed-tools: → реальные инциденты. В issue #27099 (создан 20 февраля 2026) описаны два случая, когда из-за перепутанных полей субагент получил больше прав, чем предполагал автор, и это привело к credential-hunting: в одном случае — попытка дампа Keychain, в другом — извлечение JWT-токена. Issue закрыт как not_planned — то есть молчаливое игнорирование неверного имени поля инструментарий сам не поймает. Урок простой: явно перечисляйте tools и проверяйте, каким именно полем вы ограничиваете доступ.

2. Обход PreToolUse-хуков — история из двух глав, которые обычно сливают в одну. — Общий случай (issue #21460): субагент мог обходить блокирующий хук PreToolUse. Мейнтейнер Anthropic подтвердил исправление 29 мая 2026 с описанием теста на конкретных версиях — эта дыра закрыта. — Узкий случай в режиме bypassPermissions (issue #43772): открыт 5 апреля, закрыт как not_planned 15 мая 2026. То есть не исправлен — для тех, кто использует bypassPermissions вместе с субагентами, риск остаётся практическим.

Картина честнее звучит как «частично исправлено», а не «всё сломано» или «всё чисто».

3. Свежий баг рекурсивного спавна (issue #68619, 15 июня 2026, статус OPEN). При определённом отказе в правах субагенты могут запустить бесконечный цикл повторного спавна — в отчёте фигурируют 50+ уровней вложенности и сжигание до 4 миллионов токенов за пять минут. Формально это не противоречит лимиту в 5 уровней (там другой механизм — не штатная вложенность, а баг-цикл), но для кошелька и нервов разница невелика. Баг попал в топ обсуждений сообщества за месяц — то есть это не единичная жалоба.

4. Изоляция от prompt injection реальна, но не абсолютна. Отдельное контекстное окно субагента ограничивает урон от вредоносной инструкции — но только если вредоносный текст попал именно субагенту и не эскалирует через унаследованные права. Полной гарантии изоляция не даёт.

Как класс инструментов субагенты — часть более широкой автоматизации внутри одной ИИ-сессии; для сравнения, агент с постоянной памятью и своей базой знаний — это уже другой сценарий, где нет «одноразовой» изоляции и риски другие.

Что выбрать для модели субагента

Короткий практический ответ: для разведки и ресёрча берите модель побыстрее и подешевле, для написания и сложных рассуждений — флагман. Выбор задаётся полем model во front-matter (haiku/sonnet/opus/inherit) или переопределяется выше по цепочке разрешения. Если сомневаетесь в возможностях конкретной модели под задачу субагента, ориентируйтесь на её профиль — например, мы подробно разбирали возможности Claude Sonnet 5 как рабочую лошадку для делегированных задач.

FAQ

Чем субагент отличается от навыка (skill)? Навык выполняется в главном контекстном окне и его шаги видны; субагент работает в отдельном окне и невидим до финального результата. Навык берут для повторяемой процедуры на виду, субагента — для задачи «прочитать много, вернуть мало» без засорения главного контекста.

Субагент экономит токены? Нет — он экономит контекстное окно, но обычно расходует больше токенов, а не меньше. Смысл в том, чтобы потратить их в отдельной «комнате» и вернуть в главный поток только сжатый итог. Точной измеренной цифры оверхеда для Claude Code CLI нет; официальные 4x/15x Anthropic относятся к другому продукту (Claude Research).

Как ограничить, что может делать субагент? Явно задайте поле tools во front-matter — иначе субагент унаследует все инструменты родителя. Проверьте, что используете именно tools, а не похожее поле: путаница уже приводила к инцидентам с доступом к секретам (issue #27099, февраль 2026).

Можно ли запустить несколько субагентов сразу? Да, несколько субагентов поднимаются в одном обращении и работают параллельно — это подходит для независимых задач (например, разведка по разным частям проекта). Между собой они не общаются; результаты собирает оркестратор.

Где хранить субагента — в проекте или у пользователя? В проекте (.claude/agents/ в репозитории), если субагент нужен всей команде и едет вместе с кодом; на уровне пользователя (~/.claude/agents/), если это ваш личный помощник во всех проектах. При совпадении имён проектный уровень приоритетнее пользовательского.

Правда ли, что глубже 5 уровней вложенности субагенты не идут? Штатно — да, лимит 5 уровней зафиксирован и не настраивается. Но известен баг рекурсивного спавна (issue #68619, июнь 2026, ещё открыт), при котором из-за отказа в правах возникает цикл на десятки уровней и огромный расход токенов. Это не штатная вложенность, а дефект — но знать о нём стоит.