Claude Code subagent: quando usarli

Un subagent di Claude Code è un'istanza separata dell'agente che riceve un compito, lo esegue nella propria finestra di contesto con i soli strumenti che gli hai concesso e ti restituisce il risultato finale invece di tutto il rumore prodotto per arrivarci. Conviene quando il lavoro delegato genera output voluminoso che non ti servirà più, come una ricerca nel codice o la lettura di log, e conviene molto meno quando il compito richiede continui scambi con te. Dalla versione 2.1.172 un subagent può generarne altri a sua volta, con un tetto fisso di cinque livelli di profondità.

Cosa fa esattamente un subagent di Claude Code?

Prende in carico un pezzo di lavoro e lo tiene fuori dalla tua sessione. Ogni subagent parte con un contesto pulito, quindi non vede la cronologia della conversazione, non conosce le skill che hai già invocato e non sa quali file l'agente principale abbia letto: riceve un messaggio di delega che riassume il compito e da lì si arrangia con gli strumenti che il suo file di definizione gli assegna.

Alcuni sono già inclusi e vengono usati da soli quando il caso lo richiede: Explore cerca e legge il codice senza poter scrivere, Plan raccoglie contesto durante la modalità di pianificazione, general-purpose ha tutti gli strumenti e copre i compiti che mescolano esplorazione e modifica. I primi due saltano deliberatamente i file CLAUDE.md e lo stato git della sessione per restare veloci, mentre ogni altro subagent, compresi quelli che scrivi tu, li carica regolarmente.

Dalla versione 2.1.198 Explore eredita il modello della conversazione principale invece di girare sempre su Haiku, quindi in una sessione di fascia alta l'esplorazione costa come quella fascia. Per riportarla a un modello economico definisci un subagent personale chiamato Explore con model: haiku, dato che una definizione tua sostituisce quella integrata e mantiene il proprio campo model.

Quando conviene delegare a un subagent e quando no?

Delega quando il compito è autosufficiente, quando ti serve limitare strumenti e permessi di chi lo esegue, o quando il risultato utile è un riassunto e non il percorso per arrivarci. Dalla versione 2.1.172 un subagent può a sua volta spezzare il lavoro fino a cinque livelli di profondità, quindi un revisore può mandare un verificatore su ciascun risultato senza che l'output intermedio arrivi mai da te. Tieni tutto nella conversazione principale nei casi opposti, cioè quando servono raffinamenti a ripetizione, quando più fasi condividono lo stesso contesto, o quando la modifica è piccola e mirata, perché un subagent parte da zero e paga il tempo di ricostruirsi il quadro.

Prima di scrivere una definizione nuova conviene chiedersi se il problema sia davvero l'isolamento del contesto. Se cerchi un prompt riutilizzabile che gira dentro la conversazione principale allora ti serve una skill e non un subagent, mentre le istruzioni sempre valide sul progetto restano lavoro da CLAUDE.md o AGENTS.md. Per una domanda veloce su qualcosa che è già nella sessione esiste poi /btw, che vede il contesto completo ma non ha strumenti e la cui risposta viene scartata invece di restare in cronologia.

Come si configura un subagent personalizzato?

Con un file markdown in .claude/agents/ se deve valere nel progetto o in ~/.claude/agents/ se deve seguirti su tutte le macchine, più un frontmatter YAML in cui soltanto name e description sono obbligatori. A parità di nome vince la posizione con priorità più alta, nell'ordine impostazioni gestite dall'organizzazione, flag --agents, progetto, utente e plugin.

Gli altri campi sono quelli che decidono il comportamento reale, e la maggior parte delle guide in circolazione si ferma prima di arrivarci. Con tools elenchi gli strumenti concessi e con disallowedTools togli qualcosa dall'elenco ereditato, model accetta gli alias sonnet, opus, haiku, fable, un identificativo completo oppure inherit, che è anche il valore predefinito, mentre permissionMode, maxTurns ed effort regolano rispettivamente la modalità di autorizzazione, il tetto ai turni agentici e il livello di sforzo, da low fino a max.

