# Subagenci i równoległa praca w Claude Code: jak wykonywać wiele zadań jednocześnie

> Kompletny przewodnik po równoległym przetwarzaniu zadań w Claude Code: architektura subagentów, kontekst współdzielony i izolowany, wzorce Fan-Out i Swarm, praca przez CLI z flagą -p oraz optymalizacja tokenów.

## 1. Czym są subagenci w Claude Code: od myślenia sekwencyjnego do równoległego

Standardowa sesja robocza **Claude Code** działa w trybie ściśle sekwencyjnym (single-threaded event loop). Użytkownik wysyła zapytanie, agent odczytuje kontekst, wykonuje wyszukiwanie, edytuje plik, uruchamia linter lub testy i dopiero po zakończeniu całego łańcucha przechodzi do kolejnego zadania. Gdy projekt skaluje się, a przed programistą staje dziesiątki wzajemnie niezależnych zadań, takie podejście sekwencyjne prowadzi do nieuzasadnionych opóźnień czasowych oraz szybkiego zaśmiecania okna kontekstowego.

Aby przezwyciężyć to ograniczenie, w architekturze Claude Code zintegrowano koncepcję **subagentów** – izolowanych, autonomicznych instancji modelu, którym delegowane są niezależne fragmenty ogólnego zadania.

```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
```

### Kluczowe cechy autonomicznego subagenta

- **Własne izolowane okno kontekstowe:** Subagent nie jest przeciążony długą historią dialogu głównej sesji, skupiając się wyłącznie na przydzielonym mu tasku.
- **Współdzielony dostęp do systemu plików:** Subagent może czytać strukturę katalogów, konfiguracje projektu oraz pliki kodu źródłowego na tych samych prawach co proces główny.
- **Wykonanie asynchroniczne:** Kilka subagentów pracuje jednocześnie, skracając całkowity czas wykonania (wall-clock time) proporcjonalnie do liczby równoległych wątków.
- **Automatyczna agregacja:** Po zakończeniu pracy subagent tworzy ustrukturyzowane podsumowanie, zwraca je do sesji nadrzędnej i zwalnia przydzielone zasoby.

> [!NOTE]
> Najprostszy model mentalny subagentów to efektywny management rozwoju. Zamiast tego, by Senior Engineer ręcznie pisał dokumentację dla pięciu mikrousług po kolei, tworzy on 5 osobnych tasków i przekazuje je równoległym wykonawcom, sprawdzając jedynie finalny wynik każdego z nich.

---

## 2. Kryteria paralelizacji: kiedy dzielić zadania, a kiedy pracować sekwencyjnie

Paralelizacja nie jest uniwersalnym panaceum. Jej skuteczność zależy bezpośrednio od stopnia wzajemnej niezależności zadań. Próba równoległego wykonania powiązanych etapów nieuchronnie powoduje race conditions (wyścigi) oraz kolizje logiczne.

| Scenariusz deweloperski | Optymalny tryb | Uzasadnienie wyboru |
| :--- | :---: | :--- |
| **Generowanie unit-testów dla różnych utility** | Równoległy | Moduły nie zależą od siebie nawzajem, brak wspólnych zależności |
| **Wielowymiarowy audyt bezpieczeństwa, SEO i UI** | Równoległy | Każdy kierunek analizuje system pod własnym kątem, tylko odczytując dane |
| **Projektowanie schemy DB i generowanie migracji** | Sekwencyjny | Migracji nie można napisać przed sfinalizowaniem modelu bazy danych |
| **Edycja tego samego pliku konfiguracyjnego** | Sekwencyjny | Jednoczesny zapis przez kilku agentów powoduje konflikty scalenia |
| **Pakietowy refactoring niezależnych komponentów** | Równoległy | Każdy komponent znajduje się w osobnym pliku bez cross-importów |

### Kiedy paralelizacja jest przeciwwskazana

1. **Kaskadowa zależność wyników:** Jeśli krok B wykorzystuje dane wyjściowe kroku A. Przykład: najpierw przeprowadź audyt schemy bazy danych, zaprojektuj nową strukturę, a dopiero potem wygeneruj migrację Prisma.
2. **Wspólne punkty modyfikacji plików:** Jeśli Agent 1 i Agent 2 spróbują jednocześnie wprowadzić zmiany w tym samym pliku `app.ts` lub `package.json`, jeden z zapisów zostanie nadpisany lub uszkodzony.
3. **Zadania wymagające iteracyjnego feedbacku ludzkiego:** Jeśli wymagania nie są ostatecznie określone i programista musi stale korygować kurs poprzez pytania doprecyzowujące, zadanie powinno pozostać w interaktywnej pojedynczej sesji.

