# Субагенти та паралельна робота в Claude Code: як виконувати кілька завдань одночасно

> Повний посібник із паралелізації завдань у Claude Code: архітектура субагентів, спільний та ізольований контекст, патерни Fan-Out і Swarm, робота через CLI з прапорцем -p та оптимізація токенів.

## 1. Що таке субагенти в Claude Code: від послідовного до паралельного мислення

Стандартна робоча сесія **Claude Code** функціонує в суворо послідовному режимі (single-threaded event loop). Користувач відправляє запит, агент зчитує контекст, виконує пошук, редагує файл, запускає лінтер або тести і лише після завершення всього ланцюжка переходить до наступної задачі. Коли проєкт масштабується, а перед розробником постають десятки взаємонезалежних завдань, такий послідовний підхід призводить до невиправданих часових затримок та швидкого засмічення контекстного вікна.

Для подолання цього обмеження в архітектуру 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
```

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

- **Власне ізольоване контекстне вікно:** Субагент не перевантажений попередньою довгою історією діалогу основної сесії, фокусуючись виключно на наданому тасці.
- **Спільний доступ до файлової системи:** Субагент може читати структуру каталогу, проєктні конфігурації та файли вихідного коду на рівних правах з головним процесом.
- **Асинхронне виконання:** Кілька субагентів працюють одночасно, скорочуючи загальний час виконання (wall-clock time) пропорційно кількості паралельних потоків.
- **Автоматична агрегація:** Після завершення роботи субагент формує структуроване резюме, повертає його до батьківської сесії та звільняє виділені ресурси.

> [!NOTE]
> Найпростіша ментальна модель субагентів — це ефективний менеджмент розробки. Замість того щоб Senior-інженер власноруч писав документацію для п'яти мікросервісів по черзі, він створює 5 окремих тасок і передає їх паралельним виконавцям, перевіряючи лише фінальний результат кожного.

---

## 2. Критерії паралелізації: коли розділяти задачі, а коли працювати послідовно

Паралелізація не є універсальною панацеєю. Її ефективність безпосередньо залежить від ступеня взаємної незалежності завдань. Спроба паралельного виконання взаємопов'язаних етапів неминуче спричиняє race conditions (стан гонитви) та логічні колізії.

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

### Коли паралелізація протипоказана

1. **Каскадна залежність результатів:** Якщо крок B використовує вихідні дані кроку A. Наприклад: спочатку провести аудит схеми бази даних, спроєктувати нову структуру і лише після цього згенерувати Prisma-міграцію.
2. **Спільні точки модифікації файлів:** Якщо Агент 1 та Агент 2 одночасно спробують внести зміни в один і той самий файл `app.ts` або `package.json`, один із записів буде перезаписаний або пошкоджений.
3. **Задачі, що потребують ітеративного людського фідбеку:** Якщо вимоги не визначені остаточно й розробнику необхідно постійно коригувати курс через уточнюючі запитання, задача має залишатися в інтерактивній одиночній сесії.

> [!WARNING]
> Золоте правило паралелізації: перш ніж запускати пул агентів, дайте чітку відповідь на запитання: **«Чи може кожен агент виконати свою задачу від початку до кінця без очікування проміжних відповідей від інших?»**. Якщо відповідь «ні» — працюйте виключно послідовно.

---

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

Усередині рушія Claude Code оркестрація субагентів здійснюється через системний інструмент **Task tool**. Коли модель у головній сесії розуміє, що завдання складається з ізольованих компонентів, вона ініціює дочірні фонові процеси.

Користувачеві зазвичай не потрібно вручну викликати системні JSON-інструкції Task tool — достатньо чітко сформулювати розбивку в запиті або дозволити Claude Code декомпонувати задачу самостійно.

![Архітектура запуску субагентів Claude Code та агрегація результатів в основну сесію](/api/guides-media/ai_agents/claude-code-subagents-and-parallel-work/images/claude-code-subagents-and-parallel-work-step-01.webp)

### Життєвий цикл паралельного виконання

1. **Диспетчеризація задачі:** Головна сесія отримує складний промпт (наприклад, написання тестів для п'яти утиліт: `auth.ts`, `validation.ts`, `formatting.ts`, `api-client.ts`, `cache.ts`).
2. **Формування дочірніх контекстів:** Створюються окремі субагенти, кожен з яких отримує персональне завдання та шлях до цільового файлу.
3. **Автономна робота:** Кожен агент паралельно зчитує вихідний код свого модуля, досліджує типи даних, генерує відповідний тестовий набір і перевіряє його запуск.
4. **Зворотне злиття (Aggregation):** Головна сесія чекає завершення всіх потоків, отримує фінальні статуси виконання та презентує розробнику консолідований звіт.

---

## 4. Спільний vs ізольований контекст: що бачать субагенти

Найчастіша помилка розробників-початківців — припущення, що субагенти мають телепатичний зв'язок між собою або знають усе, про що йшлося на 50-му кроці головного діалогу. Насправді модель дотримується чіткої політики розмежування пам'яті.

![Спільний та ізольований контекст субагентів: що доступно всім агентам, а що залишається приватним](/api/guides-media/ai_agents/claude-code-subagents-and-parallel-work/images/claude-code-subagents-and-parallel-work-extra-02.webp)

| Ресурс або стан системи | Спільний для всіх агентів? | Технічний опис доступу |
| :--- | :---: | :--- |
| **Файли проєкту на диску** | **Так** | Усі агенти мають доступ на читання та запис до робочої директорії |
| **Правила CLAUDE.md** | **Так** | Кожен агент автоматично ініціалізується з правилами проєкту та стеку |
| **Історія попереднього діалогу** | **Ні** | Ізольоване вікно; субагент бачить лише свій безпосередній промпт |
| **Зміни у відкритих файлах** | **Потребує обережності** | Відсутні механізми авто-блокування файлів; ризик колізій при записі |

### Забезпечення безпеки файлового запису (Write Ownership)

Щоб уникнути пошкодження кодової бази при паралельній роботі, дотримуйтесь принципу **єдиного власника файлу**:

```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  (модифікує рядок експорту)
```

> [!IMPORTANT]
> Якщо кільком паралельним агентам необхідно зареєструвати створені модулі в єдиному індексному файлі (`src/index.ts` або `src/routes.ts`), **не доручайте** це субагентам. Нехай агенти лише створять свої ізольовані файли, а реєстрацію імпортів в індексному файлі виконає батьківська сесія після повернення всіх результатів.

---

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

Хоча Claude Code має евристики для виявлення паралельних задач, явна вказівка на одночасне виконання усуває будь-яку двозначність і оптимізує час диспетчеризації.

### Зразки ефективного формулювання запитів

:::tabs
@tab Базовий розподіл
```markdown
Виконай наступні три завдання паралельно через окремих субагентів:

