Субагенты Claude Code: Когда и как запустить команды агентов

Последнее обновление: June 28, 2026

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

Краткий ответ: что такое subagent Claude Code?

Subagent — это экземпляр Claude, который имеет собственное окно контекста, собственный системный промпт и узкий набор инструментов. Основная сессия не теряет контекст при его выполнении, потому что subagent работает в изоляции и возвращает только краткое изложение. Представьте это как делегирование задачи коллеге, который никогда не прерывает ваш экран.

Официальный механизм прост. Вы помещаете markdown-файл в .claude/agents/ с YAML frontmatter, и Claude Code может вызвать его через инструмент Task, когда задача соответствует его описанию. Документация по sub-agents является источником правды для полей, а репозиторий Claude Code отслеживает изменения формата.

Минимальное определение subagent выглядит следующим образом:

---
name: migration-writer
description: Writes and runs database migrations for this repo. Use for schema changes.
tools: Read, Edit, Bash
model: inherit
---
You are a migration specialist. Always check existing migrations first, never drop columns without a confirmation step, and run the migration against the local DB before reporting done.

Как только этот файл существует, я прошу основной агент "использовать subagent migration-writer для добавления таблицы orders", и он отправляет ограниченного рабочего вместо того, чтобы делать это встраиваемым способом. Строка model: inherit сохраняет стоимость и качество на уровне основной сессии; привязка более дешевой модели, такой как haiku, к subagent, интенсивно использующему чтение, является реальным рычагом, когда вы запускаете их много.

Когда следует использовать суб-агентов вместо одной сессии?

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

Я использую суб-агентов для задач, которые в противном случае загрязняли бы мой основной контекст логами, большими объемами чтения или методом проб и ошибок. Аудит всего кодобазы, который greps 200 файлов, является идеальным кандидатом, потому что суб-агент читает все это и возвращает двухпараграфное резюме, в то время как моя основная сессия остается чистой.

Если вы новичок в самом агенте, Claude Code ultimate guide освещает основы, прежде чем добавлять суб-агентов.

Как вызвать суб-агентов в Claude Code?

Вызов происходит двумя способами. Основной агент может самостоятельно вызвать инструмент Task, если задача соответствует описанию суб-агента, или вы можете явно указать его имя в своем запросе (prompt). Я предпочитаю указывать это имя, потому что неявный вызов иногда пропускает агента, который мне нужен.

Несколько шаблонов, которые я использую регулярно:

• "Используй суб-агента code-reviewer для различий (diff) в этой ветке и примени его предложения."
• "Вызови migration-writer, чтобы добавить столбец users.email_verified, и вызови test-writer, чтобы покрыть его тестами. Запусти оба."
• "Запусти суб-агента api-docs для src/routes/ и верни только скелет OpenAPI."

Суб-агент работает в собственном контексте, поэтому он не может видеть ваш текущий разговор, если вы не передадите детали в запросе (prompt). Эта изоляция — главное преимущество. Когда он завершает работу, вы получаете результат, а не поток промежуточного шума.

Шаблоны, которые я использую для рабочих процессов, имитирующих работу команды

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

Исследование, а затем распараллеливание. Я отправляю один под-агент для сбора контекста, читаю его краткое изложение, а затем отправляю несколько под-агентов реализации к общему интерфейсу. Это имитирует работу технического лида при оценке объема работы перед распределением тикетов.

Построение по контракту. Сначала определите API или пропсы компонента, затем запустите бэкенд-под-агента и фронтенд-под-агента параллельно относительно этого контракта. Ни один из них не блокирует другой, а конфликты редки, потому что они затрагивают разные файлы.

Рецензирование как отдельная роль. Я использую под-агента code-reviewer с только инструментами чтения. После любых нетривиальных изменений я запускаю его против diff. Ограничение его инструментов означает, что он буквально не может редактировать, что сохраняет честность обзора.

Для таких повторяемых рабочих процессов объедините под-агентов с Claude Code skills: навык кодирует шаги, а под-агенты выполняют изолированную работу. И если под-агент нуждается во внешних данных, подключите его к серверу MCP так, как описано в Claude Code MCP integration guide.

Рабочий пример: заказы и платежи

В прошлом месяце я разделил функцию "заказы плюс платежи" на три под-агента относительно типизированного контракта. Контракт представлял собой единый TypeScript interface для Order со status, totalCents и paymentId. Я отправил: бэкенд-под-агента для реализации создания заказа и переходов статуса; платежный под-агент для подключения вызова Stripe и сохранения paymentId; и тестового под-агента для покрытия счастливого пути (happy path) и крайнего случая возврата средств. Все три затронули разные файлы, поэтому слияние заняло всего три чистые операции копирования/вставки вместо сессии разрешения конфликтов. Весь процесс занял 14 минут; та же работа в одной последовательной сессии потребовала 41 минута на прошлой неделе, потому что единый контекст постоянно перезагружал документацию Stripe.

