Wyjaśnienie podagentów Claude Code: czym są i kiedy ich używać.
W jaki sposób podagenty Claude Code różnią się od umiejętności i zespołów agentów: izolacja kontekstu, pierwszy dostosowany podagent, zasady opisywania i używania narzędzi oraz kiedy je pominąć.
Agenci to nie po prostu umiejętności w przebraniu
Powszechną pierwszą reakcją na agenty w Claude Code jest przekonanie, że są to umiejętności z dodatkowymi krokami, „mądrzejsze umiejętności”, które zachowują się bardziej autonomicznie, ponieważ ich instrukcje są sformułowane inaczej. To błędne postrzeganie. Agent to rzeczywiście prompt, podobnie jak umiejętność. Kluczowa różnica polega na tym, gdzie się uruchamia. Agent nie jest wykonywany w ramach głównej rozmowy – ma własne okno kontekstowe, własny prompt systemowy, dostęp do narzędzi oraz własne uprawnienia, działa w tle i zwraca wynik.
To, co następuje, zaczyna się od podstaw: czym są te agenci, jak stworzyć jednego oraz kiedy wysiłek się opłaca. Zakłada się, że już używasz Claude Code i chcesz właściwie zrozumieć tę funkcję przed zmianą jakichkolwiek ustawień. Kolejność to najpierw problem słownictwa, potem powody istnienia podagentów, następnie pierwszy dostosowany podagent, dalej różnice między nimi a umiejętnościami, praktyki pracy, krótki przegląd zespołów agentów i wreszcie przypadki, gdy agent jest niewłaściwym wyborem.
Cztery znaczenia słowa „agent”
W Claude Code słowo „agent” odnosi się co najmniej do czterech różnych rzeczy, a ich mylne traktowanie utrudnia zrozumienie całej tej funkcji. Trochę pedanterii tutaj się opłaca, ponieważ pozwala powiązać słownictwo z zasobami, których faktycznie możesz używać.
- Claude Code sam w sobie stanowi środowisko agentowe. Anthropic przedstawia go jako asystenta do kodowania o charakterze agentowym: posiada narzędzia oraz pętlę wykonywania zadań i może planować oraz działać w wielu krokach bez konieczności ponawiania instrukcji przy każdym z nich. Jest agentowym narzędziem jeszcze przed konfiguracją jakichkolwiek ustawień.
- Podagenty to spersonalizowane, wbudowane w produkt elementy typu agent. Gdy ktoś mówi, że buduje agenta w Claude Code, niemal zawsze ma na myśli podagenta. Zgodnie z oficjalną dokumentacją, są to specjalistyczni asystenci do wykonywania określonych zadań, z których każdy ma oddzielne okno kontekstowe, własną instrukcję systemową, określony dostęp do narzędzi oraz niezależne uprawnienia.
Pozostała część skupia się na drugim punkcie – podagentach. Zespoły zasługują na osobne potraktowanie później; szczegółowe wyjaśnienie jednego podagenta to odpowiednie miejsce na początek.
Dlaczego istnieją podagenty
Główną przyczyną jest to, że modele językowe mają ograniczony kontekst, więc prędzej czy później długa sesja osiąga ten limit. Bez jakichś środków zaradczych zdarza się to raz po raz.
Esej Anthropic o zarządzaniu kontekstem opisuje tę praktykę jako selekcję tego, co trafia do ograniczonego okna kontekstowego. Każde wezwanie narzędzia, odczyt pliku oraz nieukończona analiza są dodawane do kontekstu i tam pozostają. Im dłużej trwa sesja, tym więcej miejsca w tym oknie zajmują elementy pomocne przy znajdowaniu odpowiedzi, które później są bezużyteczne. Ten bałagan pogarsza jakość, a taki stan często określa się mianem degradacji kontekstu. Model ma wtedy mniej przestrzeni do pracy, a coraz więcej nieistotnych informacji konkujuje o jego uwagę.
Podagenty to jedno z rozwiązań. W opisie funkcji Claude Code jest to napisane wprost: podagent może przeczytać dziesiątki plików lub przeprowadzić rozległe wyszukiwania, ale główna rozmowa otrzymuje jedynie streszczenie, dzięki czemu praca pośrednia nigdy nie zużywa głównego kontekstu. To przydatne, gdy kroki pośrednie nie muszą być widoczne.
Konkretny przykład: prosisz Claude’a o ustalenie przyczyny niepowodzeń w zestawie testów. Badanie to, prowadzone w głównej sesji, polega na przeczytaniu dwudziestu plików, wyszukiwaniu wzorców błędów, sprawdzaniu konfiguracji testów oraz skanowaniu ostatnich zmian. Wszystko to trafia do twojego kontekstu. Pod koniec zużywasz kilka tysięcy tokenów na prace pośrednie, a prawie nic z tego nie wpływa na to, co robisz dalej.
Podagent przekształca problem. Badanie odbywa się w swoim własnym oknie kontekstowym i z własnym budżetem tokenów, a wynikiem jest krótka opinia w stylu „uszkodzenie wynika z zmiennej środowiskowej nieobecnej w konfiguracji CI; dotknięto trzech testów, oto naprawa”. Główny wątek nigdy nie przyswaja hałasu wynikającego z poszukiwań.
Głównym powodem jest izolacja kontekstowa, a do niej dochodzą jeszcze trzy mniejsze:
- Specjalizacja. Podagent posiada własny prompt systemowy. Skupiony recenzent z instrukcjami dotyczącymi standardów twojego zespołu będzie bardziej spójny w działaniu niż ogólny asystent, który próbuje przestrzegać tych standardów obok wszystkiego innego, co wie.
Tworzenie pierwszego dostosowanego podagenta
Technicznie rzecz biorąc, podagent to nic więcej niż dokument Markdown z nagłówkiem YAML. Dopuszczalne są dwa miejsca przechowywania:
.claude/agents/wewnątrz projektu, dla agentów powiązanych z tą bazą kodu. Zapisuj je, aby zespół mógł nimi dzielić się i je udoskonalać.
~/.claude/agents/ w katalogu domowym, przeznaczony dla agentów osobistych dostępnych we wszystkich projektach.Frontmatter wymaga uwagi
Ludzie zwykle przeglądają szybko YAML frontmatter, ale Claude Code przechowuje go w pamięci głównej sesji, aby dowiedzieć się, do czego służy każdy agent. W praktyce stanowi to streszczenie agenta. Dwa pola są obowiązkowe, a kilka innych opcjonalne. Prosty przykład pokazuje, jak one ze sobą współpracują:
---
name: code-reviewer
description: Reviews code changes for quality, security, and best practices.
Use proactively after any significant code change.
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. When invoked, read the changed files and provide
specific, actionable feedback on code quality, security, and best practices.
Focus on what matters. Don't restate what the code does — say what's wrong
or good about it. Flag security issues first, then logic problems, then style.
Krok po kroku:
nameto unikalny identyfikator, pisany małymi literami i zawierający wyłącznie myślniki. Jest pokazywany w logach, a Claude używa go do wewnętrznego nazewnictwa agenta.descriptionma największe znaczenie. Claude korzysta z niej, aby ustalić, czy dana zadanie należy do tego agenta; dlatego powinna opisywać jego zachowanie: jakie zadania wykonuje oraz w jakich sytuacjach należy go użyć. Dodanie frazy „używać proaktywnie” jest udokumentowanym sygnałem dla Claude, aby aktywował agent bez czekania na wyraźną prośbę. Należy pominąć tę frazę, jeśli agent powinien odpowiadać tylko wtedy, gdy zostanie o to bezpośrednio poproszony.
tools określa, do czego może mieć dostęp agent. Wspomniany wyżej recenzent może czytać pliki i wyszukiwać, ale nie może edytować ich, wykonywać poleceń w shellu ani nawiązywać połączeń sieciowych. Jest to celowe – recenzent z dostępem tylko do odczytu nie może przypadkowo zmienić tego, co recenzuje. Sama dokumentacja zaleca przyznanie tylko tych narzędzi, których agent potrzebuje, ze względu na bezpieczeństwo i aby zachowanie agenta było przewidywalne.model kieruje agenta do określonego modelu: sonnet, opus, haiku lub pełnego identyfikatora, takiego jak claude-opus-4-6. Bez niego agent używa opcji inherit, co oznacza użycie tego samego modelu co w głównej sesji.Pełna lista pól opcjonalnych pokazuje, ile jeszcze można dostosować: permissionMode, maxTurns, skills, mcpServers, effort, memory, hooks, disallowedTools, color oraz inne.
Widząc jeden agenta, możesz pomyśleć, że jest on bliski koncepcji umiejętności. Masz częściowo rację, ale jednocześnie pomijasz istotę sprawy, którą wyjaśniają następne sekcje.
Gdzie umieścić plik
Zapisz przykład jako .claude/agents/code-reviewer.md w projekcie. Otrzymany układ będzie wyglądał tak:
your-project/
├── .claude/
│ ├── agents/
│ │ └── code-reviewer.md ← your new agent file
│ ├── skills/
│ └── rules/
├── src/
├── tests/
├── README.md
└── package.json
Po zapisaniu Claude wykrywa agenta. Poproś go o przejrzenie zmian w kodzie, a on samodzielnie przekaże zadanie code-reviewer, w zależności od tego, jak dobrze prośba odpowiada opisowi. W przypadku agenta osobistego, który działa we wszystkich projektach, przenieś plik do ~/.claude/agents/code-reviewer.md. Format i treść pozostają identyczne; zmienia się tylko lokalizacja.
Agenci versus umiejętności
Dlaczego te dwa pojęcia są mylone
Trzy podobieństwa tłumaczą większość pomyłek:
- Oba są konfigurowane za pomocą prostej struktury folderów, wewnątrz
.claude/skillslub.claude/agents. - Oba wykorzystują frontmatter, a w obu opis jest najważniejszym ustawieniem.
- Oba stanowią zbiór instrukcji, innymi słowy promptów. Umiejętność i agent mogą zawierać dokładnie te same słowa.
Patrząc w ten sposób, wyglądają podobnie pod względem strukturalnym.
Gdzie odbywa się praca
Jednak istnieje jedna widoczna, praktyczna różnica, która je oddziela: miejsce wykonywania pracy, to znaczy miejsce wydawania tokenów. To najprostsze rozróżnienie do zrozumienia.
- Umiejętność jest włączana do bieżącej rozmowy. Jej instrukcje, szablony i pliki pomocnicze dołączają do aktywnego kontekstu, Claude przetwarza je w tym samym wątku, a każdy krok jest pokazywany w głównym oknie.
- Podagent działa oddzielnie w swoim własnym oknie kontekstowym. Wykonuje pracę, a główna rozmowa otrzymuje wynik.
Powierzchnia dostrojowania
Raniej istniała długa lista pól, które agent może ustawić w swoim frontmatterze. Natomiast umiejętności akceptują znacznie krótszą listę, częściowo też inną. To wskazuje na to, jak większą kontrolę dają agenci. Nie chodzi o to, by wszystko przekształcać w agenta. Chodzi raczej o to, że model mentalny używany do projektowania niezawodnego rozwiązania może wymagać ponownego przemyślenia.
Jedno zadanie, dwa rozwiązania
Weźmy przykład sytuacji, gdy chcemy, aby standardy przeglądu kodu w zespole były stosowane spójnie.
Gdyby Claude miał być świadomy tych standardów przez całą sesję, używać ich podczas pisania kodu, cytować je w radach i wskazywać na ich naruszenia w miarę pojawiania się, odpowiednia będzie umiejętność. Standardy należy napisać raz, a Claude wykorzysta je w odpowiednim kontekście, dzięki czemu wszystko, co zostanie zrobione podczas sesji, będzie mogło na nich polegać.
Jeśli zamiast tego chcesz, aby czterdzieści plików zostało przejrzanych za jednym razem, bez wypełniania głównego kontekstu informacjami o odczytywaniu plików, komentarzami tymczasowymi i wynikami wyszukiwania, to potrzebny jest subagent. Skonfiguruj agent do przeglądania kodu, pozwól mu działać w osobnym oknie i otrzymaj ustrukturyzowany podsumowanie. Możesz nawet uruchomić czterdzieści subagentów równolegle, po jednym na plik. Główna rozmowa otrzymuje wynik bez informacji o procesie, który go wygenerował.
Jedno zdanie oddaje tę różnicę: umiejętność zmienia to, co wie Claude lub sposób, w jaki podchodzi do procesu pracy, natomiast subagent zmienia to, kto wykonywa pracę, w jakim kontekście i przy użyciu jakich narzędzi.
Praktyki pracy, które się sprawdzają
Traktuj opis jako interfejs kierowania
To nie otrzymuje tak dużego nacisku, jak powinno. Claude czyta opisy podagentów, aby zdecydować, kiedy przekazać zadanie, i nie czyta treści wiadomości przed podjęciem decyzji. Wszystko, co wpiszesz do treści promptu, pozostaje niewidoczne, dopóki podagent nie zostanie utworzony. Dlatego opis musi zawierać wystarczająco dużo informacji, aby Claude wiedział, kiedy agent jest potrzebny.
- Używaj konkretnych, opisujących zachowanie sformułowań.
- Określ, co robi agent oraz w jakich sytuacjach należy go wybrać.
- Wymień rodzaje zadań, które radzi sobie dobrze, a jeśli to przydatne, te, których nie powinien podejmować.
- „Używaj proaktywnie po zmianach w kodzie” to sprawdzone rozwiązanie, o którym mowa w dokumentacji jako o sposobie zachęcania do delegowania zadań bez wyraźnej prośby. Pomiń to w przypadku agentów, które powinny działać tylko po bezpośrednim wezwaniu.
Aby zobaczyć tę różnicę, umieść niejasny opis („Pomaga w utrzymaniu jakości kodu i wykonywaniu zadań recenzji”) obok opisu przeznaczonego do routingu: „Sprawdza zmiany pod kątem luk bezpieczeństwa, błędów logicznych i problemów ze stylem. Należy go uruchomić proaktywnie po każdej znaczącej modyfikacji. Nigdy nie pisze kodu ani nie edytuje plików.”
Celowo ograniczaj narzędzia
Agent, który dziedziczy wszystkie narzędzia z głównej sesji, sprawia trudności w analizie sytuacji w przypadku problemów. Udzielaj dostępu tylko do tego, co jest potrzebne do wykonywania zadania.
- Recenzent powinien móc tylko czytać, nic więcej: bez możliwości pisania, bez dostępu do wiersza poleceń, bez połączenia sieciowego.
- Praca badawcza wymaga wyszukiwania i pobierania danych, bez możliwości edycji plików.
- Przeprowadzanie testów wymaga dostępu do Bash, ale nie ma powodu, by ingerować w funkcjonowanie sieci.
Ograniczenie dostępnych narzędzi pomaga w zapewnieniu bezpieczeństwa i klarowności. Ograniczony zestaw narzędzi sprawia, że zachowanie agenta jest przewidywalne, a gdy agent zawodzi lub zwraca nieoczekiwane wyniki, krótka lista dostępnych narzędzi przyspiesza diagnozę. Ponadto sprawia to, że możliwe sposoby awarii są ograniczone i łatwe do zidentyfikowania. Pole disallowedTools pozwala agentowi odziedziczyć narzędzia z głównej sesji, a następnie usunąć określone z nich, co nadaje się w przypadkach takich jak „wszystko oprócz Bash” lub „wszystko oprócz funkcji Write”.
Przypisz każdemu agencie jedno zadanie
Dokumentacja dotycząca podagentów jasno stwierdza, że każdy z nich powinien doskonale radzić sobie tylko z jednym zadaniem. Opis taki jak „przegląda kod, pisze testy, aktualizuje dokumentację i zajmuje się sprawdzaniem procesu wdrażania” umieszcza cztery różne funkcje w jednym polu. Claude może je przekierowywać nierównomiernie, a prompt systemu musi radzić sobie jednocześnie z czterema trybami działania.
Należy zawęzić zakres i stworzyć trzy oddzielne pliki, z których każdy będzie zawierał jeden jasno sformułowany opis. W naukach o danych mogą to być agent do walidacji modeli, narzędzie do sprawdzania jakości danych oraz osoba przeglądająca notatniki. W programowaniu mogą to być recenzent kodu, generator testów oraz osoba aktualizująca dokumentację. Zasada ta obowiązuje we wszystkich dziedzinach – każdy agent ma jedno zadanie, swój własny plik oraz opis, który umożliwia jednoznaczne przekierowanie.
Wykorzystaj pole dotyczące modelu do zarządzania kosztami
Ludzie, którzy jeszcze nie zostali zaskoczeni rachunkiem za korzystanie, najczęściej ignorują to pole. Ustawienie model: haiku w lżejszych agentach znacząco obniża koszty, gdy w jednej sesji działa kilka agentów. Ustawienie model: opus w agencie, który musi długo analizować duży kontekst, usprawiedliwia jego wysoką cenę. Pozostawienie wartości domyślnej, inherit, oznacza, że każdy agent korzysta z tego samego modelu co główna sesja – często najpotężniejszego modelu – stosowanego jednakowo do zadań, które go nie wymagają.
To, na czym zgodziła się społeczność
Katalog podagentów VoltAgent zawiera ponad sto specjalistycznych podagentów, obejmujących ekspertów od języków, audytorów bezpieczeństwa, narzędzia do debugowania, pomocników w obsłudze infrastruktury oraz orkiestratorów. Kolejna przydatna grupa znajduje się w repozytorium Everything Claude Code. Niewielu ludzi potrzebuje nawet jednej piątej z nich, więc liczba nie jest tym najważniejszym – kluczowa jest struktura. Każda pozycja w tych katalogach ma wąski zakres działania, czy to specjalista od TypeScript, ekspert od SQL, operator Kubernetesa czy audytor bezpieczeństwa. Żaden z nich nie próbuje obejmować więcej niż jednej dziedziny. Taki jest konsensus po ponad roku rzeczywistego użytkowania: wiele specjalizowanych agentów radzi sobie lepiej niż jeden agent o zastosowaniu uniwersalnym.
Zespoły agentów są godne poznania, ale stanowią różną funkcjonalność od podagentów.
Podagenty działają w ramach jednej sesji. Główna instancja Claude Code je tworzy, one pracują w izolacji i zwracają wyniki, a ty pozostajesz orkiestratorem.
Zespoły agentów to niezależne sesje Claude Code, które komunikują się ze sobą za pośrednictwem wspólnej listy zadań oraz bezpośredniej komunikacji między członkami zespołu. Każdy członek zespołu ma swój własny okno kontekstowe i stan sesji, a także może przydzielać zadania innym oraz je otrzymywać.
Dokumentacja dotycząca zespołów wskazuje, gdzie dodatkowe narzędzia są przydatne: podczas badań lub przeglądów, gdy kilku członków zespołu razem analizuje różne aspekty; podczas debugowania poprzez testowanie sprzecznych hipotez, przy którym członkowie zespołu krytykują wzajemnie swoje teorie; oraz przy tworzeniu nowych modułów, gdzie każdy członek zespołu odpowiada za swój własny komponent i unika kolizji z innymi.
Ustawienie ich nie jest proste, więc wykraczają poza zakres omawiania tutaj, i nie ma powodu, by podążać za trendem z obawy przed utratą możliwości. Zespoły dodają nakład pracy związany z koordynacją i zużywają znacznie więcej tokenów, ponieważ każdy członek zespołu ma własne okno kontekstowe, za które pobierana jest odrębna opłata. Są to rozwiązania eksperymentalne i domyślnie wyłączone, a ich włączenie odbywa się poprzez zmienną środowiskową.
Praktyczna zasada: dopóki twoje podagenty zgłaszają ci wyniki i nie muszą ze sobą rozmawiać, zespoły nie są potrzebne. Gdy jeden podagent musi przekazać ustalenia drugiemu lub zakwestionować jego wnioski, taka rozbudowa zaczyna się opłacać. Do tego momentu wystarczą podagenty.
Gdy agent jest niewłaściwym narzędziem
Wskazówki samej firmy Anthropic dotyczące tworzenia skutecznych agentów zasługują na poważne potraktowanie. Zaleca ona znajdowanie najprostszej możliwej rozwiązania i dodawanie złożoności tylko wtedy, gdy jest to konieczne, co może oznaczać nawet rezygnację z budowania systemów agentowych.
To odnosi się bezpośrednio do kilku sytuacji, w których subagent dodaje tylko trudności i nie przynosi żadnych korzyści:
- Zadania jednorazowe. Subagent generuje dodatkowy nakład pracy: nadawanie nazwy, pisanie opisu, wybieranie narzędzi, testowanie, konserwacja. Zadanie, które wykonasz tylko raz, nie usprawiedliwia tego wysiłku, dlatego lepiej napisz dobrze sformułowany prompt. Inwestycja ta opłaca się tylko wtedy, gdy proces powtarza się wystarczająco często, by warto było utrzymywać jego definicję.
Ogólną zasadą jest korzystanie z najprostszego narzędzia, które rozwiązuje rzeczywisty problem. Dodawaj agenty wtedy, gdy problemem jest izolacja kontekstu, specjalistyczne ograniczenia lub dedykowana eksploatacja, a nie dlatego, że agenty wydają się potężniejsze.
Wersja skrócona
Proście mówiąc, podagenty zarządzają kontekstem i wyznaczają granice wykonywania zadań, chociaż większość ludzi postrzega je jako dodatkową przewagę.
Jeden starannie skonfigurowany agent to rozsądna ilość pracy na popołudnie. Nie ma tu potrzeby systemu orkiestracji, by osiągnąć pożądany efekt: wystarczy precyzyjny opis, ograniczony zestaw narzędzi oraz jedno jasno określone zadanie. Złożoność może się od tego rozwijać, ale nie musi zaczynać się właśnie stąd.
Warto zadać sobie kilka pytań. Które zadanie w obecnym procesie pracy najchętniej przekazałbyś izolowanemu pracownikowi i co ci w tym przeszkadza? Jeśli już używasz podagentów, jakie było pierwsze zadanie, w którym izolacja naprawdę była istotna, a jego wykonywanie w głównej sesji spowodowałoby poważny problem? I jak zarządzasz dostępem do narzędzi: poprzez ograniczenia dla poszczególnych agentów czy poprzez dziedziczenie z głównej sesji z późniejszym jej dostosowaniem?
Literatura pokrewna
- Claude Code Agent Teams: Kiedy przejść na Multi-Agent i jak to zrobić — Kiedy jeden agent wystarcza, cztery powody do dodania kolejnych, wzorce orkiestracji, style komunikacji, osiem sposobów awarii oraz wybór między wersją wbudowaną a samodzielnie stworzoną dla zespołów Claude Code.
- DS-STAR wyjaśniony: agent do nauk o danych od Google i dlaczego jego rozwiązanie jest skuteczne — Przewodnik po agencie do nauk o danych DS-STAR od Google: jego siedem modułów, pętla raportowania DS-STAR+, opublikowane instrukcje, wyniki testów ablacji oraz istniejące ograniczenia.