Протестировали subagents в Claude Code: параллельные AI-агенты, практика и подводные камни

Claude Code умеет запускать несколько AI-агентов параллельно — каждый со своим контекстом, набором инструментов и зоной ответственности. Anthropic называет это subagents. Мы разобрали архитектуру, протестировали ключевые сценарии и собрали практические рекомендации, которых нет в официальной документации.

Что такое subagents в Claude Code и зачем они нужны

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

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

Subagents решают эту проблему. Subagent — это изолированный экземпляр Claude со своим контекстным окном. Он получает задачу, выполняет её и возвращает только результат. Удачная аналогия от Anthropic: subagents — это вкладки браузера внутри сессии Claude Code. Можно переключиться на побочную задачу, не теряя основной нити.

Архитектура: главный агент и подагенты

Главный агент выступает оркестратором. Он анализирует задачу, определяет, какие части можно делегировать, и запускает subagents. Каждый подагент работает в собственном контексте — не видит историю разговора главного агента и не загружен чужими файлами.

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

Несколько subagents могут работать параллельно. При этом у каждого свои разрешения: один может только читать код, другой — редактировать файлы, третий — выполнять bash-команды.

Claude Code включает встроенные типы агентов:

• General-purpose — универсальный агент для сложных многошаговых задач, с доступом ко всем инструментам
• Explore — быстрый агент для поиска по кодовой базе (read-only, без возможности редактирования)
• Plan — агент-архитектор, который исследует код и предлагает стратегию реализации до начала работы

Как subagents отличаются от обычных вызовов инструментов

Здесь часто возникает путаница у тех, кто знаком с tool-use в LLM. Вызов инструмента — это одноразовое действие: прочитать файл, выполнить grep, запустить команду. Subagent — это полноценный агент, который сам решает, какие инструменты вызывать и в каком порядке.

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

	Tool-use	Subagent
Контекст	Общий с главным агентом	Собственный, изолированный
Автономность	Одна операция	Цепочка решений
Параллелизм	Ограниченный	Полноценный
Инструменты	Один конкретный	Набор под задачу

Четыре ключевых сценария применения subagents

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

1. Параллельное выполнение независимых задач

Самый очевидный сценарий: задачи не зависят друг от друга, и их можно запустить одновременно.

Примеры из практики разработки:

• Code review нескольких модулей после рефакторинга
• Генерация тестов для разных сервисов
• Одновременный анализ API-маршрутов, схемы БД и фронтенд-компонентов
• Проверка безопасности параллельно с проверкой производительности

Промпт для параллельного запуска:

Claude Code сам определяет, что три задачи независимы, и запускает три subagent параллельно. По данным Anthropic, три параллельных агента завершают работу быстрее, чем один последовательный. Но выигрыш масштабируется не линейно — накладные расходы на запуск и синтез результатов съедают часть ускорения.

Сигнал к применению: задач три и больше, между ними нет зависимостей, каждая требует чтения 10+ файлов.

2. Изолированные git worktrees: безопасная работа без конфликтов

Параметр isolation: "worktree" создаёт для subagent временное рабочее дерево Git. Агент работает в собственной ветке и директории, не затрагивая основной репозиторий.

Это решает конкретную проблему: когда два агента одновременно редактируют файлы в одном репозитории, возникают конфликты. Worktree исключает их на уровне архитектуры.

Сценарий: рефакторинг модуля авторизации и параллельная разработка нового API-эндпоинта. Оба агента работают над общей кодовой базой, но в изолированных worktrees. Результаты сливаются через стандартный git merge после завершения.

Важный нюанс: если subagent не внёс изменений, worktree автоматически удаляется. Если изменения есть — возвращается путь к worktree и имя ветки для последующей интеграции.

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

3. Делегирование специализированным агентам

Главный агент — стратег. Он декомпозирует задачу и передаёт части специалистам. В Claude Code можно создать кастомных агентов с жёстко заданной специализацией.

Кастомный агент — это markdown-файл в .claude/agents/ (уровень проекта, доступен команде) или ~/.claude/agents/ (уровень пользователя, доступен во всех проектах). У каждого своё системное сообщение, набор инструментов и опционально — модель.

Пример: агент для security-ревью:

