Pierwszy zespół agentów w Claude Code

Jedna rozmowa do wszystkiego szybko się zapycha: wyniki wyszukiwania, szkice i poprawki mieszają się ze sobą. W Claude Code możesz to rozdzielić między subagentów, czyli pomocników z jedną rolą każdy. Tu składasz mały zespół do ofert i wpisów dla jednoosobowej firmy usługowej: jeden zbiera fakty, drugi pisze, trzeci sprawdza, a decyzje podejmujesz ty.

Czym jest subagent

Subagent to wyspecjalizowany asystent, któremu główna rozmowa przekazuje część zadania. Według oficjalnej dokumentacji każdy subagent:

pracuje we własnym oknie kontekstu, więc jego robocze kroki nie zaśmiecają głównej rozmowy. Wraca do niej tylko wynik.
ma własny prompt systemowy, czyli instrukcje z jego pliku. Nie dostaje promptu systemowego Claude Code, tylko te instrukcje i podstawowe dane o środowisku, na przykład folder roboczy.
ma tylko te narzędzia, które mu dasz, i własne uprawnienia.

Subagenci liczą się do tych samych limitów użycia co główna rozmowa, a każdy zużywa własne tokeny. Zespół ma sens tam, gdzie role naprawdę się różnią.

Gdzie leżą pliki

moj-projekt/.claude/agents/<nazwa>.md   subagent tego projektu
~/.claude/agents/<nazwa>.md             twoi subagenci we wszystkich projektach

Gdy dwa pliki mają tę samą nazwę, wygrywa wersja z projektu. Zmiany w tych folderach Claude Code zauważa po kilku sekundach. Restart jest potrzebny, gdy folder agents powstaje dopiero w trakcie sesji.

Format pliku

Plik Markdown z nagłówkiem YAML, a pod nim instrukcje:

---
name: nazwa-agenta
description: Co robi i kiedy go użyć.
tools: Read, Glob, Write
model: sonnet
---

Kim jesteś, co robisz krok po kroku, czego nie robisz.

name i description są wymagane. Opis mówi Claude, kiedy przekazać zadanie temu subagentowi.
tools to lista narzędzi po przecinku. Bez tego pola subagent dziedziczy wszystkie narzędzia dostępne dla subagentów.
model jest opcjonalny: sonnet, opus, haiku, pełny identyfikator modelu albo inherit.
Treść pod nagłówkiem staje się promptem systemowym.

Dokumentacja opisuje więcej pól, na przykład disallowedTools i permissionMode. Na start wystarczą te cztery.

Jak Claude przekazuje pracę

Automatycznie, na podstawie opisu. Claude porównuje twoją prośbę z polem description. Dokumentacja radzi dopisać do opisu zwrot w rodzaju „use proactively”, jeśli subagent ma się włączać chętniej.
Na twoją prośbę. Napisz „Użyj subagenta recenzent, żeby sprawdził ten szkic” albo wskaż go przez @.

Komenda /agents w aktualnych wersjach przypomina tylko, żeby poprosić Claude o subagenta albo edytować foldery .claude/agents/ i ~/.claude/agents/. W wersjach do 2.1.197 otwierała kreator do tworzenia, edycji i usuwania subagentów. Polecam prostą drogę: poproś Claude o plik i przeczytaj go przed pierwszym użyciem.

Zespół dla jednoosobowej firmy

Przykład: pracownia projektowania wnętrz. Folder projektu:

pracownia/
  CLAUDE.md
  .claude/agents/badacz.md, autor.md, recenzent.md
  materialy/   glos.md, uslugi.md, cennik.md
  notatki/     tu pisze badacz
  szkice/      tu pisze autor
  uwagi/       uwagi recenzenta

Czwarta rola, koordynator, to główna rozmowa prowadzona przez CLAUDE.md.

Badacz

---
name: badacz
description: Zbiera informacje z internetu i zapisuje notatki ze źródłami w folderze notatki/. Użyj, gdy do oferty lub wpisu potrzebne są fakty, przepisy albo dane o rynku.
tools: WebSearch, WebFetch, Read, Write
---

Zbierasz fakty dla pracowni projektowania wnętrz.

1. Wybieraj źródła pierwotne: urzędy, producenci, normy, oficjalne cenniki.
2. Zapisz notatkę w notatki/RRRR-MM-DD-temat.md. Przy każdym fakcie podaj link i datę dostępu.
3. Czego nie potwierdzisz w źródle, wpisz w sekcji "Niepotwierdzone".
4. Nie piszesz ofert ani wpisów. Nie zapisujesz nic poza folderem notatki/.
5. Zwróć listę zapisanych plików i trzy najważniejsze ustalenia.

Autor

---
name: autor
description: Pisze szkice ofert, e-maili i wpisów w głosie właściciela na podstawie notatek z folderu notatki/. Użyj, gdy trzeba przygotować tekst dla klienta lub do publikacji.
tools: Read, Glob, Write
---

Piszesz szkice w imieniu właściciela pracowni.

