Poradnik

Jak używać subagentów w Claude Code

Długie wyszukiwania i obszerne wyniki testów szybko zapychają rozmowę w Claude Code. Subagenty przenoszą tę pracę do osobnego kontekstu i oddają tylko podsumowanie. Ten poradnik wyjaśnia, czym są, jak tworzyć własne i kiedy warto ich używać.

Zaktualizowano 30 października 2026

Krótka odpowiedź: subagent to wyspecjalizowany pomocnik, któremu Claude Code przekazuje zadanie. Pracuje we własnym oknie kontekstu, z własnymi instrukcjami i dostępem do narzędzi, a potem zwraca tylko wynik. Żeby go utworzyć, zapisz plik Markdown z polami name i description we frontmatterze w .claude/agents/ (jeden projekt) lub ~/.claude/agents/ (wszystkie projekty), a potem poproś Claude, żeby użył go po nazwie, albo wybierz go przez @.

Szczegóły opisane poniżej pochodzą z dokumentacji Claude Code od Anthropic z października 2026. Claude Code często się zmienia, więc jeśli czegoś tu opisanego brakuje, uruchom claude update.

Czym są subagenty

Gdy Claude trafia na zadanie pasujące do opisu subagenta, może mu je przekazać. Subagent zaczyna od zera: nie widzi twojej rozmowy, tylko instrukcje, które przekaże mu Claude. Wykonuje swoją pracę, na przykład czyta dziesiątki plików lub uruchamia zestaw testów, i odsyła podsumowanie. Twoja główna rozmowa pozostaje krótka.

Claude Code ma wbudowane subagenty, w tym:

Explore: szybkie wyszukiwanie i analiza bazy kodu tylko do odczytu.
Plan: badanie kodu tylko do odczytu, gdy jesteś w plan mode.
General-purpose: zadania wieloetapowe, które wymagają zarówno badania, jak i zmieniania rzeczy.

Nie musisz ich konfigurować; Claude używa ich, gdy pasują.

Utwórz własnego subagenta

Wybierz zakres. Dla subagenta, z którego może korzystać cały zespół w jednym repozytorium, utwórz w projekcie folder .claude/agents/. Dla takiego, który ma ci towarzyszyć we wszystkich projektach, użyj ~/.claude/agents/.
Utwórz w tym folderze plik Markdown, na przykład code-reviewer.md.
Zacznij plik od frontmattera między dwiema liniami ---. Pierwszą linią pliku musi być ---.
Dodaj dwa wymagane pola: name (unikalny identyfikator, na przykład code-reviewer, bez dwukropka) i description (kiedy Claude ma go używać, na przykład Reviews code for quality and best practices. Use after code changes., czyli: przegląda kod pod kątem jakości i dobrych praktyk, używaj po zmianach w kodzie).
Opcjonalnie dodaj tools, żeby ograniczyć, czego może używać, na przykład Read, Glob, Grep dla recenzenta tylko do odczytu, oraz model (alias modelu, taki jak sonnet lub haiku, pełny identyfikator modelu albo inherit).
Pod zamykającą linią --- napisz zwykłym językiem instrukcje dla subagenta: jego rolę, co ma sprawdzić i co zwrócić.
Zapisz plik. Claude Code wczytuje zmiany w istniejącym folderze agentów w ciągu kilku sekund; jeśli folder utworzyłeś w trakcie sesji, uruchom Claude Code ponownie.

Możesz też po prostu poprosić Claude w sesji, żeby utworzył subagenta za ciebie. W obecnych wersjach polecenie /agents kieruje cię właśnie do tego albo do bezpośredniej edycji folderów.

Używanie subagenta

Zostaw wybór Claude: Claude porównuje twoją prośbę z polem description każdego subagenta. Słowa takie jak „use proactively” (używaj proaktywnie) w opisie zachęcają go do przekazywania zadań.
Poproś po nazwie: na przykład Użyj subagenta code-reviewer, żeby sprawdzić moje ostatnie zmiany.
Oznacz go przez @: wpisz @ i wybierz subagenta. Masz wtedy pewność, że to on zajmie się zadaniem.
Na całą sesję: uruchom claude --agent code-reviewer.

