Fan-out van subagents in Claude Code, en dan controleren wat er terugkomt

Mensen typen "claude fan out subagents" in Google, en een flink aantal zet er "command" achter, alsof er een schakelaar is die je om kunt zetten. Er is een patroon, en er is ook een commando. We hebben beide op 16 oktober 2026 gecontroleerd op Claude Code 2.1.301 en in de documentatie van Anthropic.

Dan is er het deel waar de documentatie weinig over zegt, en de reden dat we dit schrijven: wat je met de resultaten doet. Wij draaien elke nacht een fan-out. Zes subagents vertalen elk nieuw artikel van deze blog in zeventien talen, en de hoofdsessie voegt hun werk samen. Elk van hen meldt dat hij de regels heeft gevolgd. De controle die we vóór de start hebben geschreven, vindt toch nog dingen.

Het korte antwoord

Fan-out betekent dat één sessie een taak opsplitst in delen die niet van elkaar afhangen, elk deel aan een subagent geeft, ze tegelijk laat draaien en samenvoegt wat er terugkomt. In Claude Code kan dat op drie manieren.

De rest van deze pagina loopt elke manier langs, en daarna de controles die we op onze eigen fan-out draaien.

Wat een subagent wel en niet kan zien

Drie feiten uit de documentatie bepalen hoe je het werk opsplitst.

Elke subagent begint leeg. Hij draait in zijn eigen contextvenster, met zijn eigen systeemprompt, tools en rechten. Hij ziet je gesprek niet, niet de skills die je al hebt gebruikt en niet de bestanden die Claude al heeft gelezen. Alles wat hij moet weten, moet in zijn briefing staan.

Resultaten komen terug in het hoofdgesprek. Het uitgebreide deel van het werk van een subagent blijft in zijn eigen context, alleen zijn resultaat komt terug. Maar veel subagents die lange rapporten terugsturen, kunnen je hoofdcontext toch vullen, en elk verbruikt zijn eigen tokens terwijl hij draait.

Er zijn limieten. Standaard kunnen er 20 subagents tegelijk draaien in een sessie. De 21e mislukt met Concurrent subagent limit reached, en de fout zegt tegen Claude dat het niet opnieuw moet proberen. Je kunt de limiet verhogen of verlagen met CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS. Subagents kunnen hun eigen subagents starten, tot drie lagen onder het hoofdgesprek, en er is geen limiet op het totaal in een sessie.

Manier 1: vraag erom in gewone woorden

De eenvoudigste fan-out is één zin. Het voorbeeld uit de documentatie van Anthropic:

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

Elke subagent verkent zijn gebied, daarna schrijft Claude één synthese. De documentatie voegt de voorwaarde toe die ertoe doet: dit werkt het best als de onderzoekspaden niet van elkaar afhangen. Als de vraag over de database het antwoord op de vraag over auth nodig heeft, heb je geen drie delen, maar één reeks stappen.

Met gewone woorden laat je de beslissing aan Claude. Als je een eigen subagent hebt gedefinieerd in .claude/agents/, garandeert een @-vermelding dat hij voor die taak draait. Onze pagina over Claude Code subagents legt uit hoe die bestanden werken.

Manier 2: /batch, wat het dichtst bij een fan-out commando komt

/batch is een skill die met Claude Code wordt meegeleverd. Je geeft het een instructie:

/batch migrate src/ from JavaScript to TypeScript

Het onderzoekt de codebase, splitst het werk op in 5 tot 30 onafhankelijke eenheden en laat je een plan zien. Zodra je het goedkeurt, start het per eenheid een subagent op de achtergrond, elk in een geïsoleerde git worktree. Elke subagent voert zijn eenheid uit, draait de tests en publiceert zijn wijziging. Het heeft een git repository nodig, of een WorktreeCreate hook die de worktrees aanmaakt voor een ander versiebeheersysteem.

Bij het plan moet je even vaart minderen. Daar wordt de opsplitsing bepaald, en daar draait alles om: twee eenheden die hetzelfde bestand aanraken, of een eenheid die de uitkomst van een andere nodig heeft, laten zich niet netjes samenvoegen, hoe goed elke subagent ook is. Lees de lijst met eenheden zoals je het migratieplan van een collega zou lezen.

Manier 3: een lus over claude -p