1. Przeczytaj materialy/glos.md, materialy/uslugi.md i materialy/cennik.md.
2. Fakty bierz tylko z notatek, ceny tylko z cennika. Niczego nie dopowiadaj.
3. Pisz prostą polszczyzną, bez obietnic efektów i bez superlatywów.
4. Zapisz szkic w szkice/RRRR-MM-DD-nazwa.md, a na górze wypisz użyte notatki.
5. Brakujące informacje wpisz jako pytania na końcu szkicu.
6. Niczego nie wysyłasz i nie publikujesz.

Recenzent

---
name: recenzent
description: Sprawdza szkice z folderu szkice/ pod kątem faktów, tonu, poprawności polszczyzny i ryzykownych obietnic. Użyj po każdym nowym lub poprawionym szkicu.
tools: Read, Glob, Grep, WebFetch
---

Jesteś recenzentem. Nie poprawiasz szkicu, tylko piszesz uwagi.

1. Fakty: czy każde twierdzenie ma pokrycie w notatkach. Możesz otworzyć podane tam linki.
2. Ceny: czy zgadzają się z materialy/cennik.md.
3. Ton: czy tekst brzmi jak materialy/glos.md.
4. Język: ortografia, interpunkcja, polskie znaki, odmiana.
5. Ryzyko: obietnice efektów i terminów, porównania z konkurencją, dane osobowe.

Zwróć uwagi w punktach (cytat, problem, propozycja) i werdykt:
"do poprawki" albo "gotowe do decyzji właściciela".

Recenzent nie ma Write ani Edit, więc nie zmieni szkicu. Uwagi zwraca do głównej rozmowy, a ta zapisuje je w uwagi/.

Koordynator w CLAUDE.md

# Pracownia: zespół agentów

## Kolejność pracy
1. badacz zbiera fakty do notatki/
2. autor pisze szkic do szkice/
3. recenzent sprawdza szkic, a ty zapisujesz uwagi w uwagi/
4. Przy werdykcie "do poprawki" autor poprawia szkic raz i recenzent sprawdza ponownie.
5. Pokazujesz mi szkic, uwagi i otwarte pytania. Na tym koniec.

## Zasady
- Niczego nie wysyłasz, nie publikujesz i nie wklejasz do formularzy.
- Nie zmieniasz plików w materialy/.
- Danych klientów nie przekazujesz subagentom, jeśli nie są potrzebne.

Jeden pełny przebieg

Uruchom claude w folderze pracownia i wpisz:

Zapytanie od klienta: projekt łazienki w bloku, termin realizacji wiosną.
Przygotuj ofertę według kolejności z CLAUDE.md. Badacz niech sprawdzi
aktualne wymagania dla instalacji elektrycznej w łazience i podstawę
prawną, którą warto wspomnieć w ofercie. Na koniec pokaż mi szkic,
uwagi recenzenta i listę otwartych pytań.

Claude przekaże zadanie badaczowi, potem autorowi, potem recenzentowi. W rozmowie widać, który subagent właśnie pracuje, a prośby o zgodę, na przykład na zapis pliku, trafiają do ciebie. Na końcu czytasz szkic i uwagi, poprawiasz to, co chcesz, i wysyłasz ofertę własnoręcznie.

Decyzje zostają przy tobie

Nic nie wychodzi bez twojej zgody. Żaden z tych subagentów nie ma narzędzia do wysyłania e-maili ani publikowania. Tak ma zostać.
Najmniej narzędzi, ile trzeba. Zawsze wypełniaj pole tools. Zdanie „zapisuj tylko w notatki/” to prośba, a nie blokada. Blokadą jest brak narzędzia i twoja odmowa przy prośbie o zgodę.
Czytaj, co zatwierdzasz. Prośby subagentów o zgodę wyglądają tak samo jak w głównej rozmowie.
Subagent nie zada ci pytania. Narzędzie do pytań jest dla subagentów wyłączone, więc instrukcja musi mówić, co zrobić, gdy czegoś brakuje.
Git jako siatka bezpieczeństwa. Commit przed każdym przebiegiem pozwala cofnąć zmiany w plikach.

Częste błędy

Ogólny opis. „Pomaga w tekstach” pasuje do wszystkiego. Napisz, co subagent robi i przy jakich prośbach.
Brak pola tools. Subagent dostaje wtedy wszystkie narzędzia dostępne dla subagentów.
Za dużo ról na start. Zacznij od jednego subagenta, na przykład recenzenta, i dodawaj kolejnych, gdy widzisz potrzebę.
Założenie, że subagent zna rozmowę. Nie zna. Ścieżki, zasady i format wyniku zapisz w jego pliku.
Długie raporty. Wyniki wracają do głównej rozmowy i zajmują w niej miejsce. Każ zwracać krótkie podsumowanie, a szczegóły zapisywać w plikach.
Fakty bez źródeł. Bez linków recenzent nie ma czego sprawdzić.

Od czego zacząć

Nie masz jeszcze Claude Code? Zacznij od Claude Code od zera. Potem napisz jednego subagenta, recenzenta, i sprawdź go na prawdziwym szkicu. Powtarzalne zadania bez osobnego kontekstu lepiej zapisać jako skille.