Quando usare i sub-agent di Claude Code
In Claude Code esiste un Agent tool che permette di avviare sub-agent indipendenti all'interno di una conversazione. Ogni sub-agent ha il proprio contesto, svolge il compito assegnato e restituisce il risultato all'agent principale.
Sulla carta sembra potentissimo. Nella pratica, nella maggior parte dei casi non serve. Questo articolo chiarisce quando un sub-agent porta valore reale e quando complica solo le cose.
Non si può richiamare l'Agent tool direttamente da CLAUDE.md o da uno slash command — è uno strumento interno che Claude Code decide autonomamente se utilizzare. Si può però influenzare questa decisione tramite i prompt.
Il flusso di lavoro di un sub-agent:
Caratteristiche chiave:
- Contesto isolato: il sub-agent non vede lo storico della conversazione principale — solo il prompt con cui è stato avviato
- Compressione dei risultati: indipendentemente da quanti file ha letto o comandi ha eseguito, all'agent principale torna solo un riepilogo
- Esecuzione parallela: più sub-agent possono essere avviati ed eseguiti contemporaneamente
Lo scenario più classico. Si chiede a Claude Code di indagare un problema che richiede di esplorare più direzioni contemporaneamente.
Esempio: "Come è implementata l'autenticazione in questo progetto?"
Senza sub-agent, Claude Code procede in sequenza: leggere l'auth controller → il middleware → le route → il model → la config... Un passo alla volta, lento.
Con i sub-agent:
Avviare 3 sub-agent in parallelo:
- Agent 1: esaminare la logica di autenticazione in controller e middleware
- Agent 2: analizzare il design dei model User e Session
- Agent 3: ispezionare file di configurazione e variabili d'ambiente relativi all'auth
Tre direzioni esplorate simultaneamente, risultati aggregati. Nel CLAUDE.md si può guidare il comportamento così:
## Task di investigazione
Per indagini che coprono più moduli, privilegiare l'avvio parallelo
di più sub-agent, aggregando le conclusioni alla fine.
La finestra di contesto di Claude Code è limitata. Se un sotto-task richiede di leggere molti file per produrre una sola conclusione, il sub-agent tiene tutto il "rumore di elaborazione" fuori dal contesto principale.
Esempi tipici:
Il denominatore comune: tanto input, poco output. Il sub-agent digerisce la mole di informazioni e restituisce solo l'essenziale.
Alcune operazioni potrebbero andare storte. Usando un sub-agent con il parametro isolation: "worktree", questo lavora in un git worktree separato. Se qualcosa va male, la directory di lavoro corrente resta intatta.
## Refactoring ad alto rischio
Per refactoring su larga scala, usare sub-agent con isolamento worktree.
Integrare solo dopo aver verificato il risultato.
Scenari adatti:
- Refactoring esplorativo: non si sa se l'approccio funzionerà — il sub-agent fa un tentativo prima
- Confronto tra soluzioni: implementare due approcci in parallelo e confrontare i risultati
- Generazione di codice: produrre grandi quantità di boilerplate, integrare dopo review
"Rinomina questa funzione da camelCase a snake_case" — si fa direttamente. L'overhead di un sub-agent (costruzione del contesto, attesa del risultato, parsing della risposta) è più lento dell'esecuzione diretta.
Regola pratica: se bastano un Grep e un Edit, niente sub-agent.
"Leggere la config → modificare il codice di conseguenza → aggiornare i test in base alle modifiche"
In queste catene ogni passaggio dipende dal precedente. Con i sub-agent bisognerebbe passare i risultati intermedi tra un prompt e l'altro — macchinoso e a rischio di perdere informazioni. Meglio procedere in sequenza.
Un sub-agent restituisce testo riassuntivo, non dati strutturati. Se serve una modifica esatta (ad esempio inserire codice specifico alla riga 47), è più affidabile farla fare direttamente all'agent principale.
I sub-agent sono perfetti per "indagare e trarre conclusioni", non per "eseguire modifiche chirurgiche".
Se la conversazione è appena iniziata e la finestra di contesto è ancora vuota, non ha senso usare un sub-agent per "proteggere il contesto". Conviene aspettare che la conversazione si allunghi e l'agent principale inizi a comprimere lo storico prima di delegare i task pesanti.
Scenario concreto: analizzare tutti i controller di un progetto Rails che usano before_action per capire i pattern di autenticazione e autorizzazione.
Senza sub-agent:
Claude Code legge i file dei controller uno per uno, ognuno occupa contesto principale. Con 20 controller, il solo contenuto dei file può consumare una quantità enorme di token. Quando arriva il momento dell'analisi, i dettagli letti all'inizio potrebbero essere già stati compressi e persi.
Con un sub-agent:
Avviare un sub-agent: "Leggi tutti i controller in app/controllers/,
individua tutti i callback before_action, analizza i pattern di
autenticazione e autorizzazione, e produci un riepilogo classificato."
Il sub-agent legge tutti i file nel proprio contesto e restituisce un riepilogo pulito. Il contesto dell'agent principale è appena sfiorato — riceve la conclusione e può andare avanti.
Non si può obbligare Claude Code a usare o meno i sub-agent, ma si possono esprimere preferenze nel CLAUDE.md:
## Preferenze di utilizzo degli agent
### Task adatti ai sub-agent
- Investigazione multi-modulo (3+ directory)
- Ricerca e statistiche su ampie basi di codice
- Refactoring esplorativo (con isolamento worktree)
### Task da NON suddividere in sub-agent
- Modifiche a singolo file
- Operazioni sequenziali con dipendenze
- Bug fix di cui si conosce già la posizione
Il "processo" di questo task è molto più voluminoso del suo "risultato"?
Se sì — usa un sub-agent per digerire il processo e restituire solo il risultato.
Se no — fallo direttamente, senza strati intermedi.
I sub-agent non migliorano se ne usi di più. Sono uno strumento di gestione del contesto, non un framework di programmazione concorrente. Usati bene, permettono a Claude Code di mantenere lucidità sui progetti grandi. Usati male, fanno solo perdere tempo all'avvio.