> [!WARNING]
> Złota zasada paralelizacji: zanim uruchomisz pulę agentów, daj jasną odpowiedź na pytanie: **«Czy każdy agent może wykonać swoje zadanie od początku do końca bez czekania na pośrednie odpowiedzi od innych?»**. Jeśli odpowiedź brzmi „nie” – pracuj wyłącznie sekwencyjnie.

---

## 3. Architektura i mechanika uruchamiania subagentów przez Task Tool

Wewnątrz silnika Claude Code orkiestracja subagentów odbywa się za pomocą systemowego narzędzia **Task tool**. Gdy model w głównej sesji rozumie, że zadanie składa się z izolowanych komponentów, inicjuje podrzędne procesy tła.

Użytkownikowi zazwyczaj nie trzeba ręcznie wywoływać systemowych instrukcji JSON Task tool – wystarczy wyraźnie sformułować podział w zapytaniu lub pozwolić Claude Code samodzielnie zdekomponować zadanie.

![Architektura uruchamiania subagentów Claude Code i agregacja wyników do głównej sesji](/api/guides-media/ai_agents/claude-code-subagents-and-parallel-work/images/claude-code-subagents-and-parallel-work-step-01.webp)

### Cykl życia wykonania równoległego

1. **Dyspozycja zadania:** Główna sesja otrzymuje złożony prompt (np. napisanie testów dla pięciu utility: `auth.ts`, `validation.ts`, `formatting.ts`, `api-client.ts`, `cache.ts`).
2. **Formowanie kontekstów podrzędnych:** Tworzone są osobne subagenty, z których każdy otrzymuje spersonalizowane zadanie oraz ścieżkę do docelowego pliku.
3. **Praca autonomiczna:** Każdy agent równolegle odczytuje kod źródłowy swojego modułu, bada typy danych, generuje odpowiedni zestaw testowy i sprawdza jego uruchomienie.
4. **Scalanie zwrotne (Aggregation):** Główna sesja czeka na zakończenie wszystkich wątków, otrzymuje finalne statusy wykonania i prezentuje programiście skonsolidowany raport.

---

## 4. Kontekst współdzielony vs izolowany: co widzą subagenci

Najczęstszym błędem początkujących programistów jest założenie, że subagenci mają telepatyczną łączność między sobą lub wiedzą wszystko, o czym mówiono w 50. kroku głównego dialogu. W rzeczywistości model przestrzega jasnej polityki rozdzielenia pamięci.

![Kontekst współdzielony i izolowany subagentów: co jest dostępne dla wszystkich agentów, a co pozostaje prywatne](/api/guides-media/ai_agents/claude-code-subagents-and-parallel-work/images/claude-code-subagents-and-parallel-work-extra-02.webp)

| Zasób lub stan systemu | Współdzielony dla wszystkich agentów? | Opis techniczny dostępu |
| :--- | :---: | :--- |
| **Pliki projektu na dysku** | **Tak** | Wszyscy agenci mają uprawnienia do odczytu i zapisu w katalogu roboczym |
| **Reguły CLAUDE.md** | **Tak** | Każdy agent automatycznie inicjalizuje się z regułami projektu i stacku |
| **Historia poprzedniego dialogu** | **Nie** | Izolowane okno; subagent widzi tylko swój bezpośredni prompt |
| **Zmiany w otwartych plikach** | **Wymaga ostrożności** | Brak mechanizmów auto-blokowania plików; ryzyko kolizji przy zapisie |

### Zapewnienie bezpieczeństwa zapisu plików (Write Ownership)

Aby uniknąć uszkodzenia bazy kodu podczas pracy równoległej, stosuj zasadę **jedynego właściciela pliku**:

```text
Prawidłowy podział zakresów odpowiedzialności:
Subagent 1 ──► src/utils/auth.test.ts        (tworzy nowy plik testowy)
Subagent 2 ──► src/utils/validation.test.ts  (tworzy nowy plik testowy)
Subagent 3 ──► src/utils/formatting.test.ts  (tworzy nowy plik testowy)

Nieakceptowalny podział (kolizja):
Subagent 1 ──► src/index.ts  (modyfikuje linię eksportu)
Subagent 2 ──► src/index.ts  (modyfikuje linię eksportu)
Subagent 3 ──► src/index.ts  (modyfikuje linię eksportu)
```

