Fan-out subagentów w Claude Code, a potem sprawdź, co wraca

Ludzie wpisują w Google „claude fan out subagents”, a sporo z nich dodaje na końcu „command”, jakby był jakiś przełącznik do przestawienia. Jest wzorzec i jest też komenda. Sprawdziliśmy jedno i drugie na Claude Code 2.1.301 oraz w dokumentacji Anthropic 16 października 2026.

Jest też część, o której dokumentacja mówi niewiele, i to z jej powodu piszemy ten tekst: co zrobić z wynikami. Co noc uruchamiamy fan-out. Sześć subagentów tłumaczy każdy nowy wpis tego bloga na siedemnaście języków, a główna sesja scala ich pracę. Każdy z nich melduje, że przestrzegał zasad. Kontrola, którą napisaliśmy przed ich uruchomieniem, i tak coś znajduje.

Krótka odpowiedź

Fan-out oznacza, że jedna sesja dzieli zadanie na części, które od siebie nie zależą, przekazuje każdą część subagentowi, pozwala im działać jednocześnie i scala to, co wraca. W Claude Code możesz to zrobić na trzy sposoby.

Dalsza część strony omawia każdy sposób, a potem kontrole, które robimy na naszym własnym fan-oucie.

Co subagent widzi, a czego nie

Trzy fakty z dokumentacji decydują o tym, jak dzielisz pracę.

Każdy subagent zaczyna od zera. Działa we własnym oknie kontekstu, z własnym system promptem, narzędziami i uprawnieniami. Nie widzi twojej rozmowy, skilli, których już użyłeś, ani plików, które Claude już przeczytał. Wszystko, co musi wiedzieć, musi być w jego briefie.

Wyniki wracają do głównej rozmowy. Szczegółowa część pracy subagenta zostaje w jego własnym kontekście, a wraca tylko wynik. Ale wiele subagentów odsyłających długie raporty i tak może zapełnić twój główny kontekst, a każdy zużywa własne tokeny, gdy działa.

Są limity. Domyślnie w sesji może działać jednocześnie 20 subagentów. 21. kończy się błędem Concurrent subagent limit reached, a błąd mówi Claude, żeby nie próbował ponownie. Możesz podnieść lub obniżyć limit przez CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS. Subagenty mogą uruchamiać własne subagenty, do trzech poziomów pod główną rozmową, a łączna liczba w sesji nie jest ograniczona.

Sposób 1: poproś o to zwykłymi słowami

Najprostszy fan-out to jedno zdanie. Przykład z dokumentacji Anthropic:

Research the authentication, database, and API modules in parallel using separate subagents

Każdy subagent bada swój obszar, a potem Claude pisze jedną syntezę. Dokumentacja dodaje warunek, który ma znaczenie: działa to najlepiej, gdy ścieżki badania nie zależą od siebie. Jeśli pytanie o bazę danych potrzebuje odpowiedzi na pytanie o auth, nie masz trzech części, tylko jedną sekwencję.

Zwykłe słowa zostawiają decyzję Claude. Jeśli zdefiniowałeś własnego subagenta w .claude/agents/, wzmianka @ gwarantuje, że uruchomi się do tego zadania. Nasza strona o Claude Code subagents wyjaśnia, jak działają te pliki.

Sposób 2: /batch, najbliższy odpowiednik komendy fan-out

/batch to skill dostarczany razem z Claude Code. Dajesz mu polecenie:

/batch migrate src/ from JavaScript to TypeScript

Bada kod, dzieli pracę na 5 do 30 niezależnych jednostek i pokazuje ci plan. Gdy go zatwierdzisz, uruchamia jednego subagenta w tle na każdą jednostkę, każdego w odizolowanym git worktree. Każdy subagent implementuje swoją jednostkę, uruchamia testy i publikuje swoją zmianę. Potrzebne jest repozytorium git albo hook WorktreeCreate, który tworzy worktree dla innego systemu kontroli wersji.

Przy planie warto zwolnić. To tam zapada decyzja o podziale, a od podziału zależy wszystko: dwie jednostki, które dotykają tego samego pliku, albo jednostka, która potrzebuje wyniku innej, nie scalą się czysto, niezależnie od tego, jak dobry jest każdy subagent. Czytaj listę jednostek tak, jak czytałbyś plan migracji od kolegi.

Sposób 3: pętla po claude -p

Gdy zadanie to lista plików i chcesz kontrolować każde wywołanie, dobre praktyki Anthropic opisują pętlę. Najpierw każ Claude napisać listę (list all 2,000 Python files that need migrating and save the list to files.txt). Potem:

