Fan out di subagenti in Claude Code, e poi controllare cosa torna

C'è chi scrive «claude fan out subagents» su Google, e parecchi aggiungono «command» alla fine, come se ci fosse un interruttore da azionare. Esiste uno schema, ed esiste anche un comando. Li abbiamo verificati entrambi su Claude Code 2.1.301 e nella documentazione di Anthropic il 16 ottobre 2026.

Poi c'è la parte di cui la documentazione parla poco, e il motivo per cui scriviamo questo articolo: cosa fare dei risultati. Facciamo girare un fan out ogni notte. Sei subagenti traducono ogni nuovo articolo di questo blog in diciassette lingue, e la sessione principale unisce il loro lavoro. Ognuno di loro dichiara di aver seguito le regole. Il controllo che abbiamo scritto prima di avviarli trova comunque qualcosa.

La risposta breve

Fare un fan out significa che una sessione divide un lavoro in fette che non dipendono l'una dall'altra, affida ogni fetta a un subagente, le lascia girare nello stesso momento e unisce quello che torna. In Claude Code puoi farlo in tre modi.

Il resto di questa pagina passa in rassegna ogni modo, e poi i controlli che facciamo sul nostro fan out.

Cosa vede un subagente e cosa non vede

Tre fatti della documentazione decidono come dividi il lavoro.

Ogni subagente parte da zero. Gira nella propria finestra di contesto, con il proprio system prompt, i propri strumenti e i propri permessi. Non vede la tua conversazione, né le skill che hai già usato, né i file che Claude ha già letto. Tutto quello che deve sapere deve stare nel suo brief.

I risultati tornano nella conversazione principale. La parte dettagliata del lavoro di un subagente resta nel suo contesto e torna solo il risultato. Ma molti subagenti che restituiscono resoconti lunghi possono comunque riempire il tuo contesto principale, e ognuno spende i propri token mentre gira.

Ci sono dei limiti. Per impostazione predefinita, 20 subagenti possono girare nello stesso momento in una sessione. Il 21° fallisce con Concurrent subagent limit reached, e l'errore dice a Claude di non riprovare. Puoi alzare o abbassare il limite con CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS. Un subagente può avviare i propri subagenti, fino a tre livelli sotto la conversazione principale, e non c'è un limite al totale in una sessione.

Modo 1: chiederlo a parole

Il fan out più semplice è una frase. L'esempio della documentazione di Anthropic:

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

Ogni subagente esplora la sua area, poi Claude scrive una sintesi. La documentazione aggiunge la condizione che conta: funziona meglio quando i filoni di ricerca non dipendono l'uno dall'altro. Se la domanda sul database ha bisogno della risposta su auth, non hai tre fette, hai una sequenza.

A parole, la decisione resta a Claude. Se hai definito un subagente personalizzato in .claude/agents/, menzionarlo con @ garantisce che giri per quel compito. La nostra pagina sui subagenti di Claude Code spiega come funzionano quei file.

Modo 2: /batch, la cosa più vicina a un comando di fan out

/batch è una skill inclusa in Claude Code. Le dai un'istruzione:

/batch migrate src/ from JavaScript to TypeScript

Esplora il codice, divide il lavoro in 5-30 unità indipendenti e ti mostra un piano. Dopo che l'hai approvato, avvia un subagente in background per ogni unità, ciascuno in un worktree git isolato. Ogni subagente implementa la sua unità, esegue i test e pubblica la sua modifica. Serve un repository git, oppure un hook WorktreeCreate che crei i worktree per un altro sistema di controllo di versione.

Il piano è il momento di rallentare. È lì che si decide la divisione, e la divisione è tutto: due unità che toccano lo stesso file, o un'unità che ha bisogno dell'output di un'altra, non si uniranno in modo pulito per quanto sia bravo ogni subagente. Leggi la lista delle unità come leggeresti un piano di migrazione scritto da un collega.

Modo 3: un ciclo su claude -p

Quando il lavoro è una lista di file e vuoi il controllo su ogni chiamata, le best practice di Anthropic descrivono un ciclo. Prima, fai scrivere la lista a Claude (list all 2,000 Python files that need migrating and save the list to files.txt). Poi:

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