Als de taak een lijst bestanden is en je controle wilt over elke aanroep, beschrijven de best practices van Anthropic een lus. Laat Claude eerst de lijst schrijven (list all 2,000 Python files that need migrating and save the list to files.txt). Dan:

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

Drie details uit dat voorbeeld zijn het overnemen waard.

• Het antwoord is machineleesbaar. "Return OK or FAIL" betekent dat je script mislukkingen kan tellen zonder lopende tekst te lezen.
• De rechten liggen vooraf vast. --allowedTools keurt precies goed wat de migratie nodig heeft, en --permission-mode dontAsk weigert al het andere in plaats van te wachten op iemand die er niet is.
• Je begint met twee of drie bestanden. De documentatie zegt het duidelijk: verbeter de prompt op basis van wat er misgaat bij de eerste bestanden, en draai dan de hele lijst.

Zoals hij er staat, verwerkt de lus het ene bestand na het andere. Meerdere aanroepen tegelijk draaien is gewoon shellwerk, maar elke aanroep is een volledige sessie op je machine en op je quotum. We hebben gemeten wat er gebeurt als meerdere agents in dezelfde minuut hetzelfde zware commando starten in dit artikel, en hier is het hetzelfde verhaal: begin met een klein aantal parallelle aanroepen.

Voor CI raadt de documentatie aan om --bare toe te voegen, dat hooks, skills, MCP-servers en CLAUDE.md overslaat, zodat elke machine dezelfde run krijgt. De bare-modus gebruikt de login van je abonnement niet: hij heeft ANTHROPIC_API_KEY nodig.

Hoe wij elke nacht een fan-out draaien

Dit is de fan-out die we echt draaien. Ons nachtelijke SEO-team schrijft elk nieuw artikel met de hand in het Engels en het Frans. Een tweede agent vertaalt het daarna in zeventien andere talen met Claude Code subagents, en maakt het Traditioneel Chinees met een script uit het Vereenvoudigd Chinees, in plaats van het te vertalen. Elf artikelen zijn hier sinds 13 september 2026 doorheen gegaan, en elk komt binnen als twintig bestanden.

De delen

Zes subagents, elk drie talen (twee voor de laatste): Spaans, Portugees en Italiaans; Duits, Nederlands en Pools; Russisch, Oekraïens en Turks; Japans, Koreaans en Chinees; Thai, Vietnamees en Indonesisch; Arabisch en Hindi. Geen enkele taal hangt af van een andere, en dat maakt dit een schone fan-out.

Elke briefing bevat dezelfde vijf dingen, omdat de subagent niets anders ziet:

• de Engelse bron, en de Franse versie als referentie voor toon en producttermen;
• per taal teksten die al in die taal op de site staan, zodat de subagent de woorden overneemt die de site al gebruikt in plaats van nieuwe te verzinnen;
• de harde regels: merk- en productnamen blijven zoals ze zijn, code blijft byte voor byte gelijk, geen em-streepje;
• het controlescript, met de instructie om het te draaien tot het OK zegt;
• het verzoek om alles te melden wat hij twijfelachtig vond, binnen of buiten zijn deel.

De controle wordt vóór de start geschreven

De controle is een script, geen mening van een subagent. Voor elke taal vergelijkt het het bestand met de Engelse bron:

• dezelfde slug en datum, titel gelijk aan de H1;
• hetzelfde aantal secties, subsecties, afbeeldingen, links en tabelrijen, en evenveel FAQ-antwoorden in de tekst als vragen in de metadata;
• links byte voor byte identiek, codesegmenten byte voor byte identiek;
• merknamen geteld, nooit minder dan in het Engels;
• een lengte binnen grenzen die per taal zijn gekalibreerd, omdat het Chinees hetzelfde zegt in ongeveer 36% van de tekens die het Engels nodig heeft, en het Japans in ongeveer de helft;
• accenten waar de taal ze heeft (Pools, Turks, Vietnamees).

Elke subagent eindigt met een variant van "klaar, alle controles geslaagd". Het enige oordeel waarop we handelen, is hetzelfde script, opnieuw gedraaid door de hoofdsessie, op alle bestanden tegelijk.

Wat de centrale controle vond en de eigen rapporten niet