1. Реалізуй валідацію полів у компоненті форми реєстрації (src/components/RegisterForm.tsx).
2. Створи компонент скелетної анімації завантаження для дашборду (src/components/DashboardSkeleton.tsx).
3. Додай підтримку пагінації у хук завантаження користувачів (src/hooks/useUsers.ts).

Переконайся, що кожен агент працює лише зі своїм файлом і не змінює спільні конфігурації.
```
@tab Fan-Out аналіз
```markdown
Працюй паралельно через субагентів:

- Агент 1: Досліди офіційну документацію Stripe API щодо обробки webhook-подій підписок.
- Агент 2: Проаналізуй нашу поточну реалізацію в модулі src/services/billing.ts на предмет вразливостей.
- Агент 3: Спроєктуй TypeScript-інтерфейси для нових вхідних DTO об'єктів у src/types/stripe.ts.

Після завершення зведи результати в єдиний план рефакторингу в головній сесії.
```
@tab Пакетний аудит
```markdown
Проведи паралельний аудит кодової бази за чотирма напрямками:

- Напрямок А (Безпека): Сканування на предмет витоку секретів у git-історії та безпеки запитів до бази даних.
- Напрямок Б (Швидкодія): Пошук N+1 запитів у контролерах та виявлення важких імпортів у клієнтських бандлах.
- Напрямок В (Типізація): Перевірка наявності небезпечних типів "any" та пропущених обов'язкових полів інтерфейсів.
- Напрямок Г (Accessibility): Аудит наявності атрибутів aria-label та контрастності кольорів у Tailwind-класах.
```
:::

---

## 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 class-компонентів у functional hooks у каталозі `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` запускається в окремому адресному просторі операційної системи.
- **Логування у файли:** Вивід кожного процесу можна легко перенаправити у власний log-файл: `claude -p "..." > logs/auth.log 2>&1 &`.

> [!TIP]
> У терміналі оператор `&` в кінці команди відправляє процес у бекграунд, звільняючи термінал для негайного запуску наступної команди. Вбудована команда `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
```

### Чотири правила контролю бюджету токенів

1. **Вузько окреслений скоуп:** Не давайте агенту загальне доручення на кшталт «Зроби порядок у тестах проєкту». Формулюйте конкретно: «Напиши 3 unit-тести для функції parseJwt у src/utils/auth.ts».
2. **Фільтрація файлів:** Якщо проєкт містить великі директорії (наприклад, згенеровані типи або моки), переконайтеся, що вони додані до `.gitignore` або `.claudeignore`, аби субагенти не вичитували непотрібні мегабайти тексту.
3. **Використання `-p` для тривіальних задач:** Неінтерактивний запуск виключає накопичення розмовної історії та виводить результат без зайвого діалогового сміття.
4. **Об'єднання надто дрібних тасок:** Створювати окремого субагента заради зміни одного рядка в 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 та розширені перевірки expect.
- Покрий граничні випадки (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) | Звичайна інтерактивна сесія з людиною |