Claude Code agents: jak stworzyć i uruchomić subagenta

• Zacznij od jednej roli, na przykład recenzenta konkretnego pliku.
• Podaj oczekiwane działanie programu oraz format odpowiedzi.
• Po analizie sprawdź wskazany błąd na przykładzie, który umiesz policzyć samodzielnie.

Funkcja to fragment programu, który można wywołać, aby przetworzył podane dane i zwrócił wynik, na przykład cenę po rabacie. Takie znaczenie opisuje słownik Pythona.

Polecam delegować zadania z wyraźnym końcem: „przejrzyj funkcję obliczającą rabat” jest łatwiejsze do oceny niż „popraw cały projekt”. Anthropic wskazuje analizę wielu plików i dodatkową weryfikację kodu jako przykłady zastosowań; przy drobnych pytaniach delegowanie dokłada niepotrzebny etap. Zobacz zalecenia dotyczące wyboru zadania dla subagenta.

Poniższa tabela pokazuje mój proponowany podział pracy na początku nauki.

W naszym ćwiczeniu podział ról wygląda tak:

flowchart TD
    A[Twoje wymagania] --> B[Główna rozmowa]
    B --> C[Subagent recenzent]
    C --> D[Odczyt pliku]
    D --> C
    C --> B
    B --> E[Twoja ocena poprawki]

Technicznie osobny kontekst i zwrot wyniku do rozmowy nadrzędnej zapewnia narzędzie Agent.

Ćwiczenie przewidziano dla Ubuntu 24.04 LTS i powłoki Bash, czyli programu interpretującego polecenia wpisywane w terminalu. Dokumentacja Claude Code wymienia Ubuntu 20.04 lub nowsze oraz połączenie z internetem wśród wymagań systemowych.

Przygotuj:

• zainstalowany Claude Code i dostęp do konta obsługującego to narzędzie;
• terminal, czyli okno do wpisywania poleceń;
• edytor zwykłego tekstu do zapisania dwóch plików.

Jeśli narzędzie nie jest jeszcze gotowe, przejdź przez oficjalną instrukcję instalacji Claude Code. Plik przykładowy będzie napisany w Pythonie, ale podczas ćwiczenia tylko go czytamy, więc nie trzeba uruchamiać Pythona.

1. Przygotuj osobny folder

W terminalu sprawdź instalację:

claude --version

Oczekiwany wynik to numer zainstalowanej wersji. Działanie tej opcji potwierdza dokumentacja poleceń Claude Code.

Polecam zapisać pełny wynik tego polecenia razem z nazwą i wersją systemu, aby móc odtworzyć ćwiczenie. Nie podano wyniku claude --version z testu wydawcy, więc poradnik nie wskazuje wersji, na której zweryfikowano ćwiczenie.

Następnie utwórz folder ćwiczenia. Wykonuj polecenia po kolei; jeśli pierwsze zgłosi, że folder już istnieje, wybierz inną nazwę i nie przechodź do istniejącego katalogu.

mkdir claude-agents-demo
cd claude-agents-demo
mkdir -p .claude/agents

mkdir tworzy katalog, a cd przechodzi do niego. Ostatnie polecenie tworzy również brakujący katalog nadrzędny .claude. Te polecenia nie usuwają danych; dalsze kroki wykonuj z folderu claude-agents-demo.

2. Zapisz program do oceny

W edytorze utwórz plik rabat.py:

def cena_po_rabacie(cena, procent):
    return cena * procent / 100

print(cena_po_rabacie(100, 20))

Założenie ćwiczenia: funkcja ma zwracać cenę po odjęciu rabatu. Dla ceny 100 zł i rabatu 20% powinno zostać 80 zł. Celowo zapisany wzór oblicza 20 zł, czyli kwotę samego rabatu.

Nie poprawiaj go jeszcze. Ten prosty przypadek pozwoli sprawdzić, czy recenzent odnosi odpowiedź do wymagań.

3. Zapisz definicję recenzenta

Definicja subagenta to plik Markdown, czyli tekst z prostym formatowaniem. Na początku umieszcza się frontmatter: blok konfiguracji w formacie YAML, zapisany między liniami ---. YAML to czytelny dla człowieka format zapisu danych, używany między innymi do konfiguracji programów. Dalej znajdują się instrukcje dla subagenta, zgodnie z formatem opisanym w dokumentacji.

Utwórz plik .claude/agents/recenzent-kodu.md:

---
name: recenzent-kodu
description: Sprawdza wskazany plik pod kątem zgodności z wymaganiami i wyjaśnia błędy początkującemu.
tools: Read
---

Jesteś recenzentem kodu dla osoby początkującej.

Czytaj wyłącznie plik wskazany w zadaniu.
Porównaj działanie kodu z podanymi wymaganiami.
Nie zmieniaj plików i nie uruchamiaj programu.