Vertaalde code in een tabel. Op 13 september vertaalde ongeveer de helft van de subagents de woorden die in een tabel binnen dezelfde backticks op een commando volgden. Elk had zijn briefing gevolgd zoals hij die begreep. De oplossing ging in de briefing, niet in de subagents: een codesegment bevat alleen het commando, en de woorden erna staan buiten de backticks.

Onze eigen controle zat fout. Op 6 september markeerde een lengtecontrole die was gekalibreerd op de oude tekst die we vervingen 11 van de 17 subagents. Alle 11 hadden gelijk: de nieuwe tekst moest langer zijn. Gekalibreerd op het gecorrigeerde Frans markeerde hij er geen enkele meer. Ook een centrale controle kan fout zitten, en je ziet dat door hem eerst te draaien op een levering waarvan je al weet dat die goed is.

Consistentie tussen de delen. Op 15 oktober, bij een nieuwe featurepagina die op dezelfde manier was vertaald, bevestigde de samenvoegcontrole dat in 90 bestanden alleen de verwachte teksten waren veranderd. Maar de subagents voor Japans, Koreaans en Chinees hadden elk een andere titel gekozen voor "You may also like" dan de titel die hun taal al gebruikte op een pagina ernaast. Elke keuze was een correcte vertaling. Geen enkele was consistent met de site. Geen enkele subagent kon dat vanuit zijn eigen deel zien: alleen een controle van het samengevoegde resultaat ziet het.

Een fout woord komt door elke structuurcontrole. Eén taal van de site noemde AI-agents ooit autodealers, en dat stond maandenlang online. Dezelfde lengte, dezelfde leestekens, merk aanwezig: elke telling stond op groen. Het enige wat het opvangt, is een benoemde lijst met bekende foute woorden, die elke deployment blokkeert en er een regel bij krijgt telkens als we een nieuw fout woord vinden.

De meldingen buiten het deel. Op 15 oktober meldde de subagent die aan het Turks werkte dat de site in 97 bestaande teksten "ajans", bureau, schreef voor "agent". Hij heeft ze niet aangeraakt, omdat zijn briefing dat verbood. We hebben een ticket geopend en de correctie ging de volgende dag live. Subagents vragen wat ze hebben gezien, en niet alleen wat ze hebben gedaan, kost weinig en levert veel op.

Het samenvoegen gebeurt op één plek

Subagents schrijven niet rechtstreeks in de repository. Elk levert zijn bestanden in, een script voegt ze samen en vergelijkt het resultaat daarna tekst voor tekst met de vorige versie: alleen de teksten waar we om vroegen mogen veranderd zijn. Daarna draaien de controles van de repository en de build van de site één keer, op het samengevoegde resultaat. De build per subagent draaien zou langzamer zijn en half samengevoegde toestanden testen die nooit live gaan.

Wanneer je geen fan-out moet doen

• De delen hangen van elkaar af. Als deel B de uitkomst van deel A nodig heeft, draai ze dan na elkaar.
• De taak is klein. Elke subagent begint leeg en leest opnieuw wat hij nodig heeft. Bij een taak van tien minuten kosten de frisse starts meer dan ze opleveren.
• Je kunt de controle niet schrijven. Als je een goed deel niet van een slecht deel kunt onderscheiden zonder alles zelf te lezen, gaat je tijd zitten in het samenvoegen.
• Het quotum is krap. Elke subagent verbruikt zijn eigen tokens. Fan-out levert tijd en een schone hoofdcontext op, geen kleinere rekening.

Waar AgentsRoom past

Subagents leven binnen één Claude Code sessie. Je ziet hun resultaten, niet hun werk, en je kunt er geen halverwege bijsturen. Wil je dat elk deel een agent is die je kunt volgen, kunt beantwoorden en apart kunt reviewen, draai dan aparte sessies: elk ticket in zijn eigen git worktree, en Agent Teams wanneer de delen werk aan elkaar doorgeven. Een teamstap kan een controlecommando meekrijgen, en de exitcode daarvan, niet wat de agent zelf beweert, bepaalt of de run verdergaat. Dat is dezelfde regel als hierboven, afgedwongen door de runner. Het werkt met Claude Code, Codex en de andere agent-CLI's die AgentsRoom ondersteunt.

Twijfel je nog tussen subagents en Agent Teams, dan legt deze vergelijking uit waar elk voor dient.