После создания Claude автоматически делегирует подходящие задачи этому агенту. Можно вызвать и явно: «Попроси security-reviewer проверить staged-изменения».

Ключевой момент: поле description определяет, когда Claude решит делегировать задачу. Пишите конкретные условия срабатывания: «проверяет код перед коммитами, затрагивающими auth» маршрутизирует точнее, чем абстрактное «эксперт по безопасности».

Для автоматического создания агента используйте команду /agents — она проведёт через настройку интерактивно и сгенерирует файл из описания.

4. Управление контекстным окном через декомпозицию задач

Контекстное окно — конечный ресурс. В больших проектах оно заполняется быстро: прочитал 20 файлов, запустил несколько команд — и модель уже теряет детали из начала сессии.

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

Параметр run_in_background: true позволяет запускать subagent в фоне. Основная сессия продолжает работу, а когда фоновый агент завершится — результат приходит автоматически. В интерфейсе Claude Code то же самое делает комбинация Ctrl+B: отправить агента в фон и продолжить работу. Проверить статус фоновых задач можно командой /tasks.

Практический ориентир от Anthropic: если задача требует чтения более 10 файлов или включает 3+ независимые подзадачи — это сигнал к декомпозиции через subagents.

Лучшие практики: как правильно настраивать subagents

Официальная документация Anthropic объясняет, что делают subagents. Здесь разберём, как использовать их эффективно — рекомендации, собранные из практического тестирования.

Как писать эффективные промпты для subagents

Главное правило: subagent не видит контекст главного агента. Промпт должен быть полностью самодостаточным. Anthropic формулирует это так: «Brief the agent like a smart colleague who just walked into the room» — инструктируй агента, как умного коллегу, который только что вошёл в комнату и ничего не знает о контексте.

Плохой промпт:

Исправь баг, который мы обсуждали.

Subagent не знает, какой баг обсуждался. У него нет истории разговора.

Хороший промпт:

Структура эффективного промпта для subagent:

• Контекст — что делаем и зачем, достаточный для принятия решений
• Конкретные координаты — файлы, строки, функции, если известны
• Ожидаемый результат — diff, отчёт, список файлов, рекомендации
• Ограничения — что НЕ менять, какие инструменты использовать
• Формат ответа — «краткий отчёт» vs «полный анализ с примерами кода»

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

Управление инструментами и разрешениями

Принцип минимальных привилегий применим и к AI-агентам. Если subagent должен только исследовать код — дайте ему Read, Grep, Glob. Если должен вносить изменения — добавьте Edit и Write. Доступ к Bash — только когда нужно запускать команды.

В определении кастомного агента набор инструментов задаётся явно:

Зачем ограничивать:

• Предсказуемость — агент с read-only доступом гарантированно не изменит файлы
• Безопасность — минимизация поверхности атаки при анализе внешнего или незнакомого кода
• Экономия токенов — агент не тратит контекст на попытки использовать недоступные инструменты

Параметр isolation: "worktree" добавляет ещё один слой защиты: даже если агент вносит изменения, они изолированы от основной ветки.

Политики через CLAUDE.md

Кастомные агенты определяют, кто выполняет работу. Файл CLAUDE.md определяет правила, по которым Claude решает, когда делегировать. Claude читает этот файл при старте каждой сессии, поэтому поведение остаётся консистентным между сеансами и участниками команды.

Пример политики в CLAUDE.md:

С такой политикой каждый запрос на ревью автоматически идёт через subagent — никому не нужно помнить и указывать это вручную.

Обработка ошибок и мониторинг

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

Инструменты мониторинга:

• /tasks — список активных фоновых задач
• TaskOutput — получить результат конкретной задачи
• TaskStop — остановить зависший subagent

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

Практика: subagents в реальных задачах

Мы протестировали несколько сценариев на внутренних проектах VibeLab.

Параллельный code review монорепозитория

Задача: проверить 10+ модулей после крупного обновления зависимостей. Последовательный подход — это часы работы.

Подход с subagents: параллельный запуск агентов с типом Explore на каждый модуль. Каждый агент получает конкретную инструкцию: «Проверь модуль X на совместимость с обновлённой версией библиотеки Y, найди deprecated-вызовы, предложи замены с примерами кода».

