Kiedy subagenci pomagają, a kiedy przeszkadzają
W Claude Code jest narzędzie Agent, które pozwala uruchamiać niezależnych subagentów w trakcie rozmowy. Każdy subagent działa we własnym kontekście, wykonuje zadanie i zwraca wynik głównemu agentowi.
Brzmi potężnie, ale w praktyce w większości przypadków subagenci nie są potrzebni. W tym artykule wyjaśniam: kiedy podział na subagentów faktycznie pomaga, a kiedy tylko przeszkadza.
Nie da się bezpośrednio wywołać Agent tool z CLAUDE.md ani slash-komendy — Claude Code sam decyduje, czy go użyć. Można jednak wpływać na tę decyzję przez prompty.
Mechanizm działania:
Kluczowe cechy:
- Izolowany kontekst: subagent nie widzi historii głównej rozmowy — zna tylko prompt, z którym został uruchomiony
- Kompresja wyniku: niezależnie od tego, ile plików subagent przeczytał i ile komend wykonał, z powrotem wraca jedynie zwięzłe podsumowanie
- Równoległe uruchamianie: kilku subagentów może działać jednocześnie
Najbardziej typowy przypadek. Prosisz Claude Code o zbadanie problemu i trzeba sprawdzić kilka kierunków naraz.
Na przykład pytasz: „Jak w projekcie zaimplementowano uwierzytelnianie?"
Bez subagentów Claude Code będzie działał sekwencyjnie: przeczyta auth controller → middleware → routes → model → config… Krok po kroku — wolno.
Z subagentami:
Jednocześnie uruchamianych jest 3 subagentów:
- Agent 1: bada logikę uwierzytelniania w controller i middleware
- Agent 2: analizuje modele użytkowników i sesji
- Agent 3: sprawdza pliki konfiguracyjne i zmienne środowiskowe
Trzy kierunki działają równolegle, wyniki są zbierane razem. W CLAUDE.md można to ująć tak:
## Zadania badawcze
Przy analizie problemów obejmujących wiele modułów uruchamiaj
kilku subagentów równolegle do badania różnych kierunków,
potem zbieraj wyniki.
Okno kontekstowe Claude Code jest ograniczone. Jeśli podzadanie wymaga przeczytania mnóstwa plików, ale ostatecznie potrzebny jest tylko wniosek — subagent ochroni główny kontekst przed „informacyjnym śmieciem".
Typowe przykłady:
Wspólna cecha tych zadań — dużo danych wejściowych, mało wyjściowych. Subagent przetwarza objętość wewnątrz siebie i zwraca tylko esencję.
Czasem nie masz pewności, czy zmiany czegoś nie zepsują. Subagent z parametrem isolation: "worktree" pracuje w osobnym git worktree. Nawet jeśli coś pójdzie nie tak — twój katalog roboczy pozostanie nienaruszony.
## Ryzykowny refaktoring
Przy dużym refaktoringu używaj subagentów z izolacją worktree.
Scalaj zmiany dopiero po weryfikacji wyniku.
Odpowiednie sytuacje:
- Próbny refaktoring: nie wiadomo, czy podejście zadziała — niech subagent sprawdzi
- Porównanie wariantów: zaimplementować zadanie na dwa sposoby równolegle i porównać
- Generowanie kodu: wygenerować kod szablonowy, sprawdzić i dopiero potem scalić
„Zmień nazwę tej funkcji z camelCase na snake_case" — tu szybciej zrobić bezpośrednio. Narzut uruchomienia subagenta (budowanie kontekstu, czekanie na odpowiedź, parsowanie wyniku) przewyższy czas samego zadania.
Reguła: jeśli wystarczy jeden Grep + jeden Edit — nie twórz subagenta.
„Przeczytaj config → zmień kod na podstawie configu → zaktualizuj testy pod zmiany"
W takim łańcuchu każdy krok zależy od poprzedniego. Rozdzielenie na subagentów oznacza przekazywanie wyników pośrednich przez prompty — niewygodne i łatwo zgubić informacje. Lepiej zrobić to sekwencyjnie.
Subagent zwraca tekstowe podsumowanie, nie dane strukturalne. Jeśli potrzebna jest dokładna zmiana (np. wstawić konkretny kod w linii 47), pewniej zlecić to głównemu agentowi.
Subagenci nadają się do „zbadaj i daj wnioski", a nie do „wprowadź precyzyjną zmianę".
Jeśli rozmowa dopiero się zaczęła i okno kontekstowe jest prawie puste, nie ma sensu „oszczędzać kontekstu" przez subagentów. Warto o tym pomyśleć, gdy rozmowa się wydłuża i główny agent zaczyna kompresować historię.
Rzeczywisty przykład: przeanalizować wszystkie kontrolery w projekcie Rails, które używają before_action, i zbadać wzorce uwierzytelniania i autoryzacji.
Bez subagenta:
Claude Code sekwencyjnie czyta pliki kontrolerów — każdy zajmuje miejsce w głównym kontekście. Przy 20 kontrolerach sama zawartość plików może pochłonąć ogromną liczbę tokenów. W momencie formułowania wniosków wcześniejsze szczegóły mogą być już utracone przez kompresję.
Z subagentem:
Uruchomienie subagenta: „Przeczytaj wszystkie kontrolery w app/controllers/,
znajdź wszystkie callbacki before_action, przeanalizuj wzorce
uwierzytelniania i autoryzacji, podaj sklasyfikowane podsumowanie."
Subagent czyta wszystkie pliki we własnym kontekście i zwraca czyste podsumowanie. Główny kontekst praktycznie się nie zużywa — po otrzymaniu wniosków można iść dalej.
Nie da się zmusić Claude Code do używania lub niestosowania subagentów, ale przez CLAUDE.md można ustawić preferencje:
## Preferencje dotyczące agentów
### Zadania odpowiednie dla subagentów
- Analiza międzymodułowa (równoczesne przeszukiwanie 3+ katalogów)
- Wyszukiwanie i analiza kodu na dużą skalę
- Eksperymentalny refaktoring (z izolacją worktree)
### Zadania niewymagające subagentów
- Zmiany w pojedynczym pliku
- Operacje sekwencyjne z zależnościami między krokami
- Poprawki bugów, gdy dokładnie wiadomo, co zmienić
Czy „proces" tego zadania jest znacznie większy niż „wynik"?
Jeśli tak — użyj subagenta: niech przetworzy proces i zwróci sam wynik.
Jeśli nie — zrób to bezpośrednio, bez dodatkowych warstw.
Subagenci to nie „im więcej, tym lepiej". To narzędzie do zarządzania kontekstem, a nie framework do programowania współbieżnego. Dobrze użyte pomagają Claude Code zachować jasność myślenia w dużych projektach. Źle użyte — tylko marnują czas na uruchamianie.