> [!IMPORTANT]
> Jeśli kilku równoległym agentom konieczne jest zarejestrowanie utworzonych modułów w jednym pliku indeksowym (`src/index.ts` lub `src/routes.ts`), **nie powierzaj** tego subagentom. Niech agenci tylko stworzą swoje izolowane pliki, a rejestracją importów w pliku indeksowym zajmie się sesja nadrzędna po zwróceniu wszystkich wyników.

---

## 5. Wzorce formułowania promptów do uruchamiania równoległych agentów

Choć Claude Code posiada heurystyki wykrywania zadań równoległych, jawne wskazanie na jednoczesne wykonanie eliminuje wszelką dwuznaczność i optymalizuje czas dyspozycji.

### Przykłady efektywnego formułowania zapytań

:::tabs
@tab Podstawowy podział
```markdown
Wykonaj następujące trzy zadania równolegle za pośrednictwem odrębnych subagentów:

1. Zaimplementuj walidację pól w komponencie formularza rejestracyjnego (src/components/RegisterForm.tsx).
2. Utwórz komponent animacji szkieletowej ładowania dla panelu sterowania (src/components/DashboardSkeleton.tsx).
3. Dodaj obsługę paginacji w hooku pobierania użytkowników (src/hooks/useUsers.ts).

Upewnij się, że każdy agent pracuje wyłącznie z przypisanym mu plikiem i nie modyfikuje wspólnych konfiguracji.
```
@tab Analiza Fan-Out
```markdown
Działaj równolegle za pośrednictwem podagentów:

- Agent 1: Zbadaj oficjalną dokumentację API Stripe dotyczącą obsługi zdarzeń webhook subskrypcji.
- Agent 2: Przeanalizuj nasze bieżące wdrożenie w module src/services/billing.ts pod kątem podatności na ataki.
- Agent 3: Zaprojektuj interfejsy TypeScript dla nowych obiektów DTO wejściowych w pliku src/types/stripe.ts.

Po zakończeniu scal wyniki w jeden plan refactoringu w głównej sesji.
```
@tab Audyt pakietowy
```markdown
Przeprowadź równoległy audyt bazy kodu w czterech obszarach:

- Obszar A (Bezpieczeństwo): Skanowanie pod kątem wycieków sekretów w historii Git oraz bezpieczeństwa zapytań do bazy danych.
- Obszar B (Wydajność): Wykrywanie zapytań typu N+1 w kontrolerach oraz identyfikacja ciężkich importów w paczkach klienckich.
- Obszar C (Typowanie): Weryfikacja obecności niebezpiecznych typów „any” oraz brakujących obowiązkowych pól interfejsów.
- Obszar D (Dostępność): Audyt obecności atrybutów aria-label oraz kontrastu kolorów w klasach Tailwind.
```
:::

---

## 6. Cztery kluczowe schematy pracy równoległej: gotowe wzorce

Praktyczne doświadczenie zespołowej automatyzacji z Claude Code pozwoliło skrystalizować cztery wysokoskuteczne wzorce architektoniczne równoległej orkiestracji.

