Claude Code subagent: come funzionano e quando usarli

Un subagent è, in sostanza, una funzione a cui delegare un compito: Claude gli affida il lavoro, lui opera in una finestra che non viene mostrata e alla fine consegna una risposta ordinata. Se usato bene, è la leva più efficace per mantenere Claude Code coerente durante una sessione di diverse ore. Se usato male, consuma token e aggiunge latenza senza alcun vantaggio. Questa guida chiarisce entrambi gli aspetti: il funzionamento preciso, il file che definisce un subagent e il criterio concreto per capire quando conviene usarlo.

La versione in 20 secondi

Un subagent esegue un’attività autonoma e ben delimitata nel proprio contesto isolato, quindi restituisce una breve sintesi alla conversazione principale. L’idea è tutta qui. Serve a risolvere un problema specifico: nelle lunghe sessioni agentiche si accumula rumore — risultati di grep, log di build, file consultati una volta e mai più ripresi — finché il modello dedica più attenzione a gestire il disordine che al lavoro vero e proprio.

Spostando quel lavoro rumoroso in un subagent, anche il disordine resta confinato lì. Il thread principale riceve solo la conclusione. Il modello mentale corretto, quindi, non è «un team di ingegneri AI che collabora», ma igiene del contesto con un valore di ritorno. Una volta assimilato questo principio, tutte le altre decisioni sui subagent diventano più semplici.

Claude Code subagent: cosa sono davvero

Un subagent lavora nella propria finestra di contesto, con un system prompt personalizzato, accesso a strumenti specifici e permessi indipendenti. Quando Claude incontra un’attività compatibile con il ruolo dichiarato del subagent, la delega; il subagent procede in autonomia e restituisce il risultato. Questa è la definizione ufficiale, e gli elementi decisivi sono finestra di contesto propria e restituzione del risultato.

Qui si trova il dettaglio che molte spiegazioni sbagliano: un subagent parte da zero. Non vede la cronologia della conversazione, i file che Claude ha già letto o le skill già richiamate. Claude prepara un breve messaggio di delega che riassume il compito; da quel momento il subagent lavora soltanto con il proprio system prompt e con informazioni essenziali sull’ambiente, come la directory di lavoro, non con l’intero system prompt di Claude Code. Quando termina, al thread principale torna solo la sua sintesi.

L’isolamento offre un vantaggio, ma ha anche un costo. Capire questo scambio è il punto centrale:

• Il vantaggio: tutta la parte intermedia e prolissa — i dodici file letti, il grep fallito, il log analizzato — non entra mai nel contesto principale. Arriva la risposta, non il disordine.
• Il costo: il subagent deve recuperare di nuovo informazioni già note. Se il compito ha senso solo alla luce della cronologia della conversazione, un subagent che parte da zero farà fatica.

Il file che definisce un subagent

Un subagent personalizzato è un file Markdown con frontmatter YAML. Il frontmatter contiene la configurazione; il corpo Markdown diventa il system prompt del subagent. I soli campi obbligatori sono name e description.

---
name: code-reviewer
description: Reviews code for quality and best practices. Use immediately after writing or modifying code.
tools: Read, Glob, Grep
model: sonnet
---

You are a senior code reviewer. When invoked, run git diff to see recent
changes, focus on modified files, and review for clarity, naming, error
handling, exposed secrets, input validation, and test coverage. Group your
feedback by priority: critical issues, warnings, then suggestions.

Questo è già un subagent completo e funzionante. La description non è un dettaglio ornamentale: Claude la usa per decidere quando delegare. Una descrizione come «esegue revisioni del codice, da usare subito dopo aver scritto o modificato codice» attiva il subagent nel momento giusto; una formula vaga come «assistente per il codice» rischia invece di lasciarlo inutilizzato. Conviene scrivere la descrizione come se fosse l’annuncio di lavoro per uno specialista.

