Zespoły agentów w Claude Code — jak je zbudować, żeby działały

Zespoły agentów (po angielsku agent teams) to funkcja Claude Code, w której zamiast jednego asystenta pracuje dla ciebie kilku — równolegle, z jedną wspólną listą zadań i z możliwością rozmawiania między sobą. Zacznę od dwóch pojęć, bo wrócą w tekście wielokrotnie. Agent to program oparty na modelu językowym, który dostaje zadanie i wykonuje je samodzielnie: czyta pliki, pisze kod, sprawdza wynik. Claude Code to narzędzie, w którym taki agent pracuje przy zadaniach programistycznych i operacyjnych — działa w terminalu (oknie poleceń) albo jako rozszerzenie edytora, czyta pliki i wykonuje kolejne kroki.

Poniżej praktyczny przegląd: czym zespół agentów różni się od pojedynczego agenta pomocniczego, jak go uruchomić, jak go poprosić o pracę, żeby wynik był dobry, i — co ważne — kiedy nie warto go w ogóle używać.

Jak to wygląda w praktyce

Najprościej pokazać to na przykładzie. Jednym poleceniem można poprosić o utworzenie zespołu z trzech agentów: programisty front-endu (część widoczna w przeglądarce), programisty back-endu (część działająca po stronie serwera) i agenta QA, czyli kontroli jakości. Claude Code uruchamia całą trójkę równolegle. Każdy z nich to osobny agent, ale dzielą jedną listę zadań i pracują razem z główną sesją — tą, w której piszesz.

Ciekawe zaczyna się dziać przy sprawdzaniu jakości. Programiści front-endu i back-endu przekazują swoją pracę agentowi QA. Ten potrafi znaleźć poważne błędy i odesłać zadanie z powrotem — wtedy główny agent rozdziela poprawki między pierwszych dwóch, a w kolejnym podejściu QA daje zielone światło, gdy wszystko jest naprawione. Z jednego polecenia w stylu „zbuduj stronę dla fikcyjnego startupu AI” powstaje kompletna strona: teksty, kolorystyka, animacje. Nie idealna i wymagająca poprawek, ale spójna i gotowa do dalszej pracy.

Czym to się różni od pojedynczego agenta pomocniczego

To jest źródło największego nieporozumienia, więc warto je rozjaśnić. Agent pomocniczy (po angielsku sub-agent, czyli podagent) pracuje samodzielnie i odsyła swój wynik z powrotem do głównego agenta. Działa w pojedynkę i na końcu raportuje.

Zespół agentów działa inaczej. Ma kogoś w rodzaju lidera — odpowiednika kierownika projektu — który tworzy poszczególnych agentów i jedną wspólną listę zadań. Kluczowa różnica: członkowie zespołu mogą rozmawiać bezpośrednio ze sobą. Gdy jeden potrzebuje czegoś od drugiego, po prostu wysyła mu wiadomość, bez pośrednictwa głównej sesji. Dzięki temu powstają pożyteczne pętle — jak ta z agentem QA, który mówi „to jeszcze nie jest wystarczająco dobre” i odsyła pracę. Główny agent przez cały czas pilnuje, żeby zadania się domykały i żeby jakość była wysoka.

W skrócie: podagent to pojedynczy wykonawca z raportem na końcu. Zespół to kilku wykonawców pracujących jednocześnie i komunikujących się przez całą drogę.

Jak to uruchomić

Funkcja jest na razie eksperymentalna i domyślnie wyłączona. Włącza się ją jednym ustawieniem (zmienną) w pliku konfiguracyjnym projektu — settings.json. W oficjalnej dokumentacji Claude Code jest gotowy fragment do skopiowania; można po prostu poprosić Claude Code, żeby wstawił go do ustawień lokalnych projektu.

Warto jeszcze przed pierwszym uruchomieniem zrobić jedną rzecz: nauczyć projekt, jak zespoły agentów działają. Najprościej wziąć adres dokumentacji i poprosić o stworzenie z niej lokalnego przewodnika — pliku w formacie Markdown w folderze docs. Od tej pory, gdy Claude Code będzie czegoś potrzebował na temat zespołów, sięgnie do tego pliku zamiast za każdym razem czytać dokumentację online. To ta sama sztuczka, którą warto stosować przy każdej obszernej dokumentacji, do której model wraca często.

Jak formułować polecenie

Zespół wywołuje się zwykłym językiem, bez żadnej specjalnej składni. Dobry schemat wygląda tak:

1. Zacznij od celu. Gdy agenci „budzą się”, nie mają żadnego kontekstu — znają tylko to, co poda im główna sesja. Jeśli z góry powiesz, do czego cały zespół dąży, każdy lepiej rozumie nie tylko swoje zadanie, ale i to, po co ma obok siebie pozostałych.
2. Określ skład: „stwórz zespół trzech agentów na modelu X” (do wyboru są modele Haiku, Sonnet i Opus — od najszybszego i najtańszego po najmocniejszy).
3. Opisz każdą rolę: co dany agent ma robić, co ma wytworzyć i z kim ma się skontaktować, gdy skończy („gdy będziesz gotowy, wyślij wynik agentowi front-endu”).
4. Nazwij efekt końcowy. Główny agent zbierze od wszystkich mnóstwo informacji — powiedz wprost, co chcesz dostać na koniec: działającą aplikację, raport z testów, krótki dokument opisujący, co zbudowano i jak to uruchamiać dalej.

