Claude Code / суб-агенты
Суб-агент - это помощник, которого Claude Code запускает под отдельную задачу: со своим заданием, своей памятью и своими инструментами. Вы пишете один запрос - Claude делит работу на части, раздаёт её нескольким таким помощникам и собирает готовый результат.
01 · Определение
Представьте прораба на стройке. Он не кладёт плитку и не тянет проводку сам - зовёт плиточника и электрика. Каждый делает свой кусок, сдаёт работу и уходит. Прораб принимает результат, а не сидит рядом с каждым.
Ваш основной разговор с Claude Code - это прораб. Суб-агент - рабочий, нанятый под одну конкретную задачу: получил задание, сделал, отчитался, исчез.
В документации Anthropic определение звучит так:
«специализированные AI-ассистенты, которые обрабатывают конкретные типы задач» Документация Anthropic
Технически это отдельный запуск Claude со своим системным промптом - инструкцией, кто он и что умеет, - и своим списком разрешённых инструментов.
Зачем это нужно. Бывают задачи, которые заваливают разговор мусором: результаты поиска по коду, логи, содержимое двадцати файлов, к которым вы больше не вернётесь. Суб-агент делает эту работу у себя и возвращает вам только выжимку.
02 · Контекст
Контекстное окно - это объём текста, который модель держит в голове за один разговор. Оно не резиновое. Когда сессия распухает от логов и прочитанных файлов, Claude начинает хуже помнить, с чего всё началось.
Суб-агент решает это просто: он стартует с чистого листа. Не видит вашу переписку, не видит файлы, которые Claude уже читал. Получает постановку задачи, свою инструкцию - и работает в собственном окне.
Обратно в основной разговор приходит только финальный отчёт. Сто страниц логов остаются у агента, короткий вывод - у вас.
Есть и обратная сторона: агент «слепой». Он знает только то, что ему передали в задании. Если для задачи нужна вся история вашей сессии - суб-агент будет чинить вслепую. Для таких случаев есть форк - особый суб-агент, который наследует весь разговор целиком (команда /subtask).
03 · Параллельность
Когда агентов несколько, кто-то должен ими управлять. Эта роль достаётся вашему основному разговору - его называют оркестратором: он держит общий план, раздаёт задачи и сводит результаты.
Claude сам решает, когда делегировать. Он смотрит на описание каждого агента (поле description в его файле) и на текущую задачу. Можно и напрямую: «исследуй модули авторизации, базы данных и API параллельно, отдельными суб-агентами» - и три агента уходят копать одновременно, каждый своё.
Важная деталь: суб-агенты не общаются между собой. Каждый отчитывается только оркестратору - как подрядчики, которые знают прораба, но не знакомы друг с другом.
Лимиты по умолчанию: до 20 агентов одновременно, до 200 за сессию. Агент может запускать собственных суб-агентов - до 3 уровней вглубь. На практике для большинства задач хватает 3-5 параллельных: дальше накладные расходы на координацию съедают выигрыш.
04 · Скорость
Anthropic проверила это на себе. Их исследовательская система устроена по той же схеме: ведущий агент разбивает вопрос на части и раздаёт суб-агентам, каждый работает в своём контекстном окне.
Результат: мультиагентная связка (Opus 4 как ведущий + суб-агенты на Sonnet 4) обошла одиночного Opus 4 на 90,2% на внутреннем ресёрч-бенчмарке. На сложных запросах параллельная работа срезала до 90% времени.
Почему так. Anthropic посчитала: 80% разницы в качестве ответов объясняется одним фактором - количеством потраченных токенов. Суб-агенты - способ вложить в задачу больше «токенов мышления», чем влезает в одно контекстное окно.
Теперь честная часть. Такая система ест примерно в 15 раз больше токенов, чем обычный чат. Вывод самой Anthropic: мультиагентность окупается там, где ценность результата заведомо выше его цены. Для быстрой правки одной функции - нет. Для ресёрча, аудита, миграции на 40 файлов - да.
05 · Практика
Суб-агент - это обычный Markdown-файл. Шапка (YAML frontmatter - блок между --- в начале файла) описывает, кто это и что ему можно. Всё, что после шапки, становится его инструкцией.
Положите его в .claude/agents/ внутри проекта - агент будет виден в этом проекте. Или в ~/.claude/agents/ - тогда во всех ваших проектах.
Пример из официальной документации - ревьюер кода:
---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.Обязательных поля два: name (имя, маленькими буквами через дефис) и description - по нему Claude понимает, когда звать этого агента. tools ограничивает инструменты: этот ревьюер умеет только читать код, править файлы не может. model выбирает модель - например, дешёвую и быструю для простых ролей.
Claude Code подхватывает файл за секунды, перезапуск не нужен. Когда задача совпадёт с description, Claude сам делегирует её агенту. Хотите наверняка - позовите явно: «Use the code-reviewer subagent to check this file».
Самый быстрый способ из доки: попросите Claude написать файл агента за вас. Опишите словами, какой помощник нужен, - он создаст файл сам.
06 · Паттерны
Один агент держит план и раздаёт задачи специалистам, те отчитываются только ему.
Пример: сделать rate-limiting middleware - оркестратор делегирует написание кода, ревью и документацию трём разным агентам. У практиков такой прогон выходил около 90K токенов (~$0.89).
N одинаковых агентов одновременно обрабатывают N независимых кусков, результаты сливаются в сводку.
Пример: миграция 40 файлов с axios на fetch - по агенту на пачку из 5-10 файлов. Живой кейс: 9 агентов параллельно собирают материал для рассылки из 9 источников, полный прогон - около 3 минут.
Этапы идут друг за другом: выход одного агента - вход следующего, между этапами точки проверки.
Пример: система обработки webhook-событий - ресёрч, архитектура, реализация, проверка. Ориентир по цене: 100-200K токенов ($2-4) на прогон.
Отдельный агент, чья работа - не соглашаться: искать дыры и оспаривать выводы. Одиночный агент часто цепляется за первую правдоподобную причину бага - скептик это ломает.
Пример: security-аудит PR, где три независимых ревьюера смотрят один код с разных сторон.
Одно предупреждение: ревьюер, которому велели искать проблемы, найдёт их даже в хорошем коде. Выполнять все его замечания подряд - прямой путь к лишним абстракциям.
07 · Честно
Обычная одиночная сессия закрывает около 80% задач. Суб-агенты - инструмент для оставшихся 20%. Не берите их, если:
Простой тест: если основная сессия сделала бы то же самое за меньшее число ходов - суб-агент был лишним.
08 · FAQ
Отдельным контекстным окном и узким заданием. Обычный разговор помнит всё, что в нём было, и делает всё подряд. Суб-агент получает одну задачу, работает в своей памяти со своим набором инструментов и возвращает только итоговый отчёт.
Нет. Он стартует с чистого листа: получает свою инструкцию, постановку задачи от Claude и файлы CLAUDE.md - но не историю разговора и не прочитанные ранее файлы. Единственное исключение - форк (команда /subtask): такой агент наследует весь разговор целиком.
До 20 одновременно и до 200 за сессию - это лимиты Claude Code по умолчанию, оба настраиваются. Агенты могут запускать своих суб-агентов до 3 уровней вглубь. На практике для большинства задач советуют 3-5 параллельных.
Мультиагентная система ест примерно в 15 раз больше токенов, чем обычный чат (одиночный агент - около 4x); цифры Anthropic. Расход снижают миксом моделей: дешёвые модели на простые роли, мощная - на оркестратора. Практики оценивают такую экономию в 40-60%.
Нет, суб-агенты встроены в Claude Code. Встроенные агенты Explore (поиск по коду), Plan (разведка перед планом) и general-purpose работают сами, без настройки. Свой агент - это один Markdown-файл в .claude/agents/, даже его можно попросить Claude написать за вас.
Назвать его в запросе - обычно этого хватает: «Use the test-runner subagent to fix failing tests». Гарантированный способ - @-упоминание агента. Третий вариант - запустить всю сессию как агента: claude --agent code-reviewer.
Нет. Суб-агенты живут внутри одной сессии, отчитываются только запустившему их разговору и друг с другом не общаются. Agent teams - несколько координируемых сессий с общим списком задач и перепиской между собой; эта фича экспериментальная и по умолчанию выключена.
09 · Мета
Страница собрана по схеме оркестратор-исполнители: тим-лид разбил работу на задачи и раздал их суб-агентам. Каждый работал в своём контекстном окне и вернул только результат.
Ресёрчер документации. Законспектировал официальную доку Anthropic: определения, синтаксис, лимиты.
Ресёрчер практики. Собрал кейсы, цифры и типичные ошибки из блогов практиков.
Дизайнер. Задал палитру, типографику и общий вид секций и сцен.
Копирайтер. Написал все тексты страницы, включая эту строку.
Иллюстратор. Нарисовал SVG-иконки и статичную графику.
Аниматор hero-сцены. Сцена «один агент тонет - команда разбирает».
Аниматор схем. Конвейер оркестратора и изоляция контекста.
Аниматор таймлайна. Сцена «последовательно против параллельно» с цифрами.
Верстальщик. Собрал тексты и сцены в одну страницу.
Интегратор. SEO, метатеги, разметка FAQ и выкладка.
Тестировщик. Проверил рендеринг, консоль браузера и мобильную версию.
Оркестратор принял работу. Ровно так, как описано выше.