Non è necessario scrivere il file a mano. Il comando /agents di Claude Code apre un’interfaccia a schede per gestire i subagent: la scheda Running elenca quelli attivi e quelli terminati di recente, che è possibile aprire o interrompere; la scheda Library permette di crearli, modificarli e organizzarli. Un dettaglio importante: i subagent vengono caricati all’avvio della sessione. Se si modifica direttamente un file su disco, è quindi necessario riavviare la sessione perché la modifica venga acquisita. I subagent creati o modificati dall’interfaccia /agents diventano invece operativi subito.

Dove si trovano i subagent e quale definizione ha la precedenza

Lo stesso file si comporta in modo diverso a seconda della posizione. La directory stabilisce chi può utilizzare il subagent e quale definizione prevale in caso di nomi uguali.

Se due subagent hanno lo stesso nome, prevale quello nella posizione con priorità più alta: le definizioni gestite superano quelle di progetto, e quelle di progetto superano quelle dell’utente. I subagent di progetto vengono individuati risalendo dalla directory di lavoro e, dalla versione v2.1.178, in caso di conflitto vince la definizione più vicina alla directory corrente. Esiste anche un’opzione valida solo per la sessione: all’avvio di Claude Code si possono passare i subagent come JSON tramite il flag --agents. Restano disponibili per quella sessione senza essere salvati su disco, una soluzione utile per script di automazione e prove rapide.

La regola pratica è semplice: un subagent che formalizza il modo in cui va revisionato o testato questo repository appartiene a .claude/agents/ e va versionato, così da essere disponibile a tutto il team. Un subagent che riflette il proprio metodo di lavoro personale va invece in ~/.claude/agents/ e resta disponibile in ogni progetto.

Modello e strumenti: le due leve decisive

Due campi del frontmatter determinano gran parte del comportamento reale. Configurarli bene trasforma i subagent da semplice curiosità a strumento davvero conveniente.

Modello. Il campo model accetta un alias (sonnet, opus, haiku, fable), un ID completo come claude-opus-4-8 oppure inherit. Se viene omesso, il valore predefinito è inherit: il subagent usa quindi lo stesso modello della conversazione principale. È una leva di costo facile da trascurare. Un subagent incaricato soltanto di «eseguire grep nel repository e riassumere i risultati» non ha bisogno di un modello di frontiera. Impostando model: haiku, il lavoro ripetitivo passa a un modello più economico e veloce, mentre la sessione principale resta su Opus per le decisioni che richiedono ragionamento.

Strumenti. Per impostazione predefinita, un subagent eredita tutti gli strumenti interni e MCP disponibili nella conversazione principale. L’accesso si restringe con uno di due campi: tools è una lista consentita, quindi rende disponibili soltanto gli strumenti elencati; disallowedTools è una lista vietata, quindi abilita tutto tranne ciò che contiene. Un subagent di ricerca che non deve mai modificare file può ricevere tools: Read, Grep, Glob, Bash, rendendo fisicamente impossibile qualsiasi modifica. Non è soltanto una questione di ordine: è un vero confine di sicurezza. Un revisore in sola lettura non può riscrivere per errore il file che sta esaminando.

C’è un’altra impostazione utile: isolation: worktree esegue il subagent in un worktree git temporaneo, cioè in una copia isolata del repository, che viene ripulita automaticamente se il subagent non apporta modifiche. È la scelta giusta quando si vuole provare qualcosa di rischioso senza interferire con il worktree in uso.

Quando usare un subagent e quando evitarlo

Questa è la parte che manca nei lunghi elenchi di configurazioni su GitHub, ma è anche quella che fa davvero risparmiare tempo e denaro. Un subagent ha un costo, quindi la domanda non è mai «potrei usarne uno?», bensì «l’isolamento ripaga il suo costo?».

I casi in cui un subagent è lo strumento sbagliato derivano direttamente dal modo in cui questa funzione è pensata:

• Confronto iterativo. Se l’attività richiede correzioni frequenti e il proprio giudizio deve restare nel ciclo, è meglio lavorare nella conversazione principale. La delega interrompe quel ciclo.
• Fasi che condividono il contesto. Un flusso di pianificazione, implementazione e test in cui ogni fase dipende dalla precedente appartiene a un solo thread, non a tre subagent isolati che ripartono ogni volta senza contesto.
• Modifiche rapide e circoscritte. Avviare un subagent per correggere un refuso costa più della correzione.
• Lavoro sensibile alla latenza. Un subagent parte da zero e deve dedicare tempo a raccogliere il contesto. Quando serve una risposta subito, procedere nel thread è più rapido.

Subagent, skill, fork o agent team

Claude Code offre ora quattro modi per strutturare il lavoro, facili da confondere tra loro. La differenza riguarda interamente il contesto.

La distinzione che crea più confusione è skill o subagent, perché entrambi possono sembrare «competenze salvate». Una skill consiste in istruzioni riutilizzabili che operano nel contesto della conversazione principale e vedono quindi tutto il lavoro in corso. Un subagent fa l’opposto per progettazione: è isolato e conosce soltanto il compito che gli viene assegnato. Per applicare uno stile condiviso mentre Claude continua a collaborare nella stessa conversazione serve una skill. Per affidare un’indagine rumorosa da svolgere altrove e riceverne il risultato serve un subagent.

Il fork occupa una posizione intermedia utile: eredita tutta la conversazione fino a quel momento — stesso system prompt, stessi strumenti, stesso modello e stessa cronologia dei messaggi — quindi non occorre rispiegare nulla. Le sue chiamate agli strumenti restano comunque fuori dal contesto principale e torna soltanto il risultato finale. È indicato quando un subagent nominato avrebbe bisogno di troppe informazioni pregresse per lavorare bene. La modalità fork è subordinata alla variabile d’ambiente CLAUDE_CODE_FORK_SUBAGENT.

Funzioni avanzate e relativi limiti

Due capacità più recenti rendono i subagent molto più potenti, ma entrambe richiedono di rispettare un limite concreto.

Annidamento. Dalla versione Claude Code v2.1.172, un subagent può avviare altri subagent. Un subagent revisore può assegnare a un verificatore ogni singolo rilievo, mantenendo nascosto tutto l’output intermedio; alla conversazione principale arriva soltanto la sintesi del subagent di primo livello. Il limite è fisso: l’annidamento può raggiungere cinque livelli, non è configurabile e, al quinto livello, il subagent non riceve lo strumento Agent, quindi non può creare altri subagent. Quel tetto ha una ragione. Una ramificazione profonda può trasformarsi in uno sciame e far impennare il consumo di token: la profondità va trattata come un budget, non come un obiettivo.

Memoria. Aggiungendo memory: project — oppure user o local — il subagent ottiene una directory di memoria persistente che può leggere e aggiornare tra una sessione e l’altra. Un code-reviewer con memoria di progetto accumula nel tempo le convenzioni e i problemi ricorrenti del repository, diventando più preciso a ogni utilizzo. project è l’impostazione predefinita consigliata perché può essere condivisa tramite il controllo di versione. Quando la memoria è attiva, Claude Code inserisce nel system prompt all’avvio le prime 200 righe, oppure 25KB, del file MEMORY.md del subagent: quel file va quindi mantenuto essenziale e ben curato.

Un buon primo passo è creare un solo subagent mirato — un code-reviewer in sola lettura è l’esempio classico — inserirlo in .claude/agents/ e farlo intervenire dopo ogni modifica. Una volta dimostrata la sua utilità, si può aggiungere un subagent di ricerca basato su un modello più economico. I team che ottengono risultati non usano trenta agenti: ne usano tre, ciascuno specializzato in un solo compito. Se invece la decisione riguarda quale strumento di coding scegliere, il confronto è un altro: Codex vs Claude Code vs Cursor e la panoramica più ampia sui migliori agenti AI per il coding.

Se si vuole integrare Claude Code nel proprio modo di lavorare e pubblicare software, questo è il cuore di ciò che tratto. Iscriviti alla newsletter per ricevere configurazioni operative, non il clamore del giorno del lancio.