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.

Uwaga

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

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

Ostrzeżenie

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 Збільшити

Architektura uruchamiania subagentów Claude Code i agregacja wyników do głównej sesji

Cykl życia wykonania równoległego

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).
Formowanie kontekstów podrzędnych: Tworzone są osobne subagenty, z których każdy otrzymuje spersonalizowane zadanie oraz ścieżkę do docelowego pliku.
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.
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 Збільшити

Kontekst współdzielony i izolowany subagentów: co jest dostępne dla wszystkich agentów, a co pozostaje prywatne

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)

Ważne

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ń

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 &.

Wskazówka

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

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”.
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.
Wykorzystanie -p dla zadań trywialnych: Uruchomienie nieinteraktywne wyklucza gromadzenie historii rozmowy i wyprowadza wynik bez zbędnego szumu dialogowego.
Łą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: