Claude Code Subagenci: konfiguracja, ustawienia i przypadki użycia

Większość sesji w Claude Code spowalnia i staje się nieczytelna z tego samego powodu: każde eksploracyjne użycie grep, każdy zrzut logów oraz każde „sprawdzę jeszcze jeden plik” pozostaje w głównej konwersacji na stałe.

Subagenty zostały stworzone, aby rozwiązać dokładnie ten problem. Są jedną z podstawowych jednostek agentowych wbudowanych w Claude Code, służących do obsługi głośnej, równoległej pracy — sposobu na przeniesienie chaosu do izolowanego okna i przywrócenie tylko istotnego podsumowania.

Subagent nie jest mądrzejszym Claudem i nie jest tożsamy ze Skilliem (Umiejętnością). Jest to oddzielny agent rozumujący z własnym oknem kontekstowym, własną listą dozwolonych narzędzi i bez pamięci bieżącej konwersacji, chyba że zostanie on wyraźnie rozgałęziony. Zrozumienie tej różnicy jest kluczowe dla rozróżnienia między konfiguracją subagenta, która cicho oszczędza budżet kontekstowy, a taką, która jedynie dodaje opóźnienia bez żadnej korzyści.

Subagenty vs. Umiejętności (Skills) vs. MCP

Claude Code oferuje trzy punkty rozszerzeń, które rozwiązują różne problemy i są często mylone, ponieważ wszystkie trzy mogą technicznie „pomóc w zadaniu”.

Przydatna zasada: hook wymusza twardo deterministyczne ograniczenie, Umiejętność daje głównemu agentowi możliwość inline, a subagent służy do pracy, którą chcesz zdelegować i całkowicie wykluczyć z głównego kontekstu. Jeśli zadaniem Umiejętności jest koordynacja narzędzia, które jeszcze nie istnieje, jest to zazwyczaj sygnał, że potrzebujesz serwera MCP, a nie subagenta. Claude Code nie jest tu wyjątkiem — ekosystem OpenCode ma podobny koncept w postaci specjalizowanych agentów, które dzielą planowanie, badania i weryfikację między dedykowane role w podobny sposób.

czym jest subagent właściwie

Trzy właściwości definiują subagenta w Claude Code i wszystkie trzy mają znaczenie dla tego, jak go używasz:

• Izolowany kontekst. Subagent startuje z czystym oknem. Nie widzi historii Twojej konwersacji, chyba że wyraźnie go rozgałęzisz, co sprawia, że jego wynik nie jest zanieczyszczony tym, o czym rozmawialiście trzy rundy temu.
• Ograniczona lista dozwolonych narzędzi. Subagenty mogą używać tylko podzbioru tego, co już ma sesja rodzica — nie mogą przyznawać sobie nowych możliwości, a dobrze zaprojektowany subagent powinien otrzymać tylko narzędzia niezbędne do jego pracy (np. narzędzia tylko do odczytu dla agenta badawczego).
• Brak widoczności między subagentami. Subagenty nie widzą pracy w toku innych subagentów. Jeśli zadanie B naprawdę wymaga wyniku zadania A, jest to zależność sekwencyjna, a nie coś, co można zrównoleglić na dwóch subagentach.

Wyzwalaczem użycia subagenta nie jest „to zadanie jest trudne”. To „to zadanie jest głośne” — typ pracy, która generuje dużo wyników pośrednich (dziesiątki odczytów plików, długi log, eksploracyjny grep po całym repozytorium), gdzie żaden z tych materiałów pośrednich nie musi przetrwać do kolejnej rundy konwersacji.

Kiedy używać subagenta (a kiedy nie)

Dobre zastosowania: eksploracja kodu przed dużą zmianą, automatyczne uruchamianie testów, gdzie interesuje Cię tylko wynik pass/fail i podsumowanie błędów, weryfikacje bezpieczeństwa lub stylu oraz każde wieloetapowe zadanie badawcze, którego surowy wynik w przeciwnym razie zalewałby główną sesję.

Słabe zastosowania: szybkie odpytania („co zwraca ta funkcja”), wszystko wymagające ścisłej iteracji w obie strony oraz zadania zależne, które skłaniasz się do „zrównoleglenia”, mimo że drugie zadanie potrzebuje wyniku pierwszego. Używanie subagenta do trywialnego odpytania jedynie dodaje narzut uruchamiania świeżego okna kontekstowego bez realnej korzyści z izolacji.