for file in $(cat files.txt); do
  claude -p "Migrate $file from Python 2 to Python 3. Return OK or FAIL." \
    --allowedTools "Edit,Bash(git commit *)" \
    --permission-mode dontAsk
done

Trzy szczegóły z tego przykładu warto skopiować.

• Odpowiedź jest czytelna dla maszyny. „Return OK or FAIL” oznacza, że twój skrypt może policzyć niepowodzenia bez czytania prozy.
• Uprawnienia są ustalone z góry. --allowedTools zatwierdza dokładnie to, czego potrzebuje migracja, a --permission-mode dontAsk odrzuca całą resztę, zamiast czekać na kogoś, kogo nie ma.
• Zaczynasz od dwóch lub trzech plików. Dokumentacja mówi to wprost: popraw prompt na podstawie tego, co poszło źle przy pierwszych plikach, a potem uruchom całą listę.

W tej postaci pętla przetwarza jeden plik po drugim. Uruchomienie kilku wywołań naraz to zwykła praca w shellu, ale każde wywołanie to pełna sesja na twojej maszynie i z twojego limitu. Zmierzyliśmy, co się dzieje, gdy kilku agentów uruchamia tę samą ciężką komendę w tej samej minucie, w tym wpisie, i tutaj jest tak samo: zacznij od niewielkiej liczby równoległych wywołań.

Dla CI dokumentacja zaleca dodanie --bare, które pomija hooki, skille, serwery MCP i CLAUDE.md, żeby każda maszyna dostała ten sam przebieg. Tryb bare nie korzysta z logowania z twojej subskrypcji: potrzebuje ANTHROPIC_API_KEY.

Jak co noc robimy fan-out

Oto fan-out, który naprawdę uruchamiamy. Nasz nocny zespół SEO pisze każdy nowy wpis ręcznie po angielsku i po francusku. Drugi agent tłumaczy go potem na siedemnaście kolejnych języków za pomocą subagentów Claude Code, a chiński tradycyjny generuje skryptem z chińskiego uproszczonego, zamiast go tłumaczyć. Od 13 września 2026 przeszło przez to jedenaście wpisów, a każdy trafia do repozytorium jako dwadzieścia plików.

Części

Sześć subagentów, po trzy języki (dwa dla ostatniego): hiszpański, portugalski i włoski; niemiecki, niderlandzki i polski; rosyjski, ukraiński i turecki; japoński, koreański i chiński; tajski, wietnamski i indonezyjski; arabski i hindi. Żaden język nie zależy od innego i właśnie to czyni z tego czysty fan-out.

Każdy brief zawiera tych samych pięć rzeczy, bo subagent nie widzi nic innego:

• źródło angielskie i wersję francuską jako wzór tonu i terminów produktowych;
• dla każdego języka teksty już opublikowane na stronie w tym języku, żeby subagent używał słów, których strona już używa, zamiast wymyślać nowe;
• twarde zasady: nazwy marek i produktów zostają bez zmian, kod zostaje identyczny co do bajtu, żadnej pauzy;
• skrypt kontrolny z poleceniem, żeby uruchamiać go, aż odpowie OK;
• prośbę o zgłoszenie wszystkiego, co wydało mu się wątpliwe, w jego części lub poza nią.

Kontrolę pisze się przed uruchomieniem

Kontrola to skrypt, a nie opinia subagenta. Dla każdego języka porównuje plik ze źródłem angielskim:

• ten sam slug i ta sama data, tytuł równy H1;
• ta sama liczba sekcji, podsekcji, obrazów, linków i wierszy tabeli, a w treści tyle odpowiedzi FAQ, ile pytań w metadanych;
• linki identyczne co do bajtu, fragmenty kodu identyczne co do bajtu;
• nazwy marek policzone, nigdy mniej niż po angielsku;
• długość w granicach skalibrowanych dla każdego języka, bo chiński mówi to samo w około 36% znaków, których potrzebuje angielski, a japoński w około połowie;
• znaki diakrytyczne tam, gdzie język je ma (polski, turecki, wietnamski).

Każdy subagent kończy jakąś wersją „gotowe, wszystkie kontrole przechodzą”. Jedyny werdykt, na podstawie którego działamy, to ten sam skrypt, uruchomiony ponownie przez główną sesję, na wszystkich plikach naraz.

Co znalazła centralna kontrola, a czego nie zgłosiły raporty subagentów

