Subagenci w Claude Code: praktyczny przewodnik (2026)

Subagent to drugi Claude, uruchomiony przez twoją główną sesję Claude Code, który wykonuje zadanie we własnym oknie kontekstu i oddaje wynik. Nie dzieli twojej historii rozmowy. Nie widzi plików, które już przeczytałeś, ani decyzji, które już podjąłeś. Dostaje prompt, robi robotę i wraca.

Ta izolacja to cała funkcja. Równoległość, specjalizacja, niestandardowe ograniczenia narzędzi — wszystko to jest pochodną jednego faktu: subagent spala własne okno kontekstu i tylko finalna odpowiedź wraca do twojego.

Uruchamiamy dziesiątki subagentów dziennie, budując SkillProof, głównie do rozgałęzień badawczych i niezależnych poprawek w plikach danych katalogu. Część tego, czego się nauczyliśmy, jest naprawdę użyteczna. Część nauczyliśmy się, patrząc, jak agent ogłasza zwycięstwo nad pracą, której nigdy nie wykonał. Oba rodzaje są w tym przewodniku.

Czym naprawdę jest subagent

W Claude Code główna sesja to pętla: czytaj, myśl, działaj, obserwuj, powtarzaj, z każdym krokiem dopisywanym do jednej rosnącej rozmowy. Subagent to osobna instancja tej samej pętli, uruchomiona w środku sesji, z własną historią, która zaczyna się pusta poza promptem, który dajesz.

Gdy subagent kończy, żadna z jego pośrednich prac nie wraca. Nie pliki, które przeczytał, nie komendy, które uruchomił, nie ślepe zaułki, które eksplorował. Do twojego głównego kontekstu trafia tylko tekst, który zdecyduje się zwrócić. Jeśli przeczytał 40 plików, żeby odpowiedzieć na twoje pytanie, twoja główna sesja nie płaci za żaden z tych 40 odczytów. Płaci za jedno podsumowanie.

Dlatego subagenci są opisywani jako sposób na zachowanie kontekstu: nie dlatego, że praca jest darmowa (kosztuje te same tokeny gdzieś), ale dlatego, że koszt jest odizolowany w oknie, które zostaje wyrzucone, a nie w tym, które ciągniesz przez resztę sesji.

Kompromis wynika z tego wprost. Subagent, który nie wie, czego już próbowałeś, może powtórzyć twoje własne ślepe zaułki, i nie może zadać wyjaśniającego pytania w połowie zadania tak, jak potrafi główna pętla — albo ma wystarczająco w promptcie, żeby ruszyć dalej, albo zgaduje. Delegowanie kupuje izolację i kosztuje wspólną pamięć. Każdy dobry prompt dla subagenta jest napisany przez kogoś, kto zinternalizował ten kompromis.

Dlaczego izolacja kontekstu jest sednem sprawy

Wyobraź sobie główną sesję dwie godziny w głąb refaktoringu: czterdzieści przeczytanych plików, tuzin wywołań narzędzi, decyzja projektowa przemyślana dwa razy. Ta historia wykonuje realną robotę, to ona sprawia, że kolejna edycja jest spójna, ale to też pięćdziesiąt tysięcy tokenów balastu.

Teraz musisz się dowiedzieć, jak jeden niepowiązany podsystem obsługuje ponowienia. Przeczytaj te pliki w głównej pętli i każdy z nich staje się trwałym bagażem, jadącym w kontekście przez resztę sesji, użyty ponownie czy nie, aż stanie się częścią powodu, dla którego model zaczyna gubić właściwy refaktoring. Subagent pozwala ci zadać pytanie, dostać odpowiedź i odejść od czytania. Czterdzieści plików, które przeczytał, nigdy nie wchodzi do twojego okna. Dostajesz jeden akapit z powrotem.

To jest mechanizm stojący za każdym uzasadnionym zwycięstwem subagenta w tym przewodniku: badania, równoległe poprawki, hałaśliwa eksploracja. Wszystkie to tak naprawdę ten sam ruch — zrób drogie czytanie gdzieś jednorazowym, utrzymaj główny wątek czystym.

Kiedy subagenci biją pracę w głównej pętli

Badania w wielu plikach. „Jak przepływa autoryzacja przez tę bazę kodu" dotyka tras, middleware'u, przechowywania sesji i trzech plików konfiguracyjnych. Odpowiedź na to w głównej pętli oznacza, że wszystko to trwale ląduje w twoim kontekście. Subagent czyta te same pliki, zwraca syntezę, a surowy materiał znika razem z nim.

Równoległe niezależne zadania. Pięć komponentów potrzebuje tej samej zmiany nazwy propa. Żaden nie zależy od pozostałych. Pięć subagentów działających naraz kończy w mniej więcej czasie, jaki zajmuje jeden, bez współdzielonego stanu do koordynowania między zmianami.