Tre dettagli di quell'esempio vale la pena copiarli.

• La risposta è leggibile da una macchina. «Return OK or FAIL» vuol dire che il tuo script può contare i fallimenti senza leggere della prosa.
• I permessi si decidono prima. --allowedTools approva esattamente quello che serve alla migrazione, e --permission-mode dontAsk nega tutto il resto invece di aspettare qualcuno che non c'è.
• Si comincia con due o tre file. La documentazione lo dice chiaramente: affina il prompt su quello che va storto con i primi file, poi esegui la lista intera.

Così com'è scritto, il ciclo elabora un file dopo l'altro. Lanciare più chiamate nello stesso momento è normale lavoro di shell, ma ogni chiamata è una sessione completa sulla tua macchina e sulla tua quota. Abbiamo misurato cosa succede quando più agenti avviano lo stesso comando pesante nello stesso minuto in questo articolo, e qui la storia è la stessa: comincia con poche chiamate in parallelo.

Per la CI, la documentazione consiglia di aggiungere --bare, che salta gli hook, le skill, i server MCP e CLAUDE.md, così ogni macchina fa lo stesso run. La modalità bare non usa l'accesso del tuo abbonamento: le serve ANTHROPIC_API_KEY.

Come facciamo un fan out ogni notte

Ecco il fan out che facciamo girare davvero. Il nostro team SEO notturno scrive ogni nuovo articolo a mano, in inglese e in francese. Poi un secondo agente lo traduce in altre diciassette lingue con i subagenti di Claude Code, e genera il cinese tradizionale dal cinese semplificato con uno script invece di tradurlo. Undici articoli sono passati da qui dal 13 settembre 2026, e ognuno arriva sotto forma di venti file.

Le fette