```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 (Badania równoległe)

Stosowane, gdy do podjęcia decyzji technicznej konieczne jest jednoczesne przeanalizowanie kilku alternatywnych bibliotek, technologii lub podejść architektonicznych. Każdy agent bada konkretny stack według standaryzowanych kryteriów (plusy, minusy, kompatybilność licencji, rozmiar bundle'a), po czym główna sesja syntetyzuje macierz porównawczą.

### Audit Swarm (Audyt interdyscyplinarny)

Jeden z najbardziej oszczędnych zasobowo wzorców pod względem czasu. Zamiast jednego agenta czytającego cały repozytorium czterokrotnie pod rząd dla różnych kontroli, czterech wąsko wyspecjalizowanych agentów uruchamia się jednocześnie. Ponieważ audyt odbywa się wyłącznie w trybie read-only, całkowicie znika ryzyko konfliktów zapisu plików.

### Batch Processor (Refactoring pakietowy)

Stosowany w dużych migracjach, gdy identyczną transformację należy wykonać na dużej masie niezależnych plików:
- Konwersja przestarzałych klas React na functional hooks w katalogu `src/components/`.
- Przepisywanie testów z Jest na Vitest.
- Aktualizacja importów starych utility po przeniesieniu ich do monorepo.

### Feature Sprint (Równoległy rozwój niezależnych feature'ów)

Rozwój kilku samowystarczalnych modułów UI lub endpointów API jednocześnie. Przykład:
- Agent 1 implementuje przełącznik ciemnego motywu (`ThemeToggle.tsx` + odpowiedni kontekst).
- Agent 2 rozwija formularz globalnego wyszukiwania (`SearchBar.tsx` + hook wyszukiwania).
- Agent 3 tworzy rozwijane menu powiadomień (`NotificationsDropdown.tsx`).

---

## 7. Uruchamianie równoległe przez CLI: Tryb Headless i flaga -p

Oprócz interaktywnej sesji Claude Code istnieje potężne narzędzie systemowej automatyzacji – uruchomienie Claude w **trybie headless (nieinteraktywnym)** za pomocą flagi `-p` (`--print`). W tym trybie agent otrzymuje prompt jako argument linii poleceń, wykonuje zadanie w izolowanym procesie terminalowym i drukuje wynik.

Otwiera to możliwość wykorzystania standardowych funkcji wykonywania procesów w tle w powłokach typu Unix (`&`) oraz narzędzia synchronizacji `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
```

### Zalety paralelizacji CLI

- **Zero nadzoru ludzkiego:** Idealne dla nocnych skryptów CI/CD, przygotowania zestawów testowych lub wstępnej generacji dokumentacji.
- **Prawdziwa izolacja OS:** Każdy proces `claude` uruchamia się w odrębnej przestrzeni adresowej systemu operacyjnego.
- **Logowanie do plików:** Wyjście każdego procesu można łatwo przekierować do własnego pliku log: `claude -p "..." > logs/auth.log 2>&1 &`.

> [!TIP]
> W terminalu operator `&` na końcu polecenia wysyła proces w tło, zwalniając terminal do natychmiastowego uruchomienia następnego polecenia. Wbudowane polecenie `wait` blokuje wykonanie skryptu dopóki wszystkie wymienione PID-y w tle nie zakończą pracy z zwróceniem kodu wyjścia.

---

## 8. Ekonomia tokenów, limity API i optymalizacja kosztów

Praca równoległa radykalnie oszczędza czas inżyniera, jednak wymaga starannej kontroli finansowej. Każdy subagent tworzy własne okno kontekstowe, więc równoległe uruchomienie $N$ agentów zwiększa zużycie tokenów około $N$ razy.

```text
Sekwencyjna sesja (1 okno kontekstowe):
[Prompt systemowy] + [Zadanie 1] ──► [Zadanie 2] ──► [Zadanie 3]
Łączna liczba tokenów: Kontekst bazowy + ΔT1 + ΔT2 + ΔT3

Równoległe subagenty (3 niezależne okna kontekstowe):
Subagent 1: [Kontekst bazowy + Zadanie 1]
Subagent 2: [Kontekst bazowy + Zadanie 2]
Subagent 3: [Kontekst bazowy + Zadanie 3]
Łączna liczba tokenów: (3 × Kontekst bazowy) + ΔT1 + ΔT2 + ΔT3
```

### Cztery zasady kontroli budżetu tokenów

1. **Wąsko określony scope:** Nie dawaj agentowi ogólnego polecenia typu „Posprzątaj testy w projekcie”. Formułuj konkretnie: „Napisz 3 unit-testy dla funkcji parseJwt w src/utils/auth.ts”.
2. **Filtrowanie plików:** Jeśli projekt zawiera duże katalogi (np. wygenerowane typy lub mocki), upewnij się, że są dodane do `.gitignore` lub `.claudeignore`, aby subagenci nie wczytywali zbędnych megabajtów tekstu.
3. **Wykorzystanie `-p` dla zadań trywialnych:** Uruchomienie nieinteraktywne wyklucza gromadzenie historii rozmowy i wyprowadza wynik bez zbędnego szumu dialogowego.
4. **Łączenie zbyt drobnych tasków:** Tworzenie osobnego subagenta dla zmiany jednej linii w CSS jest niecelowe – koszty inicjalizacji sesji przewyższą użyteczną pracę.

---

## 9. Warsztat praktyczny: krok po kroku realizacja od testów po Audit Swarm

Utrwalmy zdobytą wiedzę na rzeczywistym warsztacie praktycznym z wykonaniem krok po kroku.

### Krok 1. Wybór izolowanych modułów i przygotowanie

Wybierz w swoim repozytorium trzy moduły utility, które nie mają cyklicznych ani wzajemnych importów:
- `src/utils/auth.ts`
- `src/utils/validation.ts`
- `src/utils/formatting.ts`

Upewnij się, że odpowiednie pliki testowe nie istnieją lub wymagają aktualizacji.

### Krok 2. Formułowanie i uruchomienie promptu równoległego

Otwórz interaktywną sesję Claude Code w terminalu projektu i wpisz ustrukturyzowane zapytanie:

```markdown
Wygeneruj testy modułowe dla następujących trzech plików równolegle za pomocą subagentów:

1. src/utils/auth.ts -> zapisz testy w src/utils/auth.test.ts
2. src/utils/validation.ts -> zapisz testy w src/utils/validation.test.ts
3. src/utils/formatting.ts -> zapisz testy w src/utils/formatting.test.ts

Wymagania dotyczące testów:
- Używaj Vitest oraz zaawansowanych asercji expect.
- Pokryj przypadki brzegowe (null, undefined, puste ciągi znaków).
- Nie modyfikuj oryginalnych plików z funkcjami pomocniczymi.
```

### Krok 3. Monitorowanie i weryfikacja wyników

Obserwuj wyjście w konsoli. Zobaczysz, jak Claude Code inicjuje zadania podrzędne, niezależnie przetwarza kod każdego modułu i sygnalizuje zakończenie każdego podprocesu.

Po zakończeniu uruchom sprawdzenie w swoim terminalu:

```bash
npm run test:run
```

Wszystkie trzy nowe zestawy testowe powinny pomyślnie przejść walidację bez konfliktów w bazie kodu.

### Krok 4. Uruchomienie Audit Swarm dla oceny jakości

Kolejnym krokiem jest przetestowanie wzorca analitycznego Audit Swarm. Wyślij zapytanie:

```markdown
Przeprowadź kompleksowy audyt repozytorium za pomocą czterech równoległych subagentów:

- Agent Bezpieczeństwa: sprawdzenie pod kątem XSS, CSRF, podatnych pakietów npm oraz zaszyfrowanych na stałe sekretów.
- Agent Wydajności: analiza rozmiaru bundla, zbędnych re-renderów i ciężkich bibliotek.
- Agent Dostępności (a11y): weryfikacja semantycznych tagów HTML, pułapek fokusu oraz atrybutów ARIA.
- Agent Jakości Kodu: wykrywanie martwego kodu, duplikacji oraz nieuzasadnionego użycia typu any.

Sporządź zbiorczy raport podsumowujący z priorytetami poprawek (High / Medium / Low).
```

---

## 10. Podsumowująca ściągawka i checklista gotowości do paralelizacji

Zachowaj tę checklistę przed uruchomieniem dużych pipeline'ów równoległych w Claude Code.

### Checklista gotowości do uruchomienia równoległego

- [ ] **Niezależność tasków:** Żadne z zadań nie czeka na pośredni artefakt od innego równoległego agenta.
- [ ] **Izolacja zapisu plików:** Każdy agent zapisuje dane do własnego nowego lub izolowanego pliku; brak walki o wspólne pliki konfiguracyjne.
- [ ] **Wąskie formułowanie promptów:** Określono jasne pliki wejściowe i wyjściowe, stack technologiczny oraz kryteria sukcesu.
- [ ] **Uzasadnienie ekonomiczne:** Korzyść ze skrócenia czasu wykonania przewyższa koszty duplikacji kontekstu bazowego.
- [ ] **Przygotowanie środowiska:** Wszystkie zewnętrzne ciężkie katalogi zostały wykluczone z kontekstu przez `.claudeignore`.

### Szybka macierz wyboru narzędzia

| Zadanie | Rekomendowane podejście | Polecenie / Metoda |
| :--- | :--- | :--- |
| **Jednorodne testy dla 5+ modułów** | Interaktywny Claude Code lub CLI `-p` | `claude -p "..." &` |
| **Wieloaspektowy audyt projektu** | Audit Swarm w sesji | Interaktywny prompt z 4 agentami |
| **Porównanie bibliotek/technologii** | Research Fan-Out | Zestawienie w tabeli podsumowującej |
| **Głęboki refactoring rdzenia systemu** | Sesja sekwencyjna (Single Session) | Zwykła interaktywna sesja z człowiekiem |

---

## 11. Rekomendowane kolejne materiały

Aby pogłębić wiedzę na temat pracy z ekosystemem Claude i automatyzacją procesów, zachęcamy do zapoznania się z naszymi nowymi przewodnikami:

- 🚀 [Claude Code Projects: jak jeden AI koordynuje zespół autonomicznych agentów →](/uk/guides/ai_agents/claude-code-projects-multi-agent)
- 📊 [Claude + Excel dla logistyka: 10 gotowych scenariuszy audytu stawek i kosztów →](/uk/guides/ai_base/claude-excel-logistics-playbook)
- ⚡ [Claude + Notion dla biznesu: automatyzacja CRM i zadań w 30 minut →](/uk/guides/ai_base/claude-notion-business-automation)
- 🤖 [Autonomiczny Operator AI w Telegramie 24/7: architektura i 10 działających scenariuszy →](/uk/guides/ai_base/telegram-ai-operator-24-7)