Restano quattro campi meno noti e piuttosto utili. Il campo skills precarica una o più skill iniettandone il contenuto completo e non la sola descrizione, mcpServers rende disponibile un server già configurato o definito in linea, memory abilita una memoria persistente con ambito user, project o local, e isolation: worktree fa lavorare il subagent in un worktree git temporaneo, ripulito da solo se non ha modificato niente. L'ultimo serve quando più subagent scrivono file in parallelo e non vuoi che si pestino i piedi nello stesso checkout.

Che differenza c'è fra un fork e un subagent denominato?

Un fork eredita l'intera conversazione fino a quel momento, mentre un subagent denominato parte dalla propria definizione. Il fork copre i casi in cui un subagent normale sarebbe inutile, perché gli servirebbe troppo contesto per capire di cosa stai parlando.

	Fork	Subagent denominato
Contesto	Cronologia completa della sessione	Contesto nuovo, solo il prompt di delega
Prompt di sistema e strumenti	Identici alla sessione principale	Dal file di definizione
Modello	Quello della sessione principale	Dal campo model
Cache del prompt	Condivisa con la sessione principale	Separata

La cache condivisa è il motivo per cui un fork costa meno di un subagent nuovo quando il compito ha bisogno dello stesso contesto. Lo avvii con /fork seguito da una direttiva, comando abilitato per impostazione predefinita dalla versione 2.1.161, e i fork in esecuzione compaiono in un pannello sotto il prompt da cui apri la trascrizione con Enter per mandare messaggi di follow-up. Un fork non può generarne un altro, mentre può generare subagent di altro tipo.

Da dove partire con i subagent

Il primo subagent utile è quasi sempre quello che scrivi dopo aver visto la conversazione riempirsi di roba che non ti servirà mai più, tipicamente ricerche nel codice o output di test. Mettine la definizione in .claude/agents/, con tools ridotti al minimo e una description che elenchi le situazioni in cui va usato, perché è su quel campo che la delega automatica decide. Se invece il compito deve diventare un flusso con passaggi fissi la strada passa dalle skill che danno una forma ai task, e su come tengo insieme le due cose ho raccontato la mia esperienza in un anno di workflow con Claude Code.

Domande frequenti

Quando conviene usare un subagent di Claude Code invece della conversazione principale?

Quando il compito è autosufficiente, produce output che non ti servirà più e può restituire un riassunto, oppure quando vuoi limitare strumenti e permessi di chi lo esegue. Nella conversazione principale restano i lavori iterativi e le modifiche piccole, perché un subagent parte da zero e deve ricostruirsi il quadro.

Quali campi si possono mettere nel frontmatter di un subagent?

Sono obbligatori soltanto name e description, mentre gli altri disponibili sono tools, disallowedTools, model, permissionMode, maxTurns, skills, mcpServers, hooks, memory, background, effort, isolation, color e initialPrompt. Ognuno cambia un aspetto preciso del comportamento, dagli strumenti concessi fino all'esecuzione in un worktree git separato.

Un subagent può lanciare altri subagent?

Sì, dalla versione 2.1.172 di Claude Code, con un limite fisso di cinque livelli sotto la conversazione principale. A quella profondità un subagent non riceve più lo strumento Agent e non può delegare altro.

Come si evita che i subagent di Claude Code facciano lievitare i costi?

Il modo più diretto è scegliere il modello per ogni subagent invece di ereditarlo, per esempio definendo un Explore personale con model: haiku ora che quello integrato eredita il modello della sessione. Aiutano anche maxTurns, effort basso per i compiti meccanici e un fork al posto di un subagent nuovo quando il contesto necessario è lo stesso, dato che il fork riusa la cache del prompt.