Pomiar zysku: matematyka kontekstu i kosztów

Argument za subagentami jest abstrakcyjny, dopóki nie wprowadzisz liczb do rzeczywistego zadania. Weźmy typowe: grep w serwisie o ~500 plikach, aby znaleźć każde miejsce, gdzie nadal jest odczytywany przestarzały klucz konfiguracji, a następnie zgłosić dokładne dopasowania plik:wiersz.

To około 15-20-krotne redukcja tego, co Twoja główna sesja musi „nosić” dla tego kroku, co jest właściwym mechanizmem za „subagenty utrzymują sesje szybsze” — to nie magia, to kontekst, który nigdy nie zostaje w ogóle załadowany.

Strona kosztowa narasta w ten sam sposób. Korzystając z cen z rozliczenia cenowego Claude Code, uruchomienie tej samej rundy eksploracyjnej na Opus (5 USD/MTok wejście, 25 USD/MTok wyjście) kosztuje około 0,20-0,25 USD tylko za ~40K tokenów wejściowych. Przekierowanie go do Haiku (1 USD/MTok wejście, 5 USD/MTok wyjście) obniża ten koszt do 0,04-0,05 USD — a budżet Opus sesji głównej w ogóle nie jest dotknięty przez tokeny eksploracyjne, ponieważ widzi on jedynie ~2K-tokenowe podsumowanie.

Definiowanie niestandardowego subagenta

Niestandardowe subagenty istnieją jako pliki Markdown z YAML frontmatter,要么是 zakresu projektu w .claude/agents/ (zacommitowane do repozytorium, współdzielone przez cały zespół),要么是 zakresu użytkownika w ~/.claude/agents/ (osobiste narzędzia, które przenosisz do każdego projektu).

---
name: code-reviewer
description: >
  Reviews staged changes for bugs, security issues, and style violations
  before commit. Use when the user asks to review, audit, or check
  changes prior to committing or opening a PR.  
tools: Read, Grep, Glob
model: sonnet
skills:
  - security-checklist
---
You are a careful code reviewer. Read the staged diff, flag concrete
issues with file:line references, and end with a short pass/fail summary.
Do not modify any files.

Pole description jest najważniejszą linijką w pliku. To ona jest czytana przez logikę routowania sesji rodzica, aby zdecydować, czy ten subagent pasuje do bieżącego zadania. Napisz ją jak ogłoszenie o pracę — nazwij warunek wyzwalający wprost, a nie jako mgliste „pomaga z kodem”. Mgiełowe opisy są pomijane lub błędnie stosowane przez automatyczne dystrybucje.

Pole tools jest Twoją granicą izolacji. Daj subagentowi badawczemu Read, Grep i Glob i nic więcej; nadanie mu wszystkich dostępnych narzędzi pokonuje cały cel uruchamiania go w ograniczonej piaskownicy. Opcjonalne pole skills wstępnie ładuje pełną zawartość nazwanych Umiejętności do kontektu startowego subagenta — przydatne, gdy subagent potrzebuje wiedzy dziedzinowej bez wydawania rundy na jej odnajdywanie i ładowanie w trakcie zadania.

Routowanie modeli: tanie modele do brudnej roboty

Subagenty to również miejsce, gdzie kontrola kosztów staje się realna. Przekieruj odkrywanie plików, skanowanie logów i inną taną do weryfikacji pracę do Haiku, a zarezerwuj Sonnet lub Opus do etapów wymagających dużego wysiłku umysłowego — decyzji architektonicznych, niejednoznacznych debugowań, wszystkiego, gdzie błąd jest kosztowny. Haiku jest około 15 razy tańszy per token niż Opus, a w przypadku głośnej eksploracji, do której subagenty są budowane, ta różnica szybko narasta w rzeczywistej sesji pracy.

Wzorzec Explore, Plan, Execute

Dla złożonej, wieloetapowej pracy wzorzec, który sprawdza się w praktyce, to Explore, Plan, Execute — używaj tanich subagentów do części generujących hałas, a bramę weryfikacji człowieka trzymaj w jednym miejscu, gdzie tak naprawdę ma znaczenie.