Hałaśliwa eksploracja. Grepowanie wzorca w dużym repo, próbowanie trzech strategii wyszukiwania, zanim jedna trafi, czytanie plików, które okazują się nieistotne. To dokładnie praca, którą chcesz odizolować. Subagent może się miotać przez chwilę, a wróci tylko użyteczna część.

Izolowanie wyspecjalizowanej persony. Subagent-recenzent kodu, który tylko recenzuje, z węższym zestawem narzędzi i promptem dostrojonym do sceptycyzmu, zachowuje się bardziej spójnie niż proszenie twojego głównego agenta o przełączenie się w środku sesji na „teraz bądź krytyczny wobec własnej pracy".

Kiedy subagenci są gorsi

Ciasne, iteracyjne pętle. Debugowanie niepowodzącego testu poprzez zmianę jednej linijki, ponowne uruchomienie, przeczytanie nowego błędu, zmianę kolejnej linijki, potrzebuje pełnej historii tego, co już próbowałeś. Oddanie tego świeżemu subagentowi przy każdej iteracji oznacza ponowne wyjaśnianie całego śledztwa za każdym razem, wolniej i gorzej niż pozostanie w głównej pętli. To terytorium omawiane w naszych notatkach o systematycznym debugowaniu: debugowanie chce ciągłości, nie delegacji.

Zadania potrzebujące pełnej rozmowy. Jeśli użytkownik spędził dziesięć wiadomości, precyzując, co dokładnie znaczy „posprzątaj to API", subagent widzący tylko finalną instrukcję posprząta to według własnego zgadywania „posprzątania", nie tego, co wynegocjowaliście. Wszystko, gdzie wymagania żyją w rozmowie, a nie w promptcie, który możesz powtórzyć, jest złym dopasowaniem.

Proste edycje jednego pliku. Delegowanie „zmień nazwę tej zmiennej w tym pliku" do subagenta dodaje przejazd w tę i z powrotem, świeże załadowanie kontekstu i wynik, który wciąż musisz przeczytać i sprawdzić, do pracy, która zajęłaby piętnaście sekund bezpośrednio. Uruchomienie izolowanego workera opłaca się tylko wtedy, gdy praca, przed którą cię chroni, jest naprawdę duża.

Wzorzec wspólny dla wszystkich trzech: subagenci są gorsi dokładnie wtedy, gdy wartość wspólnego kontekstu przewyższa koszt jego niesienia. Izolacja przestaje być funkcją w chwili, gdy to ciągłość jest tym, czego potrzebowało zadanie.

Niestandardowe definicje agentów

Claude Code ładuje niestandardowych subagentów z plików markdown pod .claude/agents/ (poziom projektu, współdzielony przez git) albo ~/.claude/agents/ (osobisty, w każdym projekcie). Każdy plik to jeden agent: frontmatter plus prompt systemowy, ten sam kształt co skill, ale opisujący personę zamiast procedury.

Oto pełny, opatrzony adnotacjami przykład — recenzent kodu ograniczony do pracy tylko-do-odczytu:

---
name: code-reviewer
description: Reviews a diff or pull request for correctness bugs,
  security issues, and missed edge cases. Use after a change is
  written and before it's committed, not while still drafting.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior engineer doing a pre-commit review. You did not
write this code and you have no attachment to it.

When given a diff or a set of changed files:

1. Read every changed file in full, not just the diff hunks.
   Bugs hide in the context around a change as often as in the
   change itself.
2. Check for: unhandled errors, off-by-one boundaries, null or
   undefined paths the type system doesn't catch, and any
   secret or credential that shouldn't be committed.
3. Do not comment on style or formatting unless it hides a bug.
   A linter's job is not your job.
4. For each finding, cite the file and line, and say what
   breaks and how you'd confirm it. If you're not sure something
   is a bug, say so explicitly instead of stating it as fact.
5. If you find nothing, say that plainly. Do not invent minor
   issues to look thorough.

Never run commands that modify files. You are reviewing, not fixing.

Kilka rzeczy ma tu znaczenie. name to sposób, w jaki go wywołujesz (Use the code-reviewer agent to check this diff) albo w jaki Claude Code wywołuje go automatycznie przy pasującym zadaniu. Pole description niesie ten sam ciężar co w skillu: konkretne warunki wyzwalania biją niejasne podsumowanie.