Kiedy subagenty pomagają, a kiedy nie

Wskazówki Anthropic sprowadzają się do tego:

Użyj subagenta, gdy	Zostań w głównej rozmowie, gdy
Zadanie generuje dużo wyników, których nie musisz zachowywać, jak logi czy wyniki wyszukiwania	Potrzebujesz częstej wymiany zdań
Chcesz ograniczyć, których narzędzi można używać	Kilka kroków dzieli dużo kontekstu
Praca jest samodzielna i może zakończyć się podsumowaniem	To szybka, punktowa zmiana
Chcesz, żeby niezależne badania szły równolegle

Warto wiedzieć

Jeśli dwa subagenty mają tę samą nazwę, wygrywa lokalizacja o wyższym priorytecie: ustawienia zarządzane, potem flaga --agents, potem folder projektu, potem twój folder użytkownika, a na końcu wtyczki.
Subagent nie widzi historii twojego czatu ani plików, które Claude już przeczytał, więc polega na instrukcjach, które dostaje od Claude.
Domyślnie jednocześnie może działać do 20 subagentów.
Nazwy pól są w camelCase (na przykład disallowedTools, maxTurns), a nierozpoznane pola są pomijane bez ostrzeżenia, więc sprawdzaj pisownię.
Pliki subagentów projektu można zatwierdzić w repozytorium, żeby cały zespół miał tych samych pomocników.

Jeśli to nie działa

Claude nie znajduje nowego subagenta: jeśli folder agentów nie istniał w chwili rozpoczęcia sesji, uruchom Claude Code ponownie.
Plik jest po cichu pomijany: typowe przyczyny to brak name lub description, niepoprawny YAML albo --- nie w pierwszej linii. Uruchom claude --debug i przeczytaj log debugowania albo uruchom claude plugin validate .claude/agents, żeby znaleźć pliki, których frontmatter się nie parsuje.
Claude zgłasza błąd o nierozpoznanych narzędziach: gdy żaden wpis w tools nie pasuje do istniejącego narzędzia, Claude Code zwykle nie uruchomi subagenta. Popraw pisownię nazw narzędzi.
Niewłaściwy model: uruchom /tasks, żeby zobaczyć, jakiego modelu faktycznie używa każdy subagent.

Zachowaj wyniki, nie tylko podsumowanie

Raport subagenta trafia do twojej sesji, a ta po zamknięciu znika z widoku. Z wtyczką Workbranch dla Claude Code wystarczy powiedzieć „save this to Workbranch” (zapisz to w Workbranch), a zadania, decyzje i otwarte pytania z sesji trafią do projektu, a następna sesja w tym folderze zacznie się od tego, co jest jeszcze otwarte. Zobacz Workbranch dla Claude. Jeśli w sesji zabrakło miejsca, poradnik o wznawianiu sesji Claude Code pokazuje, jak do niej wrócić.

Źródła

Use Claude Code with your Pro or Max plan (Centrum pomocy Claude, sprawdzono 30 października 2026)
Create custom subagents (Claude Code docs, sprawdzono 30 października 2026)

Najczęściej zadawane pytania

Czy subagenty zużywają dodatkowy limit?

Zapytania subagentów liczą się do tych samych limitów użycia co twoja główna rozmowa. Kierowanie prostej pracy do tańszego modelu, takiego jak Haiku, przez pole model może obniżyć koszty.

Czy subagent może uruchamiać własne subagenty?

Tak, domyślnie do trzech poziomów poniżej głównej rozmowy. Żeby zabronić tego konkretnemu subagentowi, pomiń Agent na jego liście tools.

Czy mogę uruchomić całą sesję jako subagenta?

Tak. Uruchom Claude Code poleceniem claude --agent z nazwą subagenta, a sesja użyje jego promptu, narzędzi i modelu.