Kod przetłumaczony w tabeli. 13 września mniej więcej połowa subagentów przetłumaczyła słowa, które w tabeli następowały po komendzie wewnątrz tych samych backticków. Każdy postąpił zgodnie ze swoim briefem tak, jak go zrozumiał. Poprawka trafiła do briefu, nie do subagentów: fragment kodu zawiera tylko komendę, a słowa po niej stoją poza backtickami.

Nasza własna kontrola się myliła. 6 września kontrola długości skalibrowana na starym tekście, który zastępowaliśmy, oznaczyła 11 subagentów z 17. Wszystkie 11 miały rację: nowy tekst miał być dłuższy. Po skalibrowaniu na poprawionym francuskim nie oznaczyła żadnego. Centralna kontrola też może się mylić, a sposób, żeby to zobaczyć, to uruchomić ją najpierw na dostawie, o której już wiesz, że jest dobra.

Spójność między częściami. 15 października, przy nowej stronie funkcji przetłumaczonej w ten sam sposób, kontrola scalania potwierdziła, że w 90 plikach zmieniły się tylko oczekiwane teksty. Ale subagenty japoński, koreański i chiński wybrały dla „You may also like” każdy inny tytuł niż ten, którego ich język już używał na sąsiedniej stronie. Każdy wybór był poprawnym tłumaczeniem. Żaden nie był spójny ze stroną. Żaden subagent nie mógł tego zobaczyć ze swojej części: widzi to tylko przejście po scalonym wyniku.

Złe słowo przechodzi każdą kontrolę struktury. Jeden z języków strony nazwał kiedyś agentów AI salonami samochodowymi i zostało to online przez miesiące. Ta sama długość, ta sama interpunkcja, marka obecna: każde liczenie było zielone. Jedyne, co to wyłapuje, to nazwana lista znanych złych słów, która blokuje każde wdrożenie i rośnie o jedną linię za każdym razem, gdy znajdziemy nowe.

Zgłoszenia spoza części. 15 października subagent pracujący nad tureckim zgłosił, że strona w 97 istniejących tekstach pisała „ajans”, czyli agencja, zamiast „agent”. Nie ruszał ich, bo brief mu tego zabraniał. Otworzyliśmy ticket, a poprawka wyszła następnego dnia. Pytanie subagentów o to, co widziały, a nie tylko o to, co zrobiły, kosztuje mało i się opłaca.

Scalanie odbywa się w jednym miejscu

Subagenty nie piszą bezpośrednio do repozytorium. Każdy oddaje swoje pliki, skrypt je scala, a potem porównuje wynik z poprzednią wersją tekst po tekście: zmienić mogły się tylko teksty, o które prosiliśmy. Następnie kontrole repozytorium i build strony uruchamiają się raz, na scalonym wyniku. Uruchamianie buildu raz na subagenta byłoby wolniejsze i testowałoby stany w połowie scalone, które nigdy nie trafią na produkcję.

Kiedy nie robić fan-outu

• Części zależą od siebie. Jeśli część B potrzebuje wyniku części A, uruchom je po kolei.
• Zadanie jest małe. Każdy subagent zaczyna od zera i ponownie czyta to, czego potrzebuje. Przy zadaniu na dziesięć minut świeże starty kosztują więcej, niż oszczędzają.
• Nie umiesz napisać kontroli. Jeśli nie da się odróżnić dobrej części od złej bez samodzielnego przeczytania wszystkiego, czas stracisz na scalaniu.
• Limit jest napięty. Każdy subagent zużywa własne tokeny. Fan-out daje czas i czysty główny kontekst, a nie mniejszy rachunek.

Gdzie pasuje AgentsRoom

Subagenty żyją wewnątrz jednej sesji Claude Code. Widzisz ich wyniki, nie ich pracę, i nie możesz pokierować żadnym z nich w trakcie. Gdy chcesz, żeby każda część była agentem, którego możesz obserwować, któremu możesz odpowiedzieć i którego pracę przejrzysz osobno, uruchom zamiast tego osobne sesje: każdy ticket w osobnym git worktree, a Agent Teams, gdy części przekazują sobie pracę. Krok zespołu może mieć komendę kontrolną i to jej kod wyjścia, a nie zapewnienie agenta, decyduje, czy run idzie dalej. To ta sama zasada co wyżej, egzekwowana przez runner. Działa to z Claude Code, Codex i innymi CLI agentów obsługiwanymi przez AgentsRoom.

Jeśli nadal wybierasz między subagentami a Agent Teams, to porównanie wyjaśnia, do czego służy każde z nich.