Subagenci w Claude Code. Pomocnik czyta logi, a do rozmowy wraca samo podsumowanie

Nocny import zamówień znowu padł i programista prosi Claude Code o znalezienie przyczyny. Claude czyta długie logi, wyniki testów i trzy moduły. Przyczynę znajduje, ale okno kontekstu jest już pełne logów, do których nikt nie wróci. Do takiej pracy w Claude Code są subagenci.

Bez nich następne pytanie, o coś zupełnie innego, idzie razem z całym tym bagażem. Subagent czyta logi we własnym kontekście, a do głównej rozmowy wraca tylko to, co znalazł. Dlaczego zapchany kontekst psuje odpowiedzi, pisaliśmy w tekście o długich rozmowach z AI.

Co to jest subagent w Claude Code

Według dokumentacji Anthropic subagent to wyspecjalizowany pomocnik do jednego rodzaju zadań. Działa we własnym oknie kontekstu, z własnymi instrukcjami, własnym zestawem narzędzi i własnymi uprawnieniami. Zaczyna od czystej kartki i nie widzi Waszej rozmowy ani plików, które Claude już przeczytał.

Wczytuje za to Wasze pliki CLAUDE.md. Wyjątkiem są wbudowane Explore i Plan, które startują bez nich, żeby działać szybciej. Kiedy subagent skończy, oddaje do głównej rozmowy podsumowanie.

Claude Code ma kilku wbudowanych subagentów. Explore szybko przeszukuje kod i nie może niczego zmieniać. Plan zbiera informacje w trybie planu. Agent ogólnego przeznaczenia bierze zadania, przy których trzeba i szukać, i działać.

Jedna rzecz łatwo umyka. Subagent wysyła własne zapytania, a one liczą się do tego samego limitu co główna rozmowa. Osobny kontekst nie znaczy, że praca nic nie zużywa.

Jak zrobić własnego subagenta

Subagent to plik Markdown z nagłówkiem YAML. Subagenci projektu leżą w .claude/agents/, a ci, których chcecie mieć we wszystkich projektach, w ~/.claude/agents/. Wymagane są tylko dwa pola, name i description. Można też ograniczyć narzędzia i wybrać lżejszy model.

---
name: czytelnik-logow
description: Czyta logi i wyniki testów. Zwraca tylko błędy z nazwą pliku i numerem linii. Używaj, gdy trzeba przejrzeć długie logi.
tools: Read, Grep, Glob
model: haiku
---

Przeczytaj wskazane logi. Wypisz błędy z plikiem i numerem linii
i dodaj jedno zdanie o prawdopodobnej przyczynie.
Niczego nie zmieniaj w plikach.

Pole tools pozwala temu pomocnikowi tylko czytać i szukać, a model: haiku oddaje czytanie logów lżejszemu i szybszemu modelowi. Treść pod nagłówkiem to jego instrukcja.

Najprościej poprosić Claude, żeby taki plik napisał. Polecenie /agents w nowszych wersjach przypomina właśnie o tym albo o ręcznej edycji folderu. Nowy albo zmieniony plik w istniejącym folderze agents Claude Code wychwyci sam. Jeśli folder powstał dopiero w trakcie sesji, trzeba ją uruchomić od nowa.

Kiedy Claude deleguje sam

O oddaniu zadania subagentowi Claude decyduje sam, na podstawie Waszej prośby, pola description i bieżącego kontekstu. Dlatego opis jest najważniejszą linijką w pliku. Ma mówić, w jakiej sytuacji sięgnąć po pomocnika. „Pomocnik do kodu” nic Claude nie mówi, a „używaj, gdy trzeba przejrzeć długie logi” mówi dokładnie, kiedy.

Anthropic podpowiada, że dopisek w rodzaju „use proactively” zachęca Claude do częstszego delegowania.

Można też poprosić wprost, zwykłym zdaniem, na przykład „użyj subagenta czytelnik-logow do nocnych logów”. Wzmianka przez @ z nazwą agenta gwarantuje, że uruchomi się właśnie on.

Kiedy podział pomaga, a kiedy tylko zjada limit

Subagent ma sens, gdy zadanie daje dużo tekstu, którego nie potrzebujecie w głównej rozmowie. Długie logi, wyniki testów, przegląd folderu z dokumentami.

Pomaga też, gdy części pracy są od siebie niezależne. Kilku subagentów może wtedy działać równolegle, każdy nad swoim modułem albo swoją partią dokumentów, a Claude zbiera ich wnioski.

Przydaje się także wtedy, gdy pomocnik ma mieć mniej narzędzi niż główna rozmowa. Recenzent kodu, który może tylko czytać, niczego przypadkiem nie zmieni.

Dokumentacja równie jasno pisze, kiedy lepiej zostać w głównej rozmowie:

• zadanie wymaga częstej wymiany zdań i poprawek,
• planowanie, wdrożenie i testy dzielą dużo wspólnego kontekstu,
• to szybka, punktowa zmiana,
• liczy się czas, bo subagent startuje od zera i najpierw sam musi zebrać kontekst.

Wielu subagentów naraz to także dużo limitu. Każdy wydaje własne tokeny, a ich długie raporty potrafią zapchać główny kontekst. Przy edycji jest jeszcze jedna pułapka. Zmiany, które subagent zrobi w plikach, zwykle nie wracają przez /rewind, więc przed taką pracą zróbcie commit.

Jeśli taki przegląd dokumentów ma się odbywać co tydzień bez nikogo przy komputerze, to już zadanie dla automatyzacji, a nie dla sesji z AI. Zacznijcie od jednego subagenta do czytania logów albo wyników testów, tylko z narzędziami do odczytu. Gdy główna rozmowa przestanie tonąć w wynikach, dzielcie większe zadania.