Do tego kilka zasad, które robią różnicę między zespołem, który działa, a takim, który się plącze:

• Każdy agent ma swoje pliki. Jeśli kilku agentów edytuje ten sam plik, mogą nadpisać sobie nawzajem pracę. Przydziel każdemu jego teren.
• Określ wynik dokładnie. Mgliste polecenia dają mgliste efekty.
• Wskaż odbiorców z imienia. Nie zakładaj, że agent sam się domyśli, do kogo i po co ma napisać.
• Trzymaj się trzech do pięciu agentów. Rój dziesięciu i więcej to nie tylko chaos, ale i dziesięciokrotnie wyższy koszt.
• Podaj pełny kontekst od razu. Agenci mogą przeczytać wszystkie pliki w projekcie, ale na starcie nie dostają nic poza tym, co im powiesz.

Co agenci wiedzą, gdy się „budzą”

Skoro nie dostają historii rozmowy, warto wiedzieć, co jednak mają. Po pierwsze, dziedziczą uprawnienia głównej sesji — jeśli ty zatwierdziłeś dane polecenia, oni też je mają. Po drugie, mają dostęp do wszystkich plików projektu, a także do podłączonych narzędzi i umiejętności (skills) — wszystkiego, czym dysponuje główna sesja.

Jest też przydatny tryb zatwierdzania planu. Zanim agent zacznie cokolwiek wykonywać, musi najpierw przedstawić plan i dostać jego akceptację — od głównego agenta albo od ciebie. To ten sam nawyk co praca w trybie planowania w pojedynczej sesji: najpierw plan, potem działanie. Zwykle wygodniej, gdy plany zatwierdza główny agent; można też wyznaczyć jednego z członków zespołu na recenzenta planów.

Najczęstsze problemy i co z nimi zrobić

• Agenci co chwilę pytają o pozwolenie i zatrzymują pracę → zatwierdź wybrane polecenia z góry w ustawieniach projektu.
• Wynik nie składa się w całość → prawdopodobnie agenci nadpisują sobie pliki; przydziel właścicieli plików.
• Któryś agent stoi bezczynnie → upewnij się, że w poleceniu każdy ma przypisaną pracę albo zależność od innych.
• Zużycie tokenów rośnie zbyt szybko → użyj mniejszej liczby agentów (token to porcja tekstu, którą model przetwarza, i jednostka rozliczeń; trzy równoległe sesje to z grubsza potrójny koszt).
• Agenci gubią pracę → poproś, żeby zapisywali wszystko w plikach tymczasowych, do których mogą wrócić.

Kiedy używać zespołu, a kiedy nie

Zespoły agentów są wolniejsze i droższe niż pojedynczy agent. To nie wada — to cena za wyższą jakość przy złożonych zadaniach. Sięgaj po nie, gdy zadanie ma kilka różnych obszarów (każdy agent bierze jeden), gdy te części mogą powstawać równolegle, gdy agenci muszą na siebie reagować i przekazywać sobie zadania, i gdy zależy ci na wysokiej jakości pilnowanej przez wiele kroków kontroli.

Z drugiej strony łatwo tę funkcję przeszacować. Nie używaj zespołu, gdy:

• proces jest sekwencyjny — kroki idą po kolei (1, 2, 3) i każdy zależy od poprzedniego; to raczej zadanie dla podagentów,
• wszystko ma się zmieścić w jednym oknie kontekstu (czyli w jednej rozmowie i jej historii),
• agenci pracowaliby i tak na tych samych plikach,
• zadanie jest po prostu proste — wtedy zespół to przerost formy.

To jest ta sama uczciwa uwaga, którą warto powtarzać przy każdym narzędziu AI: cudzy przypadek użycia to nie twój przypadek użycia. Mocniejsza funkcja nie znaczy automatycznie lepsza dla tego, co akurat robisz.

Na koniec: zamykaj zespół porządnie

Gdy praca jest skończona, główny agent wysyła do członków zespołu prośbę o zamknięcie — odpowiednik „skończ i zapisz pracę”. Agent może odpowiedzieć „jeszcze nie skończyłem, nie zamykaj mnie” i dokończyć zapis. Chodzi o to, żeby na koniec wszystko zostało czysto zapisane, a nie przerwane w połowie. To drobiazg, który decyduje o tym, czy po sesji zostaje uporządkowany wynik, czy bałagan do posprzątania.

Zespoły agentów to jedno z mocniejszych narzędzi w Claude Code — ale właśnie dlatego warto wiedzieć, kiedy ich nie wyciągać. Przy złożonym zadaniu z kilkoma obszarami, które muszą powstawać równolegle i rozmawiać ze sobą, dają jakość trudną do osiągnięcia inaczej. Przy wszystkim prostszym pojedynczy agent albo podagent zwykle wystarczy — taniej i szybciej.