1. Что такое субагенты в Claude Code: от последовательного к параллельному мышлению

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

Для преодоления этой проблемы архитектура Claude Code поддерживает концепцию субагентов — изолированных автономных экземпляров модели, которым делегируются независимые части общей работы.

mermaid

flowchart TD subgraph Sequential ["Последовательный режим (Single Session)"] S1["Задача 1"] --> S2["Задача 2"] --> S3["Задача 3"] --> S4["Финальный результат"] end subgraph Parallel ["Параллельный режим (Subagent Orchestration)"] P_Parent["Родительская сессия Claude Code"] --> P1["Субагент 1: Auth"] P_Parent --> P2["Субагент 2: Validation"] P_Parent --> P3["Субагент 3: Formatting"] P1 --> P_Join{"Агрегация результатов"} P2 --> P_Join P3 --> P_Join P_Join --> P_Done["Готовый pull request / отчет"] end

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

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

Примечание

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

2. Критерии параллелизации: когда разделять задачи, а когда работать последовательно

Параллелизация не является универсальным решением для всех задач. Ее эффективность напрямую зависит от взаимной независимости рабочих процессов. Попытка запустить зависимые шаги одновременно приводит к состояниям гонки (race conditions) и логическим конфликтам.

Сценарий разработки	Оптимальный режим	Техническое обоснование
Генерация unit-тестов для независимых утилит	Параллельный	Модули не зависят друг от друга, отсутствуют общие зависимости
Многовекторный аудит безопасности, SEO и UI	Параллельный	Каждый агент анализирует систему под своим углом в режиме чтения
Проектирование схемы БД и генерация миграций	Последовательный	Создание миграции невозможно до завершения проектирования схемы
Редактирование одного и того же файла конфигурации	Последовательный	Одновременная запись несколькими агентами вызывает перезапись данных
Пакетный рефакторинг изолированных компонентов	Параллельный	Каждый UI-компонент изолирован в отдельном файле

Когда параллелизация противопоказана

Каскадная зависимость данных: Если шаг B напрямую использует артефакты шага A. Например: сначала провести аудит базы данных, спроектировать нормализованную схему и лишь затем создать миграцию Prisma.
Общие файлы для записи: Если Агент 1 и Агент 2 одновременно попытаются модифицировать app.ts или package.json, изменения одного из них будут утеряны.
Задачи, требующие интерактивного уточнения требований: Если критерии не ясны до конца и инженеру необходимо постоянно направлять модель через вопросы и ответы, задачу следует оставить в одиночной интерактивной сессии.

Внимание

Главное правило параллелизации: перед запуском пула субагентов ответьте на вопрос: «Может ли каждый агент выполнить свою задачу от начала до конца без ожидания промежуточных ответов от других?». Если ответ «нет» — работайте исключительно последовательно.

3. Архитектура и механика запуска субагентов через Task Tool

Внутри Claude Code координация субагентов выполняется через встроенный системный инструмент Task tool. Когда модель в родительской сессии определяет, что запрос можно декомпозировать на независимые подзадачи, она автоматически инициирует фоновые рабочие процессы.

Разработчику редко требуется вручную формировать низкоуровневые вызовы Task tool — достаточно структурировать инструкции на естественном языке.

Архитектура запуска субагентов Claude Code и агрегация результатов в родительскую сессию Збільшити

Архитектура запуска субагентов Claude Code и агрегация результатов в родительскую сессию

Жизненный цикл параллельного выполнения

Диспетчеризация задачи: Родительская сессия получает составной промпт (например, написание тестов для пяти утилит: auth.ts, validation.ts, formatting.ts, api-client.ts, cache.ts).
Создание изолированных контекстов: Инициализируются отдельные субагенты, каждый из которых получает целевой файл и изолированное задание.
Автономное выполнение: Каждый агент параллельно анализирует исходный код своего модуля, типизацию, генерирует тестовый набор и проверяет его запуск.
Агрегация результатов: Родительская сессия дожидается завершения всех процессов, собирает итоговые статусы и предоставляет разработчику сводный отчет.

4. Общий vs изолированный контекст: что видят субагенты

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

Общий и изолированный контекст субагентов: что доступно всем агентам, а что остается приватным Збільшити

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

Системный ресурс / Состояние	Доступно всем агентам?	Характеристика доступа
Файлы проекта на диске	Да	Все агенты имеют одинаковые права на чтение и запись в репозитории
Инструкции CLAUDE.md	Да	Каждый субагент автоматически наследует глобальные правила проекта
История родительского диалога	Нет	Изолированный контекст; агент видит только свой целевой промпт
Изменения в файлах на лету	Требует осторожности	Отсутствует автоблокировка файлов; одновременная запись приводит к коллизиям

Принцип единого владельца файла (Single Writer Principle)

Чтобы предотвратить повреждение кодовой базы при параллельной работе, придерживайтесь четкого распределения файлов для записи:

text

Корректное разделение (без конфликтов): Субагент 1 ──► src/utils/auth.test.ts (создает новый файл) Субагент 2 ──► src/utils/validation.test.ts (создает новый файл) Субагент 3 ──► src/utils/formatting.test.ts (создает новый файл) Недопустимое разделение (коллизия): Субагент 1 ──► src/index.ts (изменяет строки экспорта) Субагент 2 ──► src/index.ts (изменяет строки экспорта) Субагент 3 ──► src/index.ts (изменяет строки экспорта)

Важно

Если нескольким субагентам необходимо зарегистрировать созданные модули в едином индексном файле (src/index.ts или src/routes.ts), не поручайте это параллельным агентам. Пусть каждый агент создаст свой изолированный файл, а добавление экспортов выполнит родительская сессия после слияния результатов.

5. Паттерны формулирования промптов для запуска параллельных агентов

Хотя Claude Code умеет самостоятельно выявлять параллельные задачи, явная инструкция на одновременное выполнение устраняет неопределенность и сокращает время планирования.

Проверенные шаблоны промптов

6. Четыре ключевые схемы параллельной работы: готовые паттерны

Опыт командной разработки с Claude Code позволил сформировать четыре проверенных шаблона параллельной оркестрации.

mermaid

flowchart LR subgraph P1 ["1. Research Fan-Out"] RF_Q["Архитектурный вопрос"] --> RF1["PostgreSQL"] RF_Q --> RF2["MongoDB"] RF_Q --> RF3["SQLite"] RF1 & RF2 & RF3 --> RF_M["Сравнительная матрица"] end subgraph P2 ["2. Audit Swarm"] AS_Code["Репозиторий"] --> AS1["Security"] AS_Code --> AS2["Performance"] AS_Code --> AS3["A11y"] AS_Code --> AS4["Code Quality"] AS1 & AS2 & AS3 & AS4 --> AS_R["Сводный отчет аудита"] end

Research Fan-Out (Параллельное исследование)

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

Audit Swarm (Мультидисциплинарный аудит)

Наиболее эффективный по времени паттерн. Вместо того чтобы один агент четыре раза последовательно сканировал весь проект, четыре специализированных агента запускаются одновременно в режиме чтения (read-only), что исключает любые конфликты записи.

Batch Processor (Пакетный рефакторинг)

Используется для масштабных типовых трансформаций в десятках независимых файлов:

Перевод устаревших классовых компонентов React на функциональные хуки в папке src/components/.
Перевод тестовой базы с Jest на Vitest.
Обновление путей устаревших импортов при миграции в монорепозиторий.

Feature Sprint (Параллельная разработка фичей)

Одновременное создание нескольких независимых UI-виджетов или API-эндпоинтов:

Агент 1 реализует переключатель темы (ThemeToggle.tsx + контекст).
Агент 2 разрабатывает строку глобального поиска (SearchBar.tsx + поисковый хук).
Агент 3 создает выпадающее меню уведомлений (NotificationsDropdown.tsx).

7. Параллельный запуск через CLI: Headless-режим и флаг -p

Помимо интерактивной сессии Claude Code, доступен инструмент системной автоматизации — запуск Claude в неинтерактивном (headless) режиме с помощью флага -p (--print). В этом режиме агент принимает запрос через аргумент командной строки, выполняет задачу автономно и выводит результат в терминал.

Это позволяет использовать возможности управления фоновыми процессами в Unix-оболочках (&) и команду синхронизации wait:

bash

# Одновременный запуск трех фоновых процессов Claude Code в bash/zsh claude -p "Write unit tests for src/utils/auth.ts using Vitest" & PID_AUTH=$! claude -p "Write unit tests for src/utils/validation.ts using Vitest" & PID_VAL=$! claude -p "Write unit tests for src/utils/formatting.ts using Vitest" & PID_FMT=$! # Ожидание завершения всех параллельных процессов echo "Запущены фоновые агенты с PID: $PID_AUTH, $PID_VAL, $PID_FMT. Ожидание..." wait $PID_AUTH $PID_VAL $PID_FMT echo "Все тесты успешно сгенерированы! Запуск проверки..." npm test

Преимущества параллелизации через CLI:

Автономность без участия человека: Подходит для ночных CI/CD скриптов, генерации документации или запуска предрелизных проверок.
Изоляция на уровне процессов ОС: Каждый рабочий процесс claude запускается в собственном адресном пространстве операционной системы.
Индивидуальное логирование: Вывод каждого процесса легко направить в отдельный файл: claude -p "..." > logs/auth.log 2>&1 &.