Результат: время ревью сократилось в разы по сравнению с последовательным анализом. Каждый агент работал в компактном релевантном контексте — без шума от соседних модулей.

Наблюдение: при запуске более 5-6 параллельных агентов прирост скорости начинает уменьшаться. Оптимум — 3-5 одновременных агентов.

Параллельная разработка с worktree-изоляцией

Протестировали сценарий с двумя worktree-агентами: один рефакторил middleware авторизации, второй добавлял новый API-эндпоинт.

Что сработало: оба агента работали параллельно без конфликтов, каждый в своей ветке. Merge прошёл без проблем.

Что потребовало внимания: когда зоны изменений пересекаются (оба агента правят один файл), при merge возникают конфликты. Решение: на этапе декомпозиции чётко разделять зоны ответственности агентов. Правило простое — один файл принадлежит одному агенту.

Технические ограничения и как с ними работать

Стоимость и лимиты API

Каждый subagent — отдельная сессия с собственным потреблением токенов. Запуск 5 параллельных агентов означает примерно пятикратное увеличение расхода за единицу времени.

Рекомендации по оптимизации:

• Ограничивайте глубину вложенности. Subagent, запускающий sub-subagent — это удвоение накладных расходов. Одного уровня делегирования достаточно для большинства задач.
• Используйте лёгкие модели для простых задач. Параметр model: haiku снижает стоимость для рутинных операций вроде поиска по коду.
• Не параллельте тривиальное. Запуск subagent для чтения одного файла — чистый оверхед.

Координация между агентами: race conditions

Когда несколько агентов работают параллельно над одним репозиторием без worktree-изоляции, возникают классические проблемы конкурентного доступа.

Паттерны решения:

• Worktrees — каждый агент в своём рабочем дереве, конфликты исключены
• Разделение зон ответственности — в промпте чётко указать, какие файлы принадлежат каждому агенту
• Последовательная интеграция — агенты работают параллельно, но merge результатов идёт последовательно

Subagents vs другие подходы

Подход	Подходит	Не подходит
Bash-скрипты	Детерминированные задачи: линтинг, сборка, деплой	Задачи, требующие понимания контекста
Tool-use цепочки	Простые последовательности: прочитай → измени → проверь	Многошаговые задачи с ветвлением логики
Subagents	Параллельные задачи, требующие анализа и решений	Тривиальные операции
Внешние оркестраторы (LangChain, CrewAI)	Кросс-модельные пайплайны, сложная маршрутизация	Задачи внутри одного Claude Code сеанса

Subagents выигрывают там, где задача требует интеллектуального анализа и автономных решений. Bash-скрипт не определит, безопасен ли рефакторинг. Tool-use цепочка не адаптируется к неожиданным находкам. Subagent — может, потому что это полноценный агент со своим reasoning-циклом.

Итог: subagents как новый слой agentic-разработки

Subagents в Claude Code — это не просто параллельный запуск нескольких LLM-сессий. Это архитектурный паттерн: декомпозиция сложных задач на автономные единицы с изолированным контекстом, чёткими разрешениями и контролируемым результатом.

Ключевые паттерны, которые работают на практике:

• Параллелизм для независимых задач — code review, тесты, анализ модулей
• Worktree-изоляция для безопасной параллельной разработки без конфликтов
• Кастомные агенты для повторяющихся специализированных задач с фиксированными правилами
• Фоновые агенты для побочных задач, не блокирующих основную работу

Если хотите попробовать subagents — начните с простого. Откройте Claude Code и введите:

Этот промпт задействует Explore-агента и вернёт структурированный результат, не засоряя основной контекст. Дальше — наращивайте: добавьте второй параллельный агент, попробуйте worktree-изоляцию, создайте первого кастомного агента под задачи вашей команды.

Мы в VibeLab продолжаем исследовать agentic-подходы к разработке — от subagents и кастомных MCP-инструментов до полноценных AI-пайплайнов. Публикуем практические разборы по мере тестирования новых паттернов на реальных проектах.

---

Подписывайтесь на наш канал: @vibelogia

Поделимся опытом

hello@vibelab.ru

8 800 201 85 68

Написать в Telegram