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

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

Что такое subagent и чем он отличается от основного диалога

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

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

Агент живёт в файле .claude/agents/<name>.md в корне проекта (либо в ~/.claude/agents/ для личных агентов, доступных во всех проектах). Минимальная анатомия такого файла:

---
name: resource-builder
description: Собирает NestJS-ресурс CoffeeCRM (module + controller + service + entity + DTO) по конвенциям проекта. Использовать, когда нужно добавить новый CRUD-ресурс в backend.
tools: Read, Edit, Write, Bash, Grep
---

Ты — инженер, собирающий ресурсы строго по конвенциям проекта.
Читай CLAUDE.md и существующий ресурс menu/ как образец структуры.
НЕ трогай app.module.ts — регистрацию делает оркестратор отдельным шагом.
Верни кратко: список созданных файлов и какие эндпоинты появились.

Обязательны только name и description. Поле description — это триггер: Claude Code смотрит на него, чтобы решить, кого позвать. Хорошее описание отвечает на вопрос «КОГДА это использовать», а не просто называет агента.

Технически делегирование выполняется инструментом Task (в новых версиях — Agent): основной агент вызывает его, передавая задачу и тип агента. Точный синтаксис меняется между версиями — сверяйтесь с актуальной документацией через Context7 MCP.

Три сигнала, что задачу пора делегировать

Делегирование — не бесплатная операция: каждый subagent стартует с нуля и тратит токены на восстановление контекста. Поэтому сначала спросите себя по трём критериям.

Изоляция контекста. Задача нагенерит много шума (длинные логи, поиск по большой кодовой базе, многошаговые правки), который не нужен в основном диалоге? Делегируйте. Весь этот шум осядет в контексте subagent, а вы получите только итог.

Узкая роль. Нужен «другой режим мышления»? Ревьюер кода и автор кода — это разные режимы. Ревьюер с суженным набором инструментов (только чтение, без Write) смотрит на код свежим взглядом и не защищает его. В одном диалоге эти роли мешают друг другу.

Параллелизм. Есть несколько независимых задач, которые можно делать одновременно? Делегируйте каждую отдельному агенту — они пойдут параллельно.

Если ни одного критерия нет и контекст уже под рукой — ведите задачу сами. Например, прочитать один файл и поправить опечатку: overhead на запуск агента не окупится.

Подробнее о базовых принципах делегирования — в статье «Что и когда делегировать AI-агенту».

Параллельный запуск: почему нельзя просто запустить пятерых сразу

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

Все агенты в одной рабочей копии видят одни и те же файлы и пишут в одну копию git. Два агента одновременно дописывают строку в app.module.ts — и затирают работу друг друга. Даже если их файлы разные, общая рабочая копия создаёт гонку состояний: один агент делает git add . и захватывает чужие недописанные файлы.

Нужна физическая изоляция: каждому агенту — своя рабочая копия, своя папка, своя ветка.

git worktree: один репозиторий, несколько рабочих копий

git worktree — встроенная возможность git иметь несколько рабочих копий одного репозитория в разных папках. История общая, а рабочие файлы у каждой копии свои. Это не разные репозитории — один репозиторий с несколькими «рабочими столами».

На практике: создаёте три worktree на трёх ветках от основной (git worktree add <путь> -b <ветка>), в каждом запускаете Claude Code с agentom и своим заданием. Агенты работают физически изолированно и не могут затереть работу друг друга.

Что это даёт сверх параллелизма:

• Локализация сбоев. Если агент C нагенерил мусор — мусор только в его worktree и его ветке. Остальные две ветки чистые. Откатываете один worktree, не трогая остальные.
• Чистое сведение. Ветки сливаются осознанно, каждый вклад виден отдельно.

Worktree — это локально и бесплатно, часть стандартного git.

Паттерн «раздели → распараллель → сведи»

Разберём на примере CoffeeCRM (Next.js + NestJS), сквозного проекта курса. Нужно собрать пять сущностей backend: Client, Order, OrderItem, Employee, Shift.

Шаг 1 — Раздели на независимые куски. Главное правило: задачи не должны трогать одни и те же файлы. Разбиваем по смысловой связи:

• Worktree A: Client — самостоятельная сущность.
• Worktree B: Order + OrderItem — позиция без заказа бессмысленна, держим вместе.
• Worktree C: Employee + Shift — смена без сотрудника бессмысленна, держим вместе.

Шаг 2 — Распараллель. Каждому куску — свой worktree, своя ветка, один и тот же агент resource-builder. Каждому передаём задание с явным «НЕ трогай app.module.ts»:

# В worktree A (ветка feat/client):
Собери ресурс Client (name, phone, email, loyaltyPoints). Не трогай app.module.ts.

# В worktree B (ветка feat/order):
Собери ресурсы Order и OrderItem (Order: clientId, status, total; OrderItem: orderId, menuItemId, qty, price). Не трогай app.module.ts.

# В worktree C (ветка feat/employee):
Собери ресурсы Employee и Shift (Employee: name, role; Shift: employeeId, startAt, endAt). Не трогай app.module.ts.

Три агента работают параллельно. Три ресурса собираются примерно за время одного.

Шаг 3 — Сведи. Возвращаемся в основную ветку module-4, сливаем три ветки. Поскольку агенты не трогали общие файлы — слияние проходит без конфликтов.

Затем отдельным, не параллельным шагом регистрируем модули:

// backend/src/app.module.ts
@Module({
  imports: [
    // ...существующее
    ClientModule,
    OrderModule,    // включает OrderItem
    EmployeeModule, // включает Shift
  ],
})
export class AppModule {}

Железное правило: общий слой никогда не собирается параллельно. app.module.ts, корневой роутинг, общие провайдеры — точка встречи всех ресурсов. Параллельные правки здесь гарантированно дадут конфликт. Именно поэтому в промпте каждого агента стоит запрет трогать этот файл.

После сведения удаляем отработавшие worktree (git worktree remove), чтобы не засорять проект.

Как действовать при сбое

Изоляция решает и задачу отказоустойчивости. Если агент C нагенерил кривой код:

1. Ветки A и B чистые — их не трогаем.
2. Откатываем только ветку feat/employee (или удаляем worktree и создаём заново).
3. Перезапускаем только агента C.

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

Что дальше

Subagents — это следующий уровень после базовой работы с Claude Code. Сначала стоит разобраться, что такое Claude Code и как устроен цикл агента, а также понять роль плагинов и MCP — agenty умеют переиспользовать их инструменты напрямую через поле skills в frontmatter файла агента.

Паттерн «раздели → распараллель → сведи» переносится на любой стек: режьте по независимым модулям, давайте каждому свой worktree, общий слой (DI-контейнер, роутер, манифест зависимостей) собирайте отдельным шагом после сведения.

Если хотите освоить это системно — от создания первого агента до оркестрации и сборки переиспользуемых плагинов на реальном проекте — это весь Модуль 4 полного курса по Claude Code.