Совет

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

8. Экономика токенов, лимиты API и оптимизация расходов

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

text

Последовательная сессия (1 контекстное окно): [Системный промпт] + [Задача 1] ──► [Задача 2] ──► [Задача 3] Итоговые токены: Базовый контекст + ΔT1 + ΔT2 + ΔT3 Параллельные субагенты (3 независимых контекстных окна): Субагент 1: [Базовый контекст + Задача 1] Субагент 2: [Базовый контекст + Задача 2] Субагент 3: [Базовый контекст + Задача 3] Итоговые токены: (3 × Базовый контекст) + ΔT1 + ΔT2 + ΔT3

Четыре правила оптимизации расходов

Точно очерченный скоуп задач: Не давайте агенту общие команды вроде «Поправь тесты в проекте». Указывайте конкретный файл: «Напиши 3 unit-теста для функции parseJwt в src/utils/auth.ts».
Фильтрация тяжелых файлов: Добавьте объемные сгенерированные файлы и дампы в .claudeignore, чтобы субагенты не расходовали контекст на чтение бесполезных данных.
Использование -p для тривиальных задач: Неинтерактивный режим не накапливает диалоговую историю и возвращает только целевой артефакт.
Объединение мелких правок: Запускать субагента ради изменения одного стиля в CSS нерационально — затраты на инициализацию контекста превысят ценность результата.

9. Практический воркшоп: пошаговая реализация от тестов до Audit Swarm

Закрепим теоретические концепции на пошаговом практическом примере.

Шаг 1. Выбор изолированных модулей и подготовка

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

src/utils/auth.ts
src/utils/validation.ts
src/utils/formatting.ts

Убедитесь, что соответствующие тестовые файлы отсутствуют или требуют расширения.

Шаг 2. Формулирование и запуск параллельного промпта

Запустите интерактивную сессию Claude Code в терминале и введите следующий запрос:

markdown

Сгенерируй модульные тесты для следующих трех файлов параллельно через субагентов: 1. src/utils/auth.ts -> сохрани тесты в src/utils/auth.test.ts 2. src/utils/validation.ts -> сохрани тесты в src/utils/validation.test.ts 3. src/utils/formatting.ts -> сохрани тесты в src/utils/formatting.test.ts Требования к тестам: - Используй Vitest и проверки граничных значений (null, undefined, пустые строки). - Не изменяй исходные файлы утилит.

Шаг 3. Мониторинг выполнения и проверка тестов

Следите за выводом в терминале. Claude Code создаст дочерние задачи, параллельно обработает каждый модуль и выведет статусы завершения.

Запустите проверку тестов в проекте:

bash

npm run test:run

Все три тестовых набора должны успешно пройти валидацию без конфликтов в файловой системе.

Шаг 4. Запуск Audit Swarm для анализа репозитория

Теперь протестируйте аналитический паттерн Audit Swarm. Отправьте запрос:

markdown

Проведи комплексный аудит кодовой базы через четырех параллельных субагентов: - Агент Безопасности: проверка на уязвимости XSS, CSRF, небезопасные npm-пакеты и секреты в коде. - Агент Производительности: анализ размера бандла, лишних ререндеров и тяжелых библиотек. - Агент Доступности (a11y): проверка семантических тегов HTML, фокус-ловушек и ARIA-атрибутов. - Агент Качества кода: поиск мертвого кода, дублирования и использования типа any. Сформируй единый сводный отчет с приоритетами исправлений (High / Medium / Low).

10. Итоговая шпаргалка и чек-лист готовности к параллелизации

Используйте этот чек-лист перед запуском масштабных параллельных задач в Claude Code.

Чек-лист готовности к параллельной работе

Независимость задач: Ни одна из подзадач не требует промежуточных данных от соседних агентов.
Изоляция записи в файлы: Каждый агент модифицирует только свой изолированный файл; отсутствует одновременный доступ к общим конфигурациям.
Четкие границы промпта: Указаны конкретные целевые пути к файлам, технологический стек и критерии завершения.
Экономическая обоснованность: Выигрыш во времени разработки оправдывает мультипликацию контекстных токенов.
Очистка контекста: Тяжелые директории исключены через .claudeignore.

Матрица выбора инструментов

Задача	Рекомендуемый подход	Интерфейс выполнения
Генерация тестов для 5+ модулей	Интерактивный Claude Code или CLI `-p`	`claude -p "..." &`
Многопрофильный аудит проекта	Audit Swarm в сессии	Запрос с 4 специализированными агентами
Сравнение библиотек и технологий	Research Fan-Out	Сведение результатов в общую таблицу
Глубокий рефакторинг ядра системы	Последовательная сессия (Single Session)	Интерактивная сессия с пошаговым ревью инженером