# Podagenci Claude Code: struktura, pięć ról i orkiestracja > Plik agenta, opis, pięć kompletnych szablonów, równoległe wykonywanie, Managed Agents, ograniczenia i koszty z zachowanymi przykładami. Source: https://ailoot.ai/blog/pl/claude-code-subagents/ Canonical: https://ailoot.ai/blog/pl/claude-code-subagents/ Language: pl Publisher: Ailoot (https://ailoot.ai/) Translation: guide-222 Revision: sha256-d5f04530fbd11a60de062360a8dd994aab0b3be7b00d33efd4adb3e7c396af0e
Najważniejsze wnioski Podagent w Claude Code to wyspecjalizowany asystent AI z własnym kontekstem, zestawem narzędzi i promptem systemowym. Główny czat sam decyduje, czy delegować mu zadanie, albo możesz wywołać go po nazwie za pomocą `@agent-`. Podagent wykonuje wąskie zadanie bez zaśmiecania głównej rozmowy i zwraca tylko końcowe podsumowanie. W tym poradniku wyjaśniam, czym podagent różni się od Skill, jak napisać opis, aby Claude rzeczywiście go wywoływał, oraz jak w 30 minut przygotować 5 działających ról.
Praktyczne instrukcje dotyczące pracy z Ailoot znajdziesz w [dokumentacji](https://ailoot.ai/docs/).
## Czym jest podagent w Claude Code i dlaczego to nie jest „kolejny Skill”?
Najważniejsze wnioski Podagent to wyspecjalizowany asystent AI z własnym kontekstem, promptem systemowym i zestawem narzędzi. Oficjalna dokumentacja Anthropic opisuje go jako asystenta, który podejmuje się pobocznego zadania w osobnym kontekście i zwraca tylko podsumowanie wyniku. W przeciwieństwie do [Skills](https://ailoot.ai/blog/pl/claude-code-skills-library/), które ładują się do głównego czatu i korzystają z jego pamięci, podagent działa w izolacji — i właśnie na tym polega jego główna wartość.
Dokumentacja Claude Code definiuje go tak:

Podagenci to wyspecjalizowani asystenci AI do określonych rodzajów zadań. Użyj podagenta, gdy zadanie poboczne zapełniłoby główną rozmowę wynikami wyszukiwania, logami lub zawartością plików, do których nie będziesz wracać: podagent wykonuje tę pracę we własnym kontekście i zwraca tylko wynik.

— Dokumentacja Claude Code, https://code.claude.com/docs/en/sub-agents
Mówiąc językiem zrozumiałym dla przedsiębiorcy: wyobraź sobie agencję nieruchomości. Jest dyrektor, marketer, prawnik i menedżerowie sprzedaży. Pracownik, który przełącza się między tymi wszystkimi rolami, nie tworzy zespołu — to przeciążona osoba. Zespół powstaje wtedy, gdy każda osoba ma własny kontekst i obszar odpowiedzialności, a dyrektor tylko przydziela zadania i łączy wyniki. Podagenci w Claude Code działają tak samo. Główny czat jest dyrektorem. Podagent to specjalista z wąskim zadaniem, własnym kontekstem i zestawem narzędzi. Gdy zadanie pasuje do opisu specjalisty, dyrektor mu je deleguje — i nie grzęźnie w szczegółach. ### 5 celów, dla których Anthropic stworzył podagentów Dokumentacja Anthropic wymienia dokładnie pięć powodów, dla których warto tworzyć własnego podagenta:

Podagenci pomagają zachować kontekst, utrzymując badania i implementację poza główną rozmową; egzekwować ograniczenia przez limitowanie narzędzi dostępnych podagentowi; ponownie wykorzystywać konfiguracje w różnych projektach dzięki podagentom na poziomie użytkownika; specjalizować zachowanie w określonych domenach za pomocą ukierunkowanych promptów systemowych; oraz kontrolować koszty, kierując zadania do szybszych, tańszych modeli, takich jak Haiku.

— Dokumentacja Claude Code, https://code.claude.com/docs/en/sub-agents
Najbardziej praktycznym punktem na tej liście dla osoby niebędącej programistą jest **kontrola kosztów**. Możesz zlecić ciężkie zadanie badawcze niedrogiemu modelowi Haiku, a główną rozmowę kontynuować na Sonnet lub Opus. Oszczędność tokenów jest wprost proporcjonalna. ### Sprawdź obsługę zagnieżdżania w zainstalowanej wersji Szablony tego przewodnika zakładają jedną główną sesję delegującą bezpośrednio wykonawcom. Nie traktuj starszej dokumentacji „podagenci nie mogą uruchamiać innych podagentów” jako ponadczasowej zasady: zachowanie zależy od wersji i dozwolonych narzędzi. [Osobny przewodnik zagnieżdżonych podagentów](https://ailoot.ai/blog/pl/claude-code-nested-subagents/) opisuje receptę dla określonej wersji. Przed planowaniem głębszej delegacji sprawdź obsługę w swojej instalacji. ## Czym podagent różni się od Skill, polecenia ukośnikowego i hooka?
Najważniejsze wnioski Claude Code ma cztery mechanizmy rozszerzeń i nie są one zamienne. CLAUDE.md to trwała wiedza, która jest zawsze wczytywana. Skills to gotowe metodyki, które ładują się do głównego czatu po wyzwoleniu. Polecenia ukośnikowe to jawne przyciski `/command` do jednorazowych działań. Podagenci to specjaliści z własnym kontekstem, którym główny czat deleguje zadania. Najczęstszym błędem jest tworzenie podagenta tam, gdzie potrzebny jest Skill.
Poprzedni poradnik o [Skills](https://ailoot.ai/blog/pl/claude-code-skills-library/) wyjaśnia, że skills i polecenia ukośnikowe w Claude Code w praktyce połączyły się w jeden format. Podagent jest jednak innym bytem — nie jest po prostu „większym skillem”. Tabela podsumowująca cztery mechanizmy: | Cecha | CLAUDE.md | Skill | Polecenie ukośnikowe | Podagent | |----|----|----|----|----| | Kiedy się ładuje | Zawsze | Gdy opis pasuje do zadania | Po jawnym poleceniu `/name` | Przy delegowaniu lub `@agent-name` | | Gdzie działa | W głównym kontekście | W głównym kontekście | W głównym kontekście | We własnym, odizolowanym kontekście | | Model | Taki sam jak główny czat | Taki sam | Taki sam | Dowolny — Haiku, Sonnet, Opus, dziedziczony | | Narzędzia | Wszystkie dostępne | Dziedziczone | Dziedziczone | Można je ograniczyć przez `tools:` | | Co zwraca | \- | W głównej rozmowie, bezpośrednio | Bezpośrednio | Tylko końcowe podsumowanie | | Równoległość | \- | Nie | Nie | Tak — wiele równolegle | | Pamięć między sesjami | Pliki w pobliżu | Pliki w pobliżu | Pliki w pobliżu | Pole `memory: user/project/local` | Dobrym sposobem ujęcia tego w anglojęzycznym poradniku jest: skills to przepisy, a podagenci to wyspecjalizowani współpracownicy. Put simply: skills are recipes; subagents are specialized colleagues. W praktyce działa to tak: skills aktywują się automatycznie, gdy ich opis pasuje do zadania, natomiast podagenci są wywoływani jawnie — albo główny czat decyduje się delegować zadanie, albo wywołujesz podagenta po nazwie. ### Drzewo decyzyjne: „Którego użyć?” Gdy myślisz: „Chcę, żeby Claude zrobił X”, zadaj sobie te cztery pytania: 1. **Czy to wiedza, która powinna być zawsze dostępna?** Na przykład: „lokalizujemy treści na preferowany język użytkownika” albo „nie używamy pauz”. Umieść ją w `CLAUDE.md`. 2. **Czy to metodyka uruchamiana ręcznie, którą stosujesz?** Na przykład: „w każdy poniedziałek piszę raport sprzedaży”. Utwórz **skill**. 3. **Czy to zadanie, które pochłonie kontekst głównego czatu, albo można je uruchomić równolegle?** Na przykład: „dogłębne badanie 30 źródeł” albo „audyt bezpieczeństwa, gdy piszę nową funkcję”. Utwórz **podagenta**. 4. **Czy potrzebujesz automatycznej reakcji na zdarzenie w Claude Code?** Na przykład: „uruchom linter po każdej edycji”. Napisz **hook**. 90% zadań przedsiębiorcy należy do dwóch pierwszych kategorii. Podagenci to narzędzie na wyższym poziomie, przydatne, gdy przechodzisz od „jednego zadania naraz” do orkiestracji. ## Gdzie znajdują się podagenci i który ma pierwszeństwo?
Najważniejsze wnioski Podagenci Claude Code znajdują się w pięciu miejscach o różnym priorytecie — od zarządzanych ustawień organizacji po wtyczki. Jeśli dwa pliki mają tę samą nazwę, wygrywa ten z wyższym priorytetem. Najczęstsza konfiguracja dla samodzielnego przedsiębiorcy to `~/.claude/agents/` dla osobistych agentów ogólnego przeznaczenia oraz `.claude/agents/` w konkretnym projekcie dla agentów projektowych.
Hierarchia podagentów ma pięć poziomów, uporządkowanych od najwyższego do najniższego priorytetu: | Poziom | Ścieżka | Zakres | Priorytet | |----|----|----|----| | Enterprise | Zarządzane ustawienia organizacji | Wszyscy pracownicy firmy | 1 (najwyższy) | | Sesja | Flaga CLI `--agents` z JSON | Tylko bieżąca sesja | 2 | | Projekt | `.claude/agents/name.md` | Tylko ten projekt | 3 | | Osobisty | `~/.claude/agents/name.md` | Wszystkie Twoje projekty | 4 | | Wtyczka | `/agents/name.md` | Wszędzie, gdzie włączono wtyczkę | 5 (najniższy) | Logika priorytetów jest taka sama jak w przypadku Skills i CLAUDE.md: organizacja ma pierwszeństwo przed CLI, CLI przed projektem, projekt przed ustawieniami osobistymi, a ustawienia osobiste przed wtyczką. ### Co warto wiedzieć o wczytywaniu Podagenci ładują się przy uruchomieniu sesji Claude Code. Jeśli ręcznie edytujesz plik agenta na dysku, zmiany nie zostaną wczytane, dopóki nie uruchomisz ponownie sesji. Edycje wykonane w interaktywnym interfejsie `/agents` obowiązują natychmiast. Jeden podagent na zakres oznacza jeden plik. Jeśli `.claude/agents/` zawiera `code-reviewer.md` i drugi `code-reviewer.md` obok niego (na przykład ze starej kopii zapasowej), Claude Code po cichu zignoruje jeden z nich. Nie wyświetli żadnego powiadomienia. Podagenci wtyczek to osobna kwestia. Podlegają ograniczeniom bezpieczeństwa: **nie obsługują** pól `hooks`, `mcpServers` i `permissionMode`. Zapobiega to sytuacji, w której instalacja wtyczki innej firmy daje jej prawo do uruchamiania dowolnego kodu na Twoim komputerze. ## Jak zbudowany jest plik podagenta: frontmatter i treść
Najważniejsze wnioski Podagent to pojedynczy plik Markdown z frontmatter YAML u góry i promptem systemowym poniżej. Minimum to dwa pola: `name` (małe litery + łączniki) i `description` (kiedy Claude powinien delegować zadanie). Pełny schemat zawiera 16 pól: tools, disallowedTools, model, permissionMode, maxTurns, skills, mcpServers, hooks, memory, background, effort, isolation, color, initialPrompt. Anthropic zaleca zwięzły opis — im wyraźniejszy sygnał, tym trafniej Claude aktywuje podagenta.
Minimalny przykład z oficjalnej dokumentacji — zaledwie 9 linii: ```markdown --- name: code-reviewer description: Reviews code for quality and best practices tools: Read, Glob, Grep model: sonnet --- Jesteś recenzentem kodu. Po wywołaniu przeanalizuj kod i przekaż konkretne, możliwe do wdrożenia uwagi dotyczące jakości, bezpieczeństwa i dobrych praktyk. ``` To wystarczy. Jeśli użytkownik napisze na głównym czacie „sprawdź moje PR”, Claude dopasuje „recenzent / kod / jakość” do opisu i deleguje zadanie podagentowi. Podagent odczyta diff, przygotuje komentarze i zwróci podsumowanie do głównego czatu. Główny czat nie zostanie zaśmiecony logami ani analizą pośrednią. ### Pełny schemat frontmatter | Pole | Wymagane | Działanie | |----|----|----| | `name` | Tak | Unikalny identyfikator, małe litery + łączniki. Nazwa pliku NIE musi być taka sama | | `description` | Tak | Kiedy Claude deleguje. To wyzwalacz automatyzacji | | `tools` | Nie | Lista dozwolonych narzędzi. Jeśli ją pominięto, agent dziedziczy wszystkie narzędzia od nadrzędnego agenta | | `disallowedTools` | Nie | Lista blokowanych narzędzi. Stosowana NAJPIERW, a potem `tools` | | `model` | Nie | `haiku` / `sonnet` / `opus` / pełny ID / `inherit` (domyślnie) | | `permissionMode` | Nie | `default` / `acceptEdits` / `auto` / `dontAsk` / `bypassPermissions` / `plan` | | `maxTurns` | Nie | Limit kroków przed zatrzymaniem | | `skills` | Nie | Skills ładowane do kontekstu podagenta przy uruchomieniu | | `mcpServers` | Nie | Serwery MCP dostępne tylko dla tego podagenta | | `hooks` | Nie | PreToolUse / PostToolUse / Stop, ograniczone do tego podagenta | | `memory` | Nie | `user` / `project` / `local` — folder pamięci między sesjami | | `background` | Nie | `true` — zawsze działaj w tle. Domyślnie `false` | | `effort` | Nie | `low` / `medium` / `high` / `xhigh` / `max` — poziom rozumowania | | `isolation` | Nie | `worktree` — praca w osobnym git worktree | | `color` | Nie | Kolor UI: red / blue / green / yellow / purple / orange / pink / cyan | | `initialPrompt` | Nie | Pierwsze zdanie wyświetlane podagentowi uruchomionemu przez `--agent` | Pole `model: haiku` realizuje wspomniany „cel kontroli kosztów”. Jeśli masz agenta badawczego, który czyta 50 stron dokumentacji, uruchom go na Haiku, aby zaoszczędzić 5–7 razy w porównaniu z Opus. Pole `isolation: worktree` rozwiązuje ważny problem: podagent wprowadza potencjalnie niebezpieczne zmiany (refaktoryzację, migrację), ale nie chcesz, aby modyfikował Twoją kopię roboczą. Ustaw `isolation: worktree`, a Claude Code utworzy tymczasową kopię git projektu; podagent będzie tam pracować i zwróci diff do sprawdzenia. ### Treść pliku to prompt systemowy Po frontmatter znajduje się zwykły Markdown, czyli prompt systemowy podagenta. Nie jest wymagana specjalna struktura, ale sprawdzony schemat wygląda tak: 1. **Kim jesteś** — jedno zdanie: „jesteś recenzentem kodu”, „jesteś audytorem bezpieczeństwa”, „jesteś opiekunem dokumentacji”. 2. **Kiedy jesteś wywoływany i co robisz najpierw** — pierwsze 2–3 działania po otrzymaniu zadania. 3. **Lista kontrolna sprawdzeń lub kroków** — 5–10 punktów, których podagent ma przestrzegać. 4. **Co zwracasz** — format końcowego raportu. To kluczowe: jeśli go nie określisz, podagent przygotuje „esej” zamiast uporządkowanego podsumowania. 5. **Czego NIE robisz** — jawne ograniczenia. Bez tej sekcji podagent zaczyna improwizować. Treść pliku powinna mieć 200–500 linii. Jeśli jest dłuższa, przenieś obszerne materiały referencyjne do osobnych plików w pobliżu i dodaj do nich odnośniki w prompcie. ## Jak napisać opis, aby Claude na pewno wywołał podagenta
Najważniejsze wnioski Description to jedyne pole, które Claude widzi na początku sesji i wykorzystuje do podjęcia decyzji o delegowaniu. Najczęstsza skarga na forach brzmi: „Napisałem podagenta, ale Claude go nie wywołuje”. Rozwiązanie to trzyczęściowa formuła: co robi + frazy wyzwalające w cudzysłowie + kiedy NIE używać. Anthropic wyraźnie zaleca dodanie do opisu zwrotów takich jak „use proactively” lub „use immediately after”, które zachęcają Claude do wywoływania podagenta.
Częstym problemem jest skonfigurowanie subagenta do przeglądu kodu, po czym Claude wykonuje wszystko sam, nie korzystając z agenta. Zwykle jest jeden powód: opis brzmi „Helper for code review”. Claude nie wie, kiedy go uruchomić. ### Formuła skutecznego opisu (3 części) **Część 1 — co robi.** Jedno zdanie o wyniku, a nie o procesie. Nie „analizuje kod”, lecz „znajduje luki w zabezpieczeniach kodu i zwraca listę z poziomem ważności oraz poprawką”. **Część 2 — kiedy go uruchamiać.** 3–5 fraz w cudzysłowie, odpowiadających rzeczywistym prośbom użytkowników. Nie zgaduj — sprawdź historię czatu i prawdziwe sformułowania. **Część 3 — kiedy go NIE uruchamiać.** 1–2 frazy opisujące podobne zadania, na które ten podagent nie powinien odpowiadać. Bez tej sekcji dwa podobne agenty będą nieustannie ze sobą konkurować. ### Magiczna fraza „Use Proactively” Oficjalna dokumentacja Anthropic zawiera bezpośrednie zalecenie:

Claude automatycznie deleguje zadania na podstawie opisu zadania w Twoim żądaniu, pola description w konfiguracji podagenta i bieżącego kontekstu. Aby zachęcić do proaktywnego delegowania, dodaj do opisu podagenta zwroty takie jak 'use proactively'.

— Dokumentacja Claude Code, https://code.claude.com/docs/en/sub-agents
Innymi słowy, Claude domyślnie **niechętnie** wywołuje podagenta, jeśli jego opis nie zawiera wyraźnych sygnałów. Dodaj „use proactively” albo „use immediately after writing code”, a aktywacja gwałtownie wzrośnie. ### Tak wygląda dobry opis ```yaml description: | Specjalista od eksperckiego przeglądu kodu. Proaktywnie sprawdza kod pod kątem jakości, bezpieczeństwa i łatwości utrzymania. Używaj natychmiast po napisaniu lub zmodyfikowaniu kodu. Zwraca uporządkowaną według priorytetów listę problemów wraz z ich ważnością i zaleceniami dotyczącymi poprawek. Nie wywołuj go przy zmianach w dokumentacji, edycjach README ani przeredagowaniu treści commitów — tym zajmuje się doc-maintainer. ``` Co tu działa: - Czasowniki „sprawdza” + „zwraca” określają konkretny wynik, a nie proces. - „Proaktywnie” i „natychmiast po” to jawne sygnały wyzwalające. - „Nie wywołuj przy...” zapobiega konfliktowi z podobnym podagentem. - Opisy po angielsku są standardem. Claude lepiej je dopasowuje. ## 5 gotowych ról podagentów, które skonfigurujesz w 10 minut
Najważniejsze wnioski Aby nie pisać pierwszego podagenta od zera, skorzystaj ze sprawdzonych wzorców i dostosuj je do swoich potrzeb. Przedstawiam 5 ról obejmujących typowe zadania: code-reviewer (przegląd kodu po zmianach), security-auditor (wyszukiwanie luk i wycieków), research-agent (dogłębne badanie co najmniej 8 źródeł), doc-maintainer (synchronizacja dokumentacji z kodem) i refactor-agent (bezpieczna refaktoryzacja w git worktree). Każda zawiera gotowy szablon do skopiowania i dostosowania.
Każda z poniższych ról to pojedynczy plik `.claude/agents/.md`. Po utworzeniu pliku uruchom ponownie Claude Code, otwórz `/agents` i sprawdź, czy nowy agent pojawił się na liście. Następnie możesz go wywołać przez `@agent-name`. ### 1. code-reviewer — przegląd kodu po każdej zmianie To oficjalny przykład z dokumentacji Anthropic, dostosowany do procesu pracy: ```markdown --- name: code-reviewer description: | Specjalista od eksperckiego przeglądu kodu. Proaktywnie sprawdza kod pod kątem jakości, bezpieczeństwa i łatwości utrzymania. Używaj natychmiast po napisaniu lub zmodyfikowaniu kodu. tools: Read, Grep, Glob model: inherit color: blue --- Jesteś starszym recenzentem kodu, dbającym o wysoką jakość. Po wywołaniu: 1. Przeczytaj różnice i listę zmienionych plików przekazane przez główną sesję. Jeśli ich brak, poproś główną sesję o dostarczenie. 2. Użyj Read, Grep i Glob do sprawdzenia właściwych plików. 3. Zwróć ustalenia bez zmiany plików i uruchamiania poleceń powłoki. Lista kontrolna: - Kod jest jasny i czytelny - Funkcje i zmienne mają dobre nazwy - Nie ma zduplikowanego kodu - Obsługa błędów jest odpowiednia - Nie ujawniono sekretów ani kluczy API - Wdrożono walidację danych wejściowych - Zakres testów jest wystarczający - Uwzględniono kwestie wydajności Przekaż uwagi uporządkowane według priorytetu: - Krytyczne problemy (trzeba je naprawić przed scaleniem) - Ostrzeżenia (należy je naprawić) - Sugestie (warto rozważyć ulepszenie) Format: dla każdego problemu podaj plik:linia + 1 zdanie wyjaśniające, na czym polega problem + konkretną poprawkę. ``` Kluczowe jest `tools: Read, Grep, Glob`: recenzent ma narzędzia odczytu i wyszukiwania, bez Bash, Write i Edit. Główna sesja przygotowuje i przekazuje różnice. Sama instrukcja uruchamiania tylko `git diff` nie ogranicza w pełni przyznanego narzędzia Bash. ### 2. security-auditor — wyszukiwanie luk i wycieków Ta rola korzysta z `opus` dla głębszego rozumowania i tego samego ograniczenia do Read, Grep i Glob. Trwałą pamięć pominięto w szablonie tylko do odczytu, ponieważ jej włączenie daje także możliwość zapisywania pamięci: ```markdown --- name: security-auditor description: | Specjalista od audytów bezpieczeństwa. Używaj proaktywnie, aby wykrywać luki z OWASP Top 10, ujawnione sekrety, zagrożenia związane z wstrzyknięciami i błędy uwierzytelniania. Uruchamiaj przed każdym wdrożeniem lub scaleniem do main. tools: Read, Grep, Glob model: opus color: red --- Jesteś audytorem bezpieczeństwa. Szukaj luk, które można wykorzystać, a nie problemów stylistycznych. Lista kontrolna audytu: - Wstrzyknięcia SQL / NoSQL - XSS (przechowywane, odbite, oparte na DOM) - Ryzyka CSRF / SSRF - Zakodowane na stałe sekrety (klucze API, tokeny, hasła) - Błędy uwierzytelniania / zarządzania sesją - Niebezpieczna deserializacja - Brak walidacji danych wejściowych - Path traversal - Otwarte przekierowania - Niebezpieczne bezpośrednie odwołania do obiektów (IDOR) Dla każdego ustalenia podaj: - Ważność: Critical / High / Medium / Low - Plik:linia - Scenariusz ataku w 1–2 zdaniach - Zalecenie poprawki wraz z przykładem kodu Pomiń szum lintera i kwestie stylistyczne. Zgłaszaj tylko luki, które można wykorzystać. ``` Narzędzia tylko do odczytu, a `model: opus` służy do złożonych kontroli, takich jak łańcuchy luk. ### 3. research-agent — dogłębne badanie co najmniej 8 źródeł Ten wzorzec opisuje sam Anthropic w artykule o systemie badań wieloagentowych. Kluczowe są jawny format wyniku i zakaz zrzucania surowych rezultatów: ```markdown --- name: research-agent description: | Specjalista od dogłębnych badań internetowych. Używaj proaktywnie do ustalania faktów, analizy konkurencji, zbierania zewnętrznej dokumentacji i porównywania podejść na podstawie wielu źródeł. tools: WebFetch, WebSearch, Read, Write model: sonnet maxTurns: 30 color: purple --- Jesteś analitykiem badań. Celem jest syntetyczne opracowanie, a nie surowe wyniki wyszukiwania. Proces: 1. Podziel pytanie na 3–5 podzapytań 2. Użyj WebSearch dla każdego podzapytania i pobierz 3–5 najlepszych źródeł na podzapytanie 3. Zweryfikuj twierdzenia w co najmniej 2 niezależnych źródłach 4. Odrzucaj farmy SEO i agregatory; preferuj źródła pierwotne 5. Cytuj dosłownie z podaniem URL dla każdego szczegółowego twierdzenia 6. Zwróć: TL;DR (3 punkty) + Ustalenia + Źródła (co najmniej 8 domen) Antywzorce, których należy unikać: - Nie przytaczaj faktu opartego na jednym źródle - Nie parafrazuj cytatów tak, jakby były dosłowne - Nie zwracaj rodzicowi surowych zrzutów wyników wyszukiwania - Nie dodawaj pustego wstępu ani zakończenia („Mam nadzieję, że to pomoże”) ``` `maxTurns: 30` chroni przed niekończącymi się iteracjami badań. Anthropic podaje tę liczbę w swoim systemie wieloagentowym:

System wieloagentowy z Claude Opus 4 jako agentem wiodącym i Claude Sonnet 4 jako podagentami osiągnął wyniki o 90.2% lepsze niż pojedynczy Claude Opus 4.

— Anthropic Engineering, https://www.anthropic.com/engineering/multi-agent-research-system
Dziewięćdziesiąt procent dotyczy zadań z benchmarków badawczych. W praktyce wzrost jest mniejszy w zadaniach biznesowych, ale ogólna skala jest podobna. ### 4. doc-maintainer — synchronizacja dokumentacji z kodem Ta rola używa `model: haiku` — to typowy przykład „kontroli kosztów”. Dokumentacja nie wymaga Opus; Haiku radzi sobie z tym za jedną trzecią ceny: ```markdown --- name: doc-maintainer description: | Specjalista od synchronizacji dokumentacji. Po scaleniu funkcji aktualizuje README, dokumentację API i CHANGELOG. Czyta ostatnie commity, identyfikuje nieudokumentowane zmiany i proaktywnie aktualizuje dokumentację. tools: Read, Write, Edit, Glob, Grep, Bash model: haiku memory: project color: green --- Dbasz o synchronizację dokumentacji z kodem. Po wywołaniu: 1. Uruchom `git log --since="last release"`, aby zobaczyć ostatnie zmiany 2. Przeczytaj README.md, docs/, CHANGELOG.md 3. Znajdź braki: nowe funkcje bez dokumentacji, usunięte API nadal opisane w dokumentacji, niezgodne wersje Wynik: - Zaktualizowane pliki (używaj Edit, nie Write — zachowaj istniejącą strukturę) - Wpis w CHANGELOG.md w formacie Keep-A-Changelog - Lista wprowadzonych zmian (rzeczywiste podsumowanie diff, nie parafraza) Zasady stylu: - Strona czynna, czas teraźniejszy - Przykłady kodu muszą nadawać się do skopiowania i wklejenia - Bez języka marketingowego („potężny”, „solidny”, „bezproblemowy”) - Bez pustych formułek („Ten poradnik Ci pomoże... ”) ``` ### 5. refactor-agent — bezpieczna refaktoryzacja w worktree Ta rola używa `isolation: worktree` — podagent pracuje w osobnej kopii repozytorium, a Ty scalasz zmiany tylko wtedy, gdy wszystko jest w porządku: ```markdown --- name: refactor-agent description: | Specjalista od bezpiecznej refaktoryzacji. Używaj przy zmianach nazw, wydzielaniu i wstawianiu kodu, które nie powinny dotykać Twojej kopii roboczej przed sprawdzeniem. Działa w tymczasowym git worktree. tools: Read, Edit, Write, Bash, Grep, Glob model: sonnet isolation: worktree permissionMode: acceptEdits color: yellow --- Refaktoryzujesz kod bez zmiany jego zachowania. Ścisłe zasady: 1. Testy muszą przechodzić PRZED refaktoryzacją i PO niej. Jeśli testy przed refaktoryzacją nie przechodzą, ZATRZYMAJ SIĘ i zgłoś problem. 2. Jeden atomowy refaktor na commit (wydzielenie, zmiana nazwy, wstawienie). 3. Nigdy nie zmieniaj publicznego API bez jawnej instrukcji. 4. Nigdy nie modyfikuj testów, chyba że bezpośrednio sprawdzają refaktoryzowaną implementację. Proces: - Uruchom zestaw testów -> stan bazowy - Wykonaj atomowy refaktor - Uruchom zestaw testów -> weryfikacja - Zatwierdź ze standardowym komunikatem: refactor(scope): what Zwróć: podsumowanie zmian + ścieżkę worktree, aby użytkownik mógł porównać zmiany i je scalić. ``` Dzięki tej roli znika najbardziej uciążliwy problem refaktoryzacji — „coś zepsułem i nie wiem, jak to cofnąć” — ponieważ oryginalna kopia pozostaje nietknięta, a podagent pracuje w odizolowanym worktree. Chcesz nie tylko kopiować gotowych podagentów, ale złożyć **zestaw, który zmieni Claude w stabilne narzędzie**? Podagenci są częścią Twojego **klona AI**: sposobem na zapewnienie Claude wyspecjalizowanego zespołu pracującego według Twojej logiki. Trzy filary tej metodyki to: **klon AI** (Skills + podagenci) + **[Drugi Mózg](https://ailoot.ai/blog/pl/claude-code-second-brain/)** + **Inżynieria Kontekstu**. To połączenie zmienia Claude z asystenta, który zgaduje, w narzędzie myślące zgodnie z Twoją logiką. ## Uruchamianie 5 podagentów równolegle: orkiestrator + pracownicy
Najważniejsze wnioski Największą zaletą podagentów jest równoległe wykonywanie zadań. Jeden główny czat przechowuje plan, a pięciu (lub dziesięciu) wyspecjalizowanych podagentów jednocześnie pracuje nad różnymi etapami, każdy we własnym kontekście. Główny czat zbiera i sprawdza wyniki. Przyspiesza to pracę 3–5 razy w porównaniu z wykonywaniem sekwencyjnym, a także eliminuje „zanieczyszczenie kontekstu”, gdy główna rozmowa zostaje zasypana logami i analizą pośrednią.
Orkiestracja równoległa przypomina układ „dyrygent + orkiestra”. Dyrygent trzyma plan, nie zapisuje nut i sprawdza, co grają muzycy. Jeśli ktoś zagra fałszywą nutę, dyrygent prosi go o powtórzenie, zamiast próbować dokończyć za niego. Dla przedsiębiorcy bliższą analogią jest agencja marketingowa przygotowująca strategię dla nowego klienta. Jeden analityk robi analizę SWOT, drugi analizuje konkurencję, trzeci przygotowuje profil odbiorców, starszy analityk odrzuca hipotezy niepasujące do budżetu, a kierownik projektu składa końcową prezentację. W Claude Code taki potok zaczyna się od jednego zdania — a krytyk jest częścią procesu od początku, zamiast pojawiać się dopiero po fakcie. ### Minimalny prompt orkiestracji Wystarczy jedno zdanie na głównym czacie: ``` Uruchom równolegle pięciu podagentów: trzy research-agent na różnych źródłach (dokumentacja Anthropic, repozytoria GitHub, blogerzy AI), jednego critic-agent do odrzucania słabych wniosków i jednego summary-agent do przygotowania dokumentu końcowego. Kontekst: piszę poradnik o X. Docelowa długość: 2,000 słów ze źródłami. Przed rozpoczęciem każdy agent czyta CLAUDE.md. ``` Claude deleguje wtedy zadania pięciu agentom. Każdy pracuje we własnym kontekście: agenci badawczy korzystają z przypisanych im źródeł, krytyk je filtruje, a agent podsumowujący przygotowuje całość. Do głównego czatu wracają tylko końcowe podsumowania. ### Kiedy równoległość się opłaca Nie zawsze. Równoległe wykonywanie zadań ma sens tylko wtedy, gdy: 1. Zadania są **niezależne**. Jeśli research-agent #2 czeka na wynik research-agent #1, nie będzie równoległości — w praktyce będą pracować sekwencyjnie. 2. Zadania trwają **długo**. Równoległe wykonywanie „usuń końcowe białe znaki” nie ma sensu; koszt uruchomienia podagentów pochłonie zysk. 3. Masz **wystarczające limity**. Więcej na ten temat w osobnej sekcji poniżej — równoległe podagenci szybko zużywają tokeny. ### Wieloagentowy Multi-Agent v2 Anthropic: kolejny krok W maju 2026 roku Anthropic wypuścił Multi-Agent Orchestration v2 z trzema ważnymi różnicami w porównaniu z klasycznym podejściem polegającym na uruchamianiu równoległych podagentów. Więcej na ten temat w następnej sekcji. ## Co nowego w Multi-Agent v2: orkiestracja, Outcomes, Dreaming
Najważniejsze wnioski 6 maja 2026 roku, podczas konferencji Code with Claude w San Francisco, Anthropic ogłosił trzy funkcje Managed Agents v2 — wszystkie w publicznej wersji beta. Multi-Agent Orchestration pozwala agentowi wiodącemu dzielić pracę i delegować ją równolegle specjalistom korzystającym ze wspólnego systemu plików. Outcomes pozwala określić kryteria sukcesu, a osobny agent oceniający sprawdza wynik. Dreaming przypomina fazę REM: zaplanowany proces czyta wcześniejsze sesje, znajduje wzorce i aktualizuje pamięć agenta.
### Multi-Agent Orchestration: wspólny system plików + meldunki w trakcie pracy Anthropic opisuje tę funkcję tak:

Gdy pracy jest zbyt dużo dla jednego agenta, orkiestracja wieloagentowa pozwala agentowi wiodącemu podzielić zadanie na części i delegować je specjalistom z własnym modelem, promptem i narzędziami. Specjaliści pracują równolegle we wspólnym systemie plików i przekazują wyniki do wspólnego kontekstu agenta wiodącego.

— Anthropic - Nowości w Claude Managed Agents, https://claude.com/blog/new-in-claude-managed-agents
Kluczową różnicą w porównaniu z klasycznymi podagentami jest **wspólny system plików**. Wcześniej każdy podagent pracował w całkowitej izolacji, a wymiana informacji odbywała się wyłącznie za pośrednictwem zwracanego podsumowania. Teraz specjaliści mogą zapisywać wyniki we wspólnym folderze, a agent wiodący odczytuje je w miarę postępu prac, a nie dopiero na końcu. Rozwiązuje to problem sytuacji, w której „wszyscy pracowali cały dzień, a na koniec okazało się, że dwie osoby przyjęły niezgodne podejścia”. Drugą nowością są **meldunki w trakcie pracy**. Agent wiodący może zatrzymać się i zapytać dowolnego specjalistę „jak idzie?”, a następnie skorygować ogólny plan. Przypomina to sposób pracy prawdziwego kierownika zespołu. ### Outcomes: kryteria zamiast instrukcji krok po kroku W Outcomes określasz kryteria sukcesu, a agent znajduje sposób, by je spełnić. Osobny agent oceniający sprawdza wynik we własnym kontekście, dzięki czemu nie zostaje on „zanieczyszczony” rozumowaniem głównego agenta.

Poprawiło to skuteczność rozwiązywania zadań nawet o 10 punktów w porównaniu ze standardową pętlą promptowania, a największy wzrost odnotowano przy najtrudniejszych zadaniach.

— Anthropic - Nowości w Claude Managed Agents, https://claude.com/blog/new-in-claude-managed-agents
Dziesięć procent przy trudnych zadaniach to poważny wzrost. Szczególnie gdy zadanie brzmi „przygotuj długi artykuł spełniający te kryteria jakości”, a nie „wykonaj kroki 1–7”. ### Dreaming: agenci zdobywają doświadczenie między sesjami To najbardziej nowatorska koncepcyjnie funkcja. Agent przegląda wcześniejsze sesje, wyszukuje wzorce sukcesów i błędów oraz aktualizuje magazyn pamięci. Możesz skonfigurować ręczne sprawdzanie zmian przed ich zastosowaniem albo pozwolić agentowi samodzielnie edytować pamięć. Anthropic podaje, że Harvey (firma z branży technologii prawniczych) odnotował około sześciokrotny wzrost skuteczności zadań związanych ze sporządzaniem dokumentów prawnych po wdrożeniu Dreaming. To działa już na produkcji, a nie tylko w wersji demonstracyjnej. ### Co to oznacza dla przedsiębiorców, którzy nie programują Multi-Agent Orchestration jest obecnie dostępne przez Claude Agent SDK, a nie bezpośrednio w CLI Claude Code. Kierunek jest jednak jasny: orkiestracja przechodzi od „ręcznie uruchamiasz N podagentów” do „opisujesz zadanie, a agent wiodący decyduje, komu je delegować i jak”. Jeśli dopiero zaczynasz pracę z podagentami, na razie nie przejmuj się v2. Naucz się klasycznego wzorca „1 główny czat + 3–5 podagentów o różnych rolach”, a za 3–6 miesięcy możesz naturalnie przejść do Managed Agents. ## 7 błędów, które sprawiają, że podagenci nie działają
Najważniejsze wnioski Najczęstsze problemy z podagentami nie wynikają z błędów Claude, lecz z błędów w samych podagentach. Opisy bez fraz wyzwalających, próby użycia podagenta do zadania odpowiedniego dla Skill, uruchamianie 60 agentów równolegle „bo to fajne”, przyznawanie każdemu agentowi dostępu do wszystkich narzędzi, brak jawnego formatu wyniku, niejasne polecenia oraz architektura oparta na rolach zamiast na zadaniach. Każdy z tych błędów psuje albo aktywację, albo wyniki podagenta.
### Błąd 1. Opisy „Helper for X” nie wywołują podagenta Objaw: napisałeś podagenta, sprawdziłeś strukturę i wszystko jest poprawne, ale Claude nie wywołuje go w odpowiedzi na prośby użytkowników. Powód jest niemal zawsze ten sam: opis jest abstrakcyjny, na przykład „Helper for code review”. Rozwiązanie: wpisz bezpośrednio w opisie 3–5 rzeczywistych fraz użytkowników w cudzysłowie oraz dodaj „use proactively” / „use immediately after”. ### Błąd 2. Tworzenie podagenta tam, gdzie potrzebny jest Skill Podagent kosztuje więcej niż Skill — tworzy własny kontekst, wczytuje własny prompt systemowy i zużywa więcej tokenów. Jeśli zadanie jest krótkie, nie pochłonie kontekstu głównego czatu i można wykonać je za jednym razem, powinno być skillem, a nie podagentem. Przykład antywzorca: podagent `format-validator`, który sprawdza schemat JSON na podstawie 20 reguł. To powinien być Skill: jeden model, bez potrzeby izolacji i bez wczytywania dodatkowego kontekstu. ### Błąd 3. Uruchamianie „60 agentów równolegle” od samego początku To najbardziej rozpowszechniona iluzja. Widzisz tweet: „Mam 1,500 agentów pracujących równocześnie” i myślisz: „Też powinienem tak zrobić”. W praktyce 60 agentów zużywa limity planu Pro w godzinę, generuje stos sprzecznych wyników, a na koniec dnia nie masz niczego gotowego. Praktyk na Medium ujmuje to tak: Rozwiązanie: zacznij od jednego podagenta do jednego zadania. Gdy już to opanujesz, dodaj drugiego o innej roli. Gdy opanujesz koordynowanie dwóch, przejdź do zespołu 3–5. Przeskok od „zainstalowałem Claude Code wczoraj” do „dziś uruchamiam 20 równolegle” na pewno zepsuje kod i zużyje limity. ### Błąd 4. Przyznawanie każdemu agentowi dostępu do wszystkich narzędzi Jeśli Twój recenzent kodu ma dostęp do Bash, Write i WebFetch, to ogromna luka w bezpieczeństwie i kosztach. Recenzent nie powinien mieć uprawnień do zapisu plików, a tym bardziej dostępu do internetu. Rozwiązanie: ściśle ogranicz `tools`. Recenzent kodu dostaje tylko `Read, Grep, Glob`. Audytor bezpieczeństwa dostaje te same narzędzia odczytu i wyszukiwania oraz różnice od głównej sesji. Dodanie Bash daje możliwość pracy w powłoce; nie ogranicza automatycznie agenta do `git diff`. Agent badawczy dostaje `WebFetch, WebSearch, Read, Write`. Nie przyznawaj podagentowi więcej uprawnień, niż potrzebuje do jednego konkretnego zadania. ### Błąd 5. Podagent zrzuca surowe wyniki do głównego kontekstu Jeśli agent badawczy zwraca „oto wszystkie 30 znalezionych stron, sam coś z tym zrób” głównemu czatowi, tracisz główną zaletę podagentów: izolację od szumu. Rozwiązanie: wyraźnie określ format wyniku w prompcie systemowym podagenta. „Zwróć WYŁĄCZNIE: 3-punktowe TL;DR + listę 5 źródeł. BEZ zrzutów kodu, BEZ surowych wyników wyszukiwania”. Ten format powinien być **ścisły** — podagent nie powinien mieć swobody, by „zmienić go w esej”. ### Błąd 6. Niejasne polecenia: nieprecyzyjne prośby o delegowanie Podagent **nie widzi** historii głównego dialogu. Zaczyna z czystym kontekstem + CLAUDE.md + treścią, którą jawnie mu przekazano. Jeśli napiszesz „napraw uwierzytelnianie”, podagent zacznie zmyślać. Zamiast tego napisz: „Napraw pętlę przekierowań OAuth, która sprawia, że po udanym logowaniu użytkownik zostaje przekierowany do /login zamiast do /dashboard. Plik: src/lib/auth.ts”. Prosta zasada: delegując, przekaż podagentowi tyle kontekstu, ile przekazałbyś nowemu wykonawcy dołączającemu do projektu. ### Błąd 7. Agenci zorientowani na role zamiast zadań Kuszący wzorzec to: „stwórzmy frontend-developera, backend-developera i inżyniera QA i każmy im pracować jako zespół”. To nie działa. Każda „rola” traci kontekst całego projektu, a agenci nie potrafią uzgodnić szczegółów, bo nie widzą pracy pozostałych. Rozwiązanie: podagent powinien wykonywać powtarzające się **zadanie** z jasno określonym wynikiem, a nie pełnić **rolę**. Nie „frontend-developer”, lecz „explore-ui-tree”, „refactor-component”, „audit-accessibility”. Każdy podagent oparty na zadaniu wykonuje konkretną pracę i zwraca konkretny wynik. ## Ile kosztują równoległe podagenci i kiedy się opłacają?
Najważniejsze wnioski Równoległe podagenci zużywają tokeny 3–5 razy szybciej niż praca sekwencyjna. Przy planie Pro (\$20/miesiąc) uruchomienie 5 równoległych podagentów oznacza wykorzystanie limitu w godzinę. Max 5x (\$100/miesiąc) to realistyczne minimum przy regularnej pracy równoległej. Podagent opłaca się w zadaniach wymagających co najmniej 10 minut skupionej pracy — uruchomienie go tylko po to, by poprawić literówkę w README, zużyje więcej tokenów, niż zaoszczędzi czasu.
| Konfiguracja | Dzienne użycie przy aktywnej pracy | |----|----| | 1 sesja Claude Code | ~\$13 | | 3 równoległe podagenci | ~\$30-40 | | 5–10 równolegle | \$50-130 | | 30 agentów (10 programistów × 3 podagenci) | \$300-400 | Limit planu Pro wyczerpie się w ciągu godziny, jeśli uruchomisz 5 równoległych podagentów do złożonych zadań. Max 5x ($100) to realistyczne minimum przy regularnej pracy równoległej. W przypadku zespołów i Enterprise kwestie finansowe są już obsługiwane na poziomie budżetu narzędziowego. Więcej informacji o oszczędzaniu tokenów w Claude Code znajdziesz w [osobnym poradniku o limitach](https://ailoot.ai/blog/pl/claude-code-token-limits-saving/). W przypadku podagentów kluczowa zasada mówi, że podagent opłaca się przy zadaniu wymagającym **co najmniej 10 minut** skupionej pracy. Jeśli zadanie trwa krócej, nie twórz podagenta — wykonaj je na głównym czacie albo użyj Skill. ## Jak zintegrować podagentów z klonem AI i Drugim Mózgiem?
Najważniejsze wnioski Podagenci to czwarty krok w metodyce Claude Code. Logiczna kolejność jest następująca: najpierw [CLAUDE.md](https://ailoot.ai/blog/pl/claude-md-template/) (trwały kontekst), potem [Skills](https://ailoot.ai/blog/pl/claude-code-skills-library/) (gotowe metodyki), następnie [Drugi Mózg](https://ailoot.ai/blog/pl/claude-code-second-brain/) (struktura wiedzy o projekcie), a dopiero potem podagenci (wyspecjalizowani pracownicy). Odwrócenie tej kolejności daje szum zamiast wyników. Podagent bez CLAUDE.md zmyśla; bez Skills za każdym razem powtarza tę samą pracę od początku; bez struktury wiedzy udziela przeciętnej odpowiedzi.
Podagent korzysta z trzech rzeczy, które powinny być w projekcie, zanim utworzysz pierwszego specjalistę: 1. **Właściwy [CLAUDE.md](https://ailoot.ai/blog/pl/claude-md-template/).** Podagent czyta CLAUDE.md przed rozpoczęciem — to jego „umowa o pracę”. Bez tego nie zna kontekstu projektu, ograniczeń ani tonu. Zacznie zmyślać. 2. **Podstawowe [Skills](https://ailoot.ai/blog/pl/claude-code-skills-library/).** Skill to spakowana metodyka. Podagent ładuje tylko te Skills, których potrzebuje, a nie wszystko naraz. Bez Skills za każdym razem powtarza tę samą pracę od początku. 3. **[Drugi Mózg](https://ailoot.ai/blog/pl/claude-code-second-brain/): struktura wiedzy.** Folder `business/` (lub jego odpowiednik w Twojej dziedzinie) to biblioteka, z której korzystają wszyscy podagenci. Bez niego podagent udziela przeciętnej odpowiedzi ChatGPT, nieróżniącej się od odpowiedzi innych osób. Odwrócenie tej kolejności daje szum zamiast wyników. „Mam 60 podagentów działających równolegle” przy pustym folderze `business/` oznacza 60 przeciętnych sesji ChatGPT wykorzystujących to samo podejście. Pełne połączenie — **klon AI + Drugi Mózg + Inżynieria Kontekstu** — to **trzy filary**, które zapewniają Claude spójność. Podagenci są częścią klona AI: sposobem na zapewnienie Claude wyspecjalizowanego zespołu pracującego według Twojej logiki.
### Źródła - [Tworzenie własnych podagentów - Dokumentacja Claude Code](https://code.claude.com/docs/en/sub-agents) - [Jak umożliwić Claude Code bardziej autonomiczną pracę - Anthropic News](https://www.anthropic.com/news/enabling-claude-code-to-work-more-autonomously) - [Jak stworzyliśmy nasz wieloagentowy system badawczy - Anthropic Engineering](https://www.anthropic.com/engineering/multi-agent-research-system) - [Wyposażanie agentów w umiejętności do pracy w rzeczywistym świecie - Anthropic Engineering](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) - [Nowości w Claude Managed Agents (Multi-Agent v2, Outcomes, Dreaming) - blog Anthropic](https://claude.com/blog/new-in-claude-managed-agents)
Najszybszy sposób na rozpoczęcie: skopiuj `code-reviewer` z pierwszego przykładu powyżej do `.claude/agents/code-reviewer.md`, uruchom ponownie Claude Code i wywołaj `@agent-code-reviewer` przy następnym commicie. W ciągu 5 minut dowiesz się, czy potrzebujesz podagentów, czy wystarczy główny czat.
Możesz dalej poznawać Ailoot na stronie [ailoot.ai](https://ailoot.ai/).
## Pytania i odpowiedzi ### Czy recenzent może wykonywać tylko git diff dlatego, że tak mówi prompt? Nie. Przyznanie Bash daje możliwość pracy w powłoce; prompt nie jest listą dozwolonych poleceń. Szablon recenzenta tylko do odczytu pomija Bash, Write i Edit oraz otrzymuje różnice od głównej sesji. ### Jak recenzent sprawdza ostatnie zmiany bez Bash? Główna sesja przekazuje różnice i listę zmienionych plików przy delegowaniu. Recenzent czyta i przeszukuje te pliki przez Read, Grep i Glob oraz zwraca ustalenia bez edycji. ## Ailoot · Firma i jej portfel projektów Ailoot opiera się na zgromadzonym doświadczeniu operacyjnym, szerokiej bazie klientów, stabilnej usłudze i stałej kontroli KPI. Firma i jej portfel projektów: miliony klientów; miesięczna sprzedaż liczona w miliardach. Ailoot wykorzystuje to doświadczenie operacyjne, zapewniając dostęp przez API do funkcji AI w produktach klientów, agentach, aplikacjach i automatyzacjach.