Как оркестровать параллельную работу, не теряя контекста?

Основная сессия — ваш координатор. Ее задача — разделить работу, передать ограниченные промпты и собрать результаты воедино. Держите координатора минималистичным и позвольте суб-агентам выполнять тяжелые операции чтения.

Типичный параллельный запуск для меня выглядит следующим образом:

1. Написать контракт и границы файлов в основной сессии.
2. Отправить от двух до четырех суб-агентов, каждый с одним срезом и четким условием успеха.
3. Читать каждое резюме по мере его получения, а не во время выполнения.
4. Объединить в основной сессии, самостоятельно разрешая стыки.
5. Запустить тестового суб-агента последним против интегрированного результата.

Параллелизм окупается только тогда, когда срезы действительно независимы. Если два суб-агента одновременно редактируют schema.prisma, вы не разделили работу; вы создали проблему слияния. Определите границы на уровне файлов и контрактов, а затем принудительно реализуйте их в промпте.

Когда субагенты добавляют больше накладных расходов, чем экономят?

Субагенты добавляют задержку (latency), токены и стоимость координации. Передача сводки теряет детализацию, поэтому что-либо, требующее глубокой непрерывности, плохо подходит для этой задачи. Будьте честны относительно компромисса, прежде чем обращаться к ним.

Однажды я провел бенчмарк на ветке функций (feature branch): один субагент на микросервис против одной сессии, проходящей через них по порядку. Для пяти слабо связанных сервисов параллельный режим выиграл примерно на 40 процентов по времени реального хода часов (wall-clock time). Для трех сервисов, которые использовали общую модель данных, одна сессия оказалась быстрее, потому что слияние и повторное объяснение "съели" выгоду от параллельности.

Урок: параллелизм вознаграждает за независимость и наказывает за связанность (coupling). Если ваши срезы используют общее состояние (state), не распараллеливайте их.

Каковы распространенные ошибки?

• Слишком много суб-агентов. Я ограничиваю запуск тремя или пятью. После этого стоимость координации превышает параллельный выигрыш.
• Расплывчатые запросы. «Fix the auth» не удается. «Add a JWT refresh endpoint at /auth/refresh, returning { token }, with a test» проходит.
• Отсутствие критериев успеха. Укажите, что означает «готово». «Migration applied locally and rollback tested» превосходит «handle the schema».
• Неправильный набор инструментов. Предоставьте рецензенту только инструменты для чтения. Предоставьте агенту развертывания точные команды, которые ему нужны, и ничего более широкого.
• Игнорирование сбоев. Если суб-агент возвращает ошибку, прочитайте ее. Слепое повторение тратит токены и скрывает реальную проблему.
• Пропуск слияния. Суб-агенты возвращают результаты; интеграция по-прежнему ваша ответственность. Выделите для этого реальное время.

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

Обзор

Субагенты превращают Claude Code во что-то, напоминающее небольшую команду: экономного координатора, который отправляет ограниченных работников, каждый из которых несет свой контекст и сообщает результат. Определите их в .claude/agents/, отправляйте с помощью инструмента Task и поддерживайте чистоту основной сессии, перенося тяжелые чтения и повторяющиеся роли в субагентов.

Используйте их, когда работа длительная, контекстно насыщенная или требует ограниченного набора инструментов. Пропускайте их для коротких, связанных интерактивных задач, где передача сводки приводит к слишком большим потерям. Установите границы на уровне файлов и контрактов, ограничьте запуск небольшим количеством агентов и всегда выделяйте время для самостоятельного объединения результатов.

Одно реальное предостережение: субагенты умножают пропускную способность, а не суждение. Они с радостью построят что-то неправильное параллельно в четырех изолированных контекстах. Координационная работа, определение контракта и окончательный обзор все равно ложатся на вас, поэтому рычаг только проявляется, когда срезы действительно независимы, а критерии успеха точны. Если вы хотите более глубокое понимание протокола, который обеспечивает работу многих этих инструментов, MCP explainer — хорошее следующее чтение, а в Claude Code docs описаны настройки, которые я здесь не повторял.

Кредиты изображений

• Команда разработчиков, работающих вместе за компьютерами в современном технологическом офисе — фото от Rebrand Cities на Pexels
• Яркий программный код на мониторе компьютера — фото от inna mykytas на Pexels
• Разработчик, пишущий код на ноутбуке перед несколькими мониторами — фото от Christina Morillo на Pexels
• Два программиста, сосредоточенные на кодировании бок о бок в современном офисе — фото от Rebrand Cities на Pexels