Sei subagenti, tre lingue ciascuno (due per l'ultimo): spagnolo, portoghese e italiano; tedesco, olandese e polacco; russo, ucraino e turco; giapponese, coreano e cinese; thailandese, vietnamita e indonesiano; arabo e hindi. Nessuna lingua dipende da un'altra, ed è questo che lo rende un fan out pulito.

Ogni brief porta le stesse cinque cose, perché il subagente non vede nient'altro:

• la fonte inglese, e la versione francese come riferimento per il tono e i termini del prodotto;
• per ogni lingua, frasi già pubblicate sul sito in quella lingua, così il subagente riusa le parole che il sito usa già invece di inventarne di nuove;
• le regole rigide: i nomi di marchi e prodotti restano come sono, il codice resta identico byte per byte, nessuna lineetta;
• lo script di controllo, con l'istruzione di rieseguirlo finché non risponde OK;
• la richiesta di segnalare qualunque cosa dubbia abbia visto, dentro o fuori dalla sua fetta.

Il controllo si scrive prima dell'avvio

Il controllo è uno script, non l'opinione di un subagente. Per ogni lingua confronta il file con la fonte inglese:

• stesso slug e stessa data, titolo uguale all'H1;
• stesso numero di sezioni, sottosezioni, immagini, link e righe di tabella, e tante risposte di FAQ nel corpo quante domande nei metadati;
• link identici byte per byte, segmenti di codice identici byte per byte;
• nomi di marchi contati, mai meno che in inglese;
• una lunghezza entro limiti calibrati per ogni lingua, perché il cinese dice la stessa cosa in circa il 36% dei caratteri che servono all'inglese, e il giapponese in circa la metà;
• accenti presenti dove la lingua li ha (polacco, turco, vietnamita).

Ogni subagente chiude con una qualche versione di «fatto, tutti i controlli passano». L'unico verdetto su cui agiamo è lo stesso script, rieseguito dalla sessione principale, su tutti i file in una volta.

Cosa ha trovato il controllo centrale che i resoconti dei subagenti non dicevano

Codice tradotto dentro una tabella. Il 13 settembre, circa metà dei subagenti ha tradotto le parole che seguivano un comando all'interno degli stessi backtick di una tabella. Ognuno aveva seguito il suo brief per come l'aveva capito. La correzione è andata nel brief, non nei subagenti: un segmento di codice contiene solo il comando, e le parole che lo seguono stanno fuori dai backtick.

Il nostro stesso controllo sbagliava. Il 6 settembre, un controllo di lunghezza calibrato sulla vecchia frase che stavamo sostituendo ha segnalato 11 subagenti su 17. Tutti e 11 avevano ragione: il nuovo testo doveva essere più lungo. Calibrato invece sul francese corretto, non ne ha segnalato nessuno. Anche un controllo centrale può sbagliare, e il modo per accorgersene è eseguirlo prima su una consegna che sai già essere buona.

La coerenza tra le fette. Il 15 ottobre, su una nuova pagina di funzionalità tradotta allo stesso modo, il controllo del merge ha confermato che in 90 file erano cambiate solo le frasi previste. Ma i subagenti di giapponese, coreano e cinese avevano scelto ciascuno per «You may also like» un titolo diverso da quello che la loro lingua usava già in una pagina vicina. Ogni scelta era una traduzione corretta. Nessuna era coerente con il sito. Nessun subagente poteva vederlo dall'interno della sua fetta: lo vede solo un passaggio sul risultato del merge.

Una parola sbagliata supera tutti i controlli di struttura. Una lingua del sito una volta ha chiamato gli agenti AI concessionari di auto, ed è rimasta online per mesi. Stessa lunghezza, stessa punteggiatura, marchio presente: tutti i conteggi erano verdi. L'unica cosa che lo intercetta è una lista con nome di parole sbagliate note, che blocca ogni deploy e cresce di una riga ogni volta che ne troviamo una nuova.

Le segnalazioni fuori dalla fetta. Il 15 ottobre, il subagente che lavorava sul turco ha segnalato che il sito scriveva «ajans», agenzia, per «agent» in 97 frasi esistenti. Non le ha toccate, perché il suo brief glielo vietava. Abbiamo aperto un ticket e la correzione è uscita il giorno dopo. Chiedere ai subagenti cosa hanno visto, e non solo cosa hanno fatto, costa poco e ripaga.

Il merge avviene in un solo punto

I subagenti non scrivono direttamente nel repository. Ognuno restituisce i suoi file, e uno script li unisce, poi confronta il risultato con la versione precedente frase per frase: possono essere cambiate solo le frasi che abbiamo chiesto. Dopo, i controlli del repository e la build del sito girano una sola volta, sul risultato del merge. Eseguire la build una volta per subagente sarebbe più lento e testerebbe stati unificati a metà che non andranno mai online.

Quando non fare un fan out

• Le fette dipendono l'una dall'altra. Se la fetta B ha bisogno dell'output della fetta A, eseguile in ordine.
• Il lavoro è piccolo. Ogni subagente parte da zero e rilegge quello che gli serve. Su un compito di dieci minuti, le ripartenze costano più di quanto fanno risparmiare.
• Non sai scrivere il controllo. Se non c'è modo di distinguere una fetta buona da una cattiva senza rileggere tutto tu, è nel merge che passerai il tuo tempo.
• La quota è stretta. Ogni subagente spende i propri token. Il fan out ti fa guadagnare tempo e un contesto principale pulito, non una bolletta più leggera.

Dove si colloca AgentsRoom

I subagenti vivono dentro una sola sessione di Claude Code. Vedi i loro risultati, non il loro lavoro, e non puoi rimetterne uno in carreggiata a metà strada. Quando vuoi che ogni fetta sia un agente che puoi seguire, a cui puoi rispondere e il cui lavoro puoi rivedere per conto suo, avvia piuttosto sessioni separate: ogni ticket nel proprio worktree git, e Agent Teams quando le fette si passano il lavoro. Un passo di team può portare un comando di controllo, ed è il suo codice di uscita, non quello che dice l'agente, a decidere se il run va avanti. È la stessa regola di prima, applicata dal runner. Funziona con Claude Code, Codex e le altre CLI di agenti supportate da AgentsRoom.

Se stai ancora decidendo tra subagenti e Agent Teams, questo confronto spiega a cosa serve ciascuno.