Kluczowym szczegółem, który ludzie często odwracają, jest miejsce bramy weryfikacji. Eksploracja jest tania, więc pozwól subagentowi czytać swobodnie, nie pytając najpierw o pozwolenie. Planowanie jest analityczne, więc pozwól agentowi zaprojektować podejście samodzielnie. Ale zanim dowolny agent zmodyfikuje pliki, chcesz zobaczyć plan i go zatwierdzić — do tego służy tryb planowania w Claude Code (permissionMode: plan), a jest to ta sama zasada omawiana w szerszych najlepszych praktykach vibe coding, polegających na sprawdzaniu każdego diffu przed jego zastosowaniem.

Częste błędy

Pewne błędy pojawiają się powtarzalnie, gdy zespoły zaczynają pisać niestandardowe subagenty:

• Mgiełowe opisy. „Pomaga z kodem” nigdy nie zostanie poprawnie zaroutowany. Nazwij dokładny warunek wyzwalający.
• Zbyt szeroki dostęp do narzędzi. Nadanie subagentowi badawczemu tylko do odczytu dostępu do zapisu i bash usuwa gwarancję izolacji, która sprawiła, że jego tworzenie miało sens w pierwszej chwili.
• Równoleglenie zadań zależnych. Jeśli zadanie B potrzebuje gotowego wyniku zadania A, uruchamiaj je sekwencyjnie — subagenty nie mogą koordynować się w trakcie zadania tak, jak może to zrobić wspólny orchestrator. Dla przepływów pracy, które naprawdę potrzebują agentów rozmawiających ze sobą w trakcie zadania, to inny kształt problemu; zobacz wzorce orchestracji wieloagentowej, jeśli budujesz system produkcyjny, a nie przepływ pracy dla pojedynczego repozytorium.
• Używanie subagenta do trywialnej pracy. „Sformatuj ten JSON” lub „uruchom tę jedną komendę” nie potrzebuje świeżego okna kontekstowego; zrób to bezpośrednio.

Przykład zrealizowany: subagent code-review od początku do końca

Mówiąc, że chcesz, aby każde niebagatelne commit było sprawdzane przed zastosowaniem. Umieść definicję code-reviewer pokazaną wcześniej w .claude/agents/code-reviewer.md, comituj ją, aby cały zespół współdzielał tego samego recenzenta, i wywołaj ją naturalnym żądaniem, takim jak „sprawdź moje przygotowane zmiany przed commit”. Claude Code dopasowuje Twoje żądanie do description subagenta, uruchamia go z dostępem tylko do Read, Grep i Glob, a on wraca ze znaleziskami odwołującymi się do plik:wiersz i podsumowaniem pass/fail — żaden z plik-po-pliku hałasu z dojścia do celu nie dotyka Twojej głównej sesji.

Jak to wygląda w głównym transkrypcji, z adnotacjami:

You:  review my staged changes before I commit

Main: [dispatches code-reviewer subagent — 6 files read, 1 grep pass,
       zero of it shown here]

Main: code-reviewer findings:
      - auth/session.go:142 — token refresh path doesn't handle expired
        refresh token; falls through to nil dereference
      - auth/session.go:203 — style: error wrapped without %w
      PASS/FAIL: FAIL (1 blocking issue)

Siedem odczytów plików i jeden przebieg grep miały miejsce, a Twoja główna sesja zapłaciła dokładnie za cztery linijki tego. Ta luka — wszystko, co zrobił subagent, versus trójliniowe podsumowanie, które tak naprawdę widzisz — to cały wniosek wartości w jednym transkrypcji.

Jeśli Twój zespół używa również szkieletów Spec-Driven Development, subagent weryfikacyjny naturalnie wpisuje się w krok walidacji; zobacz GitHub Spec Kit vs Kiro vs Claude Code SDD Workflows, aby zobaczyć, jak ta brama weryfikacyjna porównuje się w przenośnych i zintegrowanych z IDE ustawieniach SDD.

Czy warto konfigurować niestandardowe subagenty?

Nie od razu. Wbudowany ogólny subagent już pokrywa większość eksploracji i delegacji badawczej bez pisania pojedynczego pliku YAML, a pojedynczy przebieg Explore-Plan-Execute wystarcza do większości codziennej pracy. Napisz niestandardowy plik .claude/agents/*.md dopiero wtedy, gdy zdelegujesz to samo zadanie ręcznie trzy razy — recenzent kodu, triager testów, agent wyszukiwania dokumentacji dla jednej konkretnej wewnętrznej biblioteki. Zespoły, które piszą pięć subagentów w swoim pierwszym tygodniu, zwykle kończą z pięcioma przestarzały polami description, których nikt nie aktualizuje, gdy rzeczywisty warunek wyzwalający się zmienia, co cicho psuje automatyczne routowanie miesiące później. Zacznij od zera niestandardowych subagentów, dodawaj po jednym i tylko wtedy, gdy powtarzalność — a nie teoretyczna użyteczność — tego wymaga.

Znane ograniczenia

Kilka niedociągnięć warto znać przed budowaniem wokół subagentów:

• Brak delegacji rekurencyjnej. Subagent nie może generować własnych subagentów. Jeśli zadanie naprawdę potrzebuje drugiej warstwy delegacji, jest to sygnał, że potrzebujesz innego kształtu orchestracji — zobacz wzorce orchestracji wieloagentowej, aby zobaczyć, jak to wygląda poza pojedynczą sesją Claude Code.
• Brak pamięci między wywołaniami. Każde wysłanie startuje od zera, nawet jeśli wywołałeś tego samego subagenta pięć minut temu w podobnym zadaniu. Nie ma wbudowanego mechanizmu, aby subagent pamiętał swoje ostatnie uruchomienie.
• Izolacja to lista dozwolonych narzędzi, a nie piaskownica. Subagent z dostępem Bash nadal może dotknąć systemu plików i sieci jak każde inne wywołanie narzędzia. Ograniczanie tools redukuje promień wybuchu; nie tworzy twardej granicy bezpieczeństwa.

Rozwiązywanie problemów

Subagent nigdy się nie uruchamia. Problem prawie zawsze leży w opisie. Przypisz go do konkretnego warunku wyzwalającego zamiast ogólnego stwierdzenia o możliwościach i sprawdź dwukrotnie, czy plik znajduje się w .claude/agents/ (projekt) lub ~/.claude/agents/ (osobisty) z odpowiednim rozszerzeniem.

Subagent spala za dużo kontekstu mimo wszystko. Sprawdź listę dozwolonych narzędzi tools — zbyt szeroki zestaw narzędzi zachęca do zbyt szerokiej eksploracji. Sprawdź również, czy zadanie powinno zostać podzielone na dwa subagenty zamiast jednego robiącego wszystko.

Założona umiejętność nie ładuje się wewnątrz subagenta. Claude Code pomija brakującą lub wyłączoną umiejętność nazwaną w polu skills zamiast kończyć uruchomienie z błędem i rejestruje odpowiednią linię w wyjściu debug (/debug z głównej sesji, a następnie odtwórz wysłanie) — coś w stylu skill "security-checklist" not found, skipping. Uruchom /doctor później, aby potwierdzić, że reszta Twojego ustawienia jest zdrowa.

Wyniki wydają się niespójne między uruchomieniami. To często problem routowania modelu, a nie projektowania subagenta — praca wymagająca dużego wysiłku umysłowego przypisana do taniego modelu będzie się bardziej różnić. Przenieś ją do Sonnet lub Opus i zostaw Haiku do deterministycznych, mało niejednoznacznych kroków.

Subagenty są jedną częścią znacznie większego zestawu narzędzi; jeśli porównujesz Claude Code z resztą ekosystemu narzędzi deweloperskich AI przed zobowiązaniem się do tego przepływu pracy, to przegląd jest dobrym kolejnym krokiem.

Przydatne linki

• Instalacja i konfiguracja Claude Code dla Ollama, llama.cpp, ceny
• Umiejętności Claude i SKILL.md dla Deweloperów
• GitHub Spec Kit vs Kiro vs Claude Code SDD Workflows
• Czym jest Vibe Coding?
• Wzorce Orchestracji Wieloagentowej: Praktyczny Przewodnik
• Oh My Opencode Specialised Agents Deep Dive
• Narzędzia Deweloperskie AI: Kompletny Przewodnik