tools to prawdziwa granica bezpieczeństwa, nie sugestia. Wypisanie tylko Read, Grep, Glob, Bash oznacza, że ten agent fizycznie nie może wywołać Edit ani Write, nawet jeśli jego własne rozumowanie uznało, że poprawka jest oczywista. To celowe: agent recenzujący, który może też załatać kod, który recenzuje, to taki, któremu nie możesz zaufać, że tylko recenzuje. model pozwala skierować mechanicznego, dobrze opisanego agenta do tańszego modelu niż twoja główna sesja, bo zadanie nie potrzebuje pełnej wagi twojego głównego modelu.

Treść to to samo rzemiosło co skill: negatywne ograniczenia („nie komentuj stylu", „nie wymyślaj drobnych problemów") robią więcej niż pozytywne, bo to one powstrzymują recenzenta przed dopychaniem wyniku, żeby wyglądał na dokładny.

Wzorce równoległe, które faktycznie działają

Rozgałęzione odczyty. Uruchom kilku subagentów naraz, każdemu przypisz inny wycinek tego samego pytania: jeden czyta moduł autoryzacji, jeden warstwę danych, jeden zestaw testów. Każdy zwraca krótką syntezę. Dostajesz trzy odpowiedzi w czasie, jaki zajęłoby jedno sekwencyjne przejście, a surowa zawartość plików nigdy nie dotyka twojego głównego kontekstu.

N niezależnych poprawek. Partia komponentów potrzebuje identycznej mechanicznej zmiany, i żaden nie importuje z drugiego. Uruchom jednego subagenta na komponent, każdy z samowystarczalnym promptem: dokładna zmiana, dokładny plik, dokładny warunek akceptacji. To najczystszy przypadek równoległy, żaden subagent nie musi wiedzieć, co zrobił inny.

Oba wzorce dzielą wymóg łatwy do pominięcia i kosztowny, gdy go pominiesz: każdy prompt musi być samowystarczalny. Nie ma twojej rozmowy. Jeśli zadanie zależy od decyzji podjętej trzy wiadomości temu, ta decyzja musi być powtórzona w promptcie, albo subagent pewnie zrobi złą rzecz.

Tryby awarii, na które faktycznie trafiliśmy

To część, którą pomija większość przewodników, napisanych przez kogoś, kto uruchomił subagenta dwa razy i zadziałało. My uruchamiamy ich codziennie, i oto, co psuje się w praktyce.

Agenci raportujący „gotowe" bez wykonania pracy. Subagent wraca z czystym, pewnym siebie podsumowaniem: „Zaktualizowano trzy pliki, testy przechodzą, gotowe do commitu." Sprawdzasz, a jeden plik jest nietknięty. To nie jest model będący nieuczciwym w jakimkolwiek celowym sensie, to podsumowanie odjeżdżające od tego, co faktycznie się stało, zwłaszcza przy dłuższych zadaniach, gdzie własna relacja agenta z pracy ulega kompresji. Naprawa jest nudna i nienegocjowalna: weryfikuj po artefakcie, nie po raporcie. Przeczytaj diff sam. Uruchom test sam. Podsumowanie subagenta to twierdzenie, nie potwierdzenie.

Agenci czekający na fantomowe powiadomienia. Mieliśmy subagentów zatrzymujących się w środku zadania, oczekujących callbacku albo sygnału od innego procesu, który nigdy nie miał nadejść, bo mechanizm koordynacji istniał tylko w wyobraźni promptu, nie w niczym faktycznie podłączonym. Naprawa polega na tym, żeby nigdy nie projektować promptu subagenta wokół zdarzenia, którego nie zweryfikowałeś, że się odpala. Jeśli kolejny krok subagenta zależy od wyniku innego agenta, przekaż mu ten wynik bezpośrednio przy uruchomieniu, nie proś go o wykrycie sygnału zakończenia, którego nie zbudowałeś.

Obie awarie sprowadzają się do tej samej dyscypliny: prompt, który nie polega na wspólnym kontekście ani zakładanym powiadomieniu, to taki, który agent faktycznie może poprawnie ukończyć, a wynik, który sprawdzasz, czytając plik, nie czytając relacji agenta o pliku, to jedyny sposób, by wiedzieć, że to zrobił. Nic z tego nie jest argumentem przeciwko subagentom. To argument przeciwko ufaniu podsumowaniu tekstowemu tak, jak ufałbyś diffowi. Uruchamiamy ich bez przerwy. Po prostu nie mergujemy niczego na słowo honoru.

Skille działają też wewnątrz subagentów

Subagent to wciąż instancja Claude, więc ładuje skille tak samo, jak twoja główna sesja: dopasowując swoje zadanie do opisów zainstalowanych skilli i dociągając treść po wyzwoleniu. Subagent recenzujący kod z zainstalowanym naszym skillem code review checklist dostaje to samo ustrukturyzowane przejście, co w głównej pętli, ograniczone do dowolnego diffa, który mu podałeś.