Odpowiedz po polsku. Dla każdego znalezionego problemu podaj:
1. Nazwę pliku i problematyczny fragment.
2. Wyjaśnienie błędu prostymi słowami.
3. Przykład danych ujawniających problem.
4. Proponowaną poprawkę w bloku kodu.

Oddziel analizę kodu od wyników wykonania.
Jeśli programu nie uruchomiono, napisz to wprost.

name identyfikuje subagenta, a description opisuje, kiedy go używać. Pole tools określa dostępne narzędzia. Ich znaczenie potwierdza opis pól konfiguracji.

Wybraliśmy samo Read, czyli odczyt zawartości pliku. Anthropic pokazuje konfigurację agenta ograniczonego do Read, który nie może edytować plików ani wykonywać poleceń przez Bash.

4. Uruchom Claude Code i zleć analizę

Z folderu projektu wpisz:

claude

Przy pierwszym użyciu przejdź przez logowanie wyświetlone przez program. Uruchomienie sesji w katalogu projektu i logowanie opisuje oficjalna instrukcja pierwszego uruchomienia.

W rozmowie Claude Code wpisz poniższy tekst. Zapis @agent-recenzent-kodu jawnie wskazuje subagenta, zgodnie z dokumentacją wywoływania agentów.

@agent-recenzent-kodu Przejrzyj wyłącznie plik rabat.py.
Wymaganie: cena_po_rabacie ma zwracać cenę po odjęciu rabatu.
Dla ceny 100 i rabatu 20 wynik powinien wynosić 80.
Wyjaśnij błąd i pokaż proponowaną poprawkę.
Nie zmieniaj plików ani nie uruchamiaj programu.

To wiadomość do Claude, nie polecenie powłoki. Po wysłaniu poczekaj na wynik analizy.

5. Oceń odpowiedź i popraw plik

Oczekuj wyjaśnienia, że funkcja zwraca kwotę rabatu zamiast pozostałej ceny. Sprawdź, czy propozycja odpowiada poniższemu wzorowi, a nie tylko zmienia nazwy zmiennych.

Zastąp zawartość pliku rabat.py:

def cena_po_rabacie(cena, procent):
    return cena * (1 - procent / 100)

print(cena_po_rabacie(100, 20))

Zapis zastępuje poprzednią treść tego pliku. Dla naszych danych obliczenie to 100 * (1 - 0.2), czyli 80. Następnie ponów prośbę o analizę i dodaj przypadki rabatu 0% oraz 100%, z oczekiwanymi wynikami odpowiednio 100 i 0.

Polecam traktować taką odpowiedź jako propozycję do sprawdzenia. W tym ćwiczeniu recenzent analizuje tekst programu; nie wykonuje testu, czyli automatycznego sprawdzenia działania kodu.

Recenzent nie jest dostępny

Sprawdź ścieżkę .claude/agents/recenzent-kodu.md oraz pola name i description. Pierwszą linią pliku musi być ---; błędny YAML może spowodować pominięcie definicji. Jeżeli katalog agents powstał dopiero po rozpoczęciu sesji, uruchom ją ponownie. Te przypadki opisuje dokumentacja ładowania definicji subagentów.

Odpowiedź jest zbyt ogólna

Polecam zawęzić zadanie: zamiast „sprawdź jakość kodu” napisz „sprawdź, czy funkcja odejmuje rabat”. Poproś o fragment kodu i przykład liczbowy. Jeśli sugestia dotyczy zaokrąglania cen, ustal najpierw własne wymaganie dotyczące zaokrągleń.

Czy trzeba tworzyć własnych agentów?

Nie. Claude Code ma również wbudowanych pomocników, między innymi Explore do przeszukiwania kodu i Plan do badań przed przygotowaniem planu. Własna definicja przydaje się przy powtarzanej roli, takiej jak nasz recenzent. Wbudowane typy opisuje przewodnik Anthropic.

Dlaczego /agents nie otwiera kreatora?

Aktualna dokumentacja podaje, że kreator działał w wersji 2.1.197 i wcześniejszych. Obecnie /agents wyświetla przypomnienie o tworzeniu plików lub zleceniu ich przygotowania Claude. Dlatego ten poradnik korzysta z ręcznej definicji subagenta.

Czym subagent różni się od skills?

Skill to zapisana umiejętność, na przykład instrukcja przeglądu dokumentacji w pliku SKILL.md. Subagent jest wykonawcą wydzielonego zadania. Mechanizmy można łączyć, co pokazuje dokumentacja współpracy skills i subagentów.

Czy subagenci zużywają limit Claude Code?

Tak. Ich własne zapytania również zużywają dostępny limit, nawet jeśli do głównej rozmowy wraca tylko podsumowanie. Potwierdza to dokumentacja zarządzania zużyciem. Polecam zaczynać od jednego pliku i konkretnego pytania.

Przygotuj recenzentowi własną listę pytań, na przykład o zgodność z wymaganiami i obsługę błędnych danych. Następnie przeczytaj oficjalny poradnik tworzenia skills w plikach SKILL.md, żeby zapisać powtarzalną procedurę.