To komponuje się czysto. Subagent obsługuje, gdzie dzieje się praca, skill obsługuje, jak jest wykonana. Żaden nie musi wiedzieć o drugim; łączą się automatycznie, dopóki oba są zainstalowane tam, gdzie subagent może je zobaczyć — skille projektowe w .claude/skills/, skille osobiste w ~/.claude/skills/. Nasza strona najlepszych skilli do kodowania rankinguje te warte zainstalowania, zanim podłączysz agenta do recenzji albo badań.

Subagenci vs hooki vs skille

Trzy różne mechanizmy, trzy różne role, i są ciągle mylone:

	Co robi	Wyzwala się przez	Działa gdzie
Skill	Uczy Claude procedury albo stylu	Dopasowanie przez Claude twojej prośby do opisu	Wewnątrz bieżącego kontekstu
Hook	Uruchamia stałą komendę powłoki automatycznie	Zdarzenie cyklu życia (przed wywołaniem narzędzia, po odpowiedzi, start sesji)	Poza modelem, deterministycznie
Subagent	Deleguje zadanie do izolowanej instancji Claude	Jawne wywołanie, przez ciebie albo przez głównego agenta	Osobne okno kontekstu

Skill zmienia jak Claude podchodzi do czegoś, co i tak już zamierza zrobić. Hook egzekwuje coś za każdym razem, bezwarunkowo, bez proszenia modelu o zapamiętanie: uruchom testy po każdej edycji, zablokuj commit, jeśli wykryto sekrety. Subagent zmienia gdzie dzieje się praca, przenosząc ją do jednorazowego okna zamiast twojego głównego. Omawiamy hooki dogłębnie, wraz z tym samym rodzajem blizn co powyżej, w naszym przewodniku po hookach Claude Code.

Łączą się w stos. Setup zespołowy może użyć hooka do lintowania po każdym zapisie, skilla do nauczenia firmowego stylu kodu i subagenta do uruchomienia pełnego przejścia przeglądu przed mergem, trzy warstwy, żadna nieredundantna. Jeśli wciąż składasz resztę swojego setupu, nasz przewodnik konfiguracji na 2026 przechodzi przez to, gdzie trafia każdy element, a nasz przewodnik po kosztach tokenów omawia, ile kosztuje każdy z trzech w spoczynku.

FAQ

Czy subagenci współdzielą kontekst mojej głównej sesji?

Nie, i o to właśnie chodzi. Subagent zaczyna z pustą historią poza promptem, który mu dajesz. Nic z twojej głównej rozmowy nie przenosi się automatycznie, i nic, co subagent czyta albo robi, nie wraca poza finalnym tekstem, który zwraca. Jeśli potrzebuje tła z twojej rozmowy, umieść to tło w promptcie.

Czy subagenci mogą działać równolegle?

Tak. Uruchomienie kilku naraz to standardowy wzorzec dla rozgałęzionych badań i niezależnych, nienakładających się poprawek. Każdy dostaje własne okno kontekstu, więc nie kolidują ze sobą, ale też nie mogą koordynować się w trakcie zadania, chyba że jawnie przekazałeś wynik jednego do promptu drugiego.

Skąd wiem, czy subagent faktycznie zrobił to, co twierdził?

Sprawdź artefakt, nie podsumowanie. Przeczytaj diff, uruchom test, otwórz plik. Mieliśmy subagentów raportujących czysty sukces przy pracy, która była częściowo cofnięta, nie z nieuczciwości, ale dlatego, że podsumowanie to rekonstrukcja, a rekonstrukcje dryfują. Traktuj każdy raport subagenta jako twierdzenie do zweryfikowania.

Gdzie żyją niestandardowe definicje agentów?

.claude/agents/*.md dla agentów na poziomie projektu, które podróżują z repo przez git, i ~/.claude/agents/*.md dla osobistych, dostępnych w każdym projekcie. Każdy plik potrzebuje minimum name i description we frontmatterze; tools i model są opcjonalne, ale warto je ustawić świadomie zamiast zostawiać na domyślnych.

Czy powinienem ograniczać, jakich narzędzi może używać subagent?

Tak, zawsze gdy agent ma wąską rolę. Agent recenzujący, który nie może wywołać Edit, nie może przypadkiem załatać rzeczy, którą ma krytykować. Agent badawczy tylko-do-odczytu, który nie może wywołać Bash, nie może przypadkiem uruchomić czegoś destrukcyjnego, grzebiąc dookoła. Pole tools we frontmatterze agenta to mechanizm, a jego ustawienie jest tańsze niż debugowanie tego, co zrobił przesadnie potężny agent z pozostałym mu czasem.