Subagent di Claude Code: cosa sono, come crearli, consumi

I subagent di Claude Code sono assistenti specializzati a cui Claude affida un compito a parte: lavorano in una finestra di contesto separata, con un loro prompt di sistema, strumenti limitati e permessi propri, e restituiscono alla conversazione principale solo un riassunto. Si creano con un file Markdown nella cartella .claude/agents/ e servono a tenere pulito il contesto. Attenzione però: ogni subagent fa le sue richieste e consuma gli stessi limiti del tuo piano.

In questa guida, aggiornata alla versione 2.1.318 del 4 novembre 2026, ti spiego cosa sono, come creo un subagent da zero, come si richiamano e soprattutto quanto pesano su Pro, Max e Ultra. In italiano non c'è quasi nulla di completo sul tema: la documentazione ufficiale è in inglese e cambia ogni settimana.

Cosa sono i subagent di Claude Code

Un subagent di Claude Code è una sessione di lavoro secondaria che Claude apre quando un'attività rischia di riempire la conversazione principale di file letti, log o risultati di ricerca che non ti serviranno più. Il subagent fa il lavoro sporco nel suo contesto e ti riporta solo la sintesi.

Ogni subagent di Claude Code ha quattro elementi:

• Un prompt di sistema suo: riceve solo quello e alcuni dettagli di base, come la cartella di lavoro. Non riceve il prompt di sistema completo di Claude Code.
• Una lista di strumenti: puoi dargli solo lettura, oppure anche scrittura e comandi.
• Un modello: può essere lo stesso della conversazione principale o uno più economico, come Haiku.
• Permessi indipendenti: una modalità di permesso diversa da quella della sessione.

Il punto che sorprende di più chi inizia: un subagent non vede la tua conversazione. Parte con il suo prompt, il messaggio di delega che Claude scrive per lui, i file CLAUDE.md e uno snapshot di git status. Se hai passato venti minuti a spiegare un bug a Claude e poi deleghi "sistemalo", il subagent non sa nulla di quei venti minuti.

I subagent integrati: Explore, Plan e general-purpose

Tra i subagent di Claude Code ce ne sono alcuni già pronti, che Claude usa da solo quando servono:

• Explore: agente veloce in sola lettura (Write ed Edit negati), pensato per cercare e capire il codice. Claude gli assegna un livello di profondità: quick, medium o very thorough. Parte senza CLAUDE.md e senza git status per essere rapido ed economico.
• Plan: lavora in plan mode, raccoglie il contesto prima di presentarti un piano. Anche lui in sola lettura.
• General-purpose: ha tutti gli strumenti disponibili ai subagent e si usa per compiti che richiedono sia esplorazione sia modifiche.
• Agenti di servizio: statusline-setup (gira su Sonnet quando usi /statusline) e claude-code-guide (gira su Haiku quando fai domande su Claude Code).

Un dettaglio utile per risparmiare: se crei un tuo subagent chiamato Explore, sostituisce quello integrato e mantiene il suo campo model. Con model: haiku fai girare tutte le esplorazioni su un modello più economico.

Come creare un subagent di Claude Code

Un subagent è un file Markdown con un'intestazione YAML (il frontmatter) seguita dal prompt di sistema. Puoi chiedere a Claude di scriverlo o crearlo a mano. Il mio consiglio: fai scrivere la prima versione a Claude e poi rileggila riga per riga.

Passo 1: decidi dove salvarlo

• .claude/agents/ nella cartella del progetto: vale solo per quel progetto. È il posto giusto per subagent legati a un codice preciso, da mettere sotto versione così li usa tutto il team.
• ~/.claude/agents/ nella tua home: vale in tutti i tuoi progetti.
• Flag --agents all'avvio: definizione in JSON valida solo per quella sessione, comoda per test e script.
• Plugin: i subagent arrivano installati con il plugin.

Se due subagent hanno lo stesso nome vince quello con priorità più alta: impostazioni gestite dall'organizzazione, poi flag --agents, poi progetto, poi utente, infine plugin.

Passo 2: scrivi il file

Questo è un esempio di revisore in sola lettura, salvato come .claude/agents/code-reviewer.md:

---
name: code-reviewer
description: Rivede il codice modificato e segnala bug, problemi di sicurezza e manutenibilità. Usalo dopo ogni modifica.
tools: Read, Grep, Glob
model: sonnet
---

Sei un revisore di codice. Quando vieni chiamato, analizza le modifiche
e dai indicazioni concrete su qualità, sicurezza e buone pratiche.
Indica file e riga per ogni problema. Non modificare i file.

Solo name e description sono obbligatori. Attenzione ai refusi: i nomi dei campi sono in camelCase e Claude Code ignora in silenzio un campo che non riconosce. Un file senza description, con YAML non valido o con il primo --- non in prima riga viene saltato senza avvisi in sessione: il motivo finisce nel log di debug (claude --debug).

Passo 3: provalo

Chiedi a Claude di usarlo: "Usa il subagent code-reviewer per rivedere le ultime modifiche". Nella trascrizione vedrai una riga con il nome del subagent e una breve descrizione del compito. Claude Code rileva i file nuovi o modificati in pochi secondi, senza riavvio. L'unica eccezione: se la cartella agents non esisteva quando hai aperto la sessione, devi riavviare.

Una nota per chi segue vecchi tutorial: il comando /agents oggi non apre più la procedura guidata. Stampa solo un promemoria che ti dice di chiedere a Claude o di modificare le cartelle a mano. La procedura con le schede Running e Library esisteva fino alla versione 2.1.197.

I campi del frontmatter che contano davvero

• description: è la regola con cui Claude decide quando delegare. È la riga più importante del file. Se scrivi "use proactively" o "usalo sempre dopo...", Claude delega più spesso.
• tools e disallowedTools: lista di strumenti permessi o vietati. Un prompt che dice "non modificare i file" è una richiesta; togliere Edit e Write dagli strumenti è un muro.
• model: sonnet, opus, haiku, fable, un ID completo come claude-opus-5-5 oppure inherit.
• effort: livello di ragionamento del subagent (low, medium, high, xhigh, max, secondo il modello).
• maxTurns: numero massimo di turni. Al limite il risultato torna marcato come parziale e Claude può riprenderlo.
• skills: skill da precaricare nel contesto del subagent, con il contenuto completo.
• isolation: worktree: il subagent lavora in un git worktree temporaneo, una copia isolata del repository.
• memory: memoria persistente con ambito user, project o local.

Come richiamare un subagent di Claude Code

Ci sono quattro modi, dal più morbido al più rigido:

1. Delega automatica: Claude sceglie da solo in base alla tua richiesta e alla description dei subagent.
2. Per nome: "usa il subagent test-runner per sistemare i test". Claude di solito delega, ma decide lui.
3. Con la menzione @: scrivi @ e scegli il subagent dall'elenco, oppure @agent-nome. Così quel subagent parte di sicuro per quel compito.
4. Per tutta la sessione: claude --agent code-reviewer fa diventare l'intera sessione quel subagent, con i suoi strumenti e il suo modello. Puoi renderlo predefinito per un progetto con la chiave agent in .claude/settings.json.

Le descrizioni occupano contesto: quando quelle dei tuoi subagent superano insieme 15.000 token, Claude Code mostra un avviso all'avvio. Tienile brevi e sposta i dettagli nel prompt di sistema, che si carica solo quando il subagent gira.

Quanto consumano i subagent di Claude Code sui limiti

Questa è la parte che i tutorial saltano. La documentazione è chiara: ogni subagent invia le sue richieste e queste contano sugli stessi limiti di utilizzo della conversazione principale. Cinque subagent in parallelo sono cinque contesti che si riempiono, e i risultati che tornano occupano spazio anche nella conversazione principale.

Se usi Claude Code con un abbonamento, il consumo si vede sulla finestra di 5 ore e sul tetto settimanale. Per capire come funzionano i piani ti rimando alla mia guida su prezzi e limiti di Claude Pro, Max e Ultra. Le leve per contenere la spesa sono tre.

1. Scegli il modello giusto per ogni subagent

Un subagent che lancia i test e riporta solo quelli falliti non ha bisogno di Opus. Claude Code sceglie il modello di un subagent in questo ordine:

1. il parametro model che Claude passa per quella chiamata;
2. il campo model nel frontmatter (inherit vuol dire il modello principale);
3. la variabile d'ambiente CLAUDE_CODE_SUBAGENT_MODEL;
4. il modello della conversazione principale.

Se vuoi imporre un solo modello a tutti i subagent, imposta anche CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1. Per verificare, lancia /tasks mentre un subagent lavora: la sua riga mostra il modello usato. Per i lavori di routine, Claude Haiku 5.5 è la scelta che conviene valutare per prima.

2. Abbassa l'effort dei subagent

Dalla versione 2.1.316 del 31 ottobre 2026 esiste la variabile CLAUDE_CODE_SUBAGENT_EFFORT: imposta il livello di effort dei subagent quando nient'altro lo indica, invece di ereditare quello della sessione. Puoi anche fissarlo nel campo effort del singolo subagent. Per un subagent di ricerca nel codice, un effort basso spesso basta.

3. Limita quanti ne partono

• Massimo 20 subagent in esecuzione contemporaneamente per sessione: oltre, la chiamata fallisce con Concurrent subagent limit reached. Si cambia con CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS.
• Massimo tre livelli di annidamento: un subagent può lanciare altri subagent fino a tre livelli sotto la conversazione principale. Con CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1 togli l'annidamento.
• Nessun limite totale al numero di subagent in una sessione: il freno vero sono i tuoi limiti di piano.

Se vuoi un controllo più ampio sul consumo di token, trovi i comandi /usage, /context e /compact nella guida su come ottimizzare Claude Code e ridurre i token.

Le novità di inizio novembre 2026

Le ultime tre versioni hanno toccato proprio i subagent di Claude Code:

• 2.1.316 (31 ottobre): arriva CLAUDE_CODE_SUBAGENT_EFFORT.
• 2.1.317 (3 novembre): i subagent che girano su un modello diverso da quello principale usano l'effort salvato per quel modello, o il suo predefinito, invece dell'effort della sessione.
• 2.1.318 (4 novembre): i subagent in background spostano in background un comando di shell dopo 3 minuti, così la cache del prompt non scade mentre il comando gira. Corretto anche l'avviso "Now using usage credits" che ricompariva circa ogni 30 secondi con un subagent in background attivo.

Il consiglio pratico: aggiorna con claude update e controlla la versione con claude --version. Se non hai ancora installato lo strumento, parti dalla guida su come installare Claude Code su Windows, Mac e Linux.

Subagent in parallelo, in background e fork

Di default, un subagent di Claude Code avviato dalla conversazione principale parte in background: tu continui a lavorare e il risultato arriva come notifica. Se il subagent chiede un permesso, la richiesta compare nella sessione principale con il nome del subagent: approvi, oppure premi Esc per negare solo quella chiamata.

Tre schemi che funzionano bene:

• Isolare operazioni con output enorme: "usa un subagent per lanciare i test e riportami solo quelli falliti con l'errore".
• Ricerca in parallelo: "analizza in parallelo i moduli autenticazione, database e API con subagent separati". Funziona bene quando le ricerche non dipendono l'una dall'altra.
• Subagent in catena: un revisore trova i problemi di prestazioni, poi un secondo subagent li corregge.

Attenzione alla scrittura in parallelo: due subagent che modificano gli stessi file si pestano i piedi. In quel caso usa isolation: worktree.

C'è poi il fork: un subagent che eredita tutta la conversazione invece di partire da zero. Lo avvii con /subtask seguito dal compito. Siccome condivide prompt di sistema, strumenti e modello con la sessione principale, riusa la sua cache del prompt e costa meno di un subagent nuovo quando il compito richiede lo stesso contesto. La modalità fork è attiva di default dalla 2.1.302. Se vuoi che Claude possa aspettare un subagent prima di proseguire, devi spegnerla con CLAUDE_CODE_FORK_SUBAGENT=0 nel blocco env delle impostazioni.

Subagent o skill? Le differenze con skill, hook e MCP

Si confondono spesso perché tutti estendono Claude Code, ma rispondono a domande diverse:

• Subagent di Claude Code: cambia dove Claude fa il lavoro. Contesto separato, torna solo un riassunto. Ideale per compiti rumorosi e ricerche parallele.
• Skill: cambia come Claude fa una cosa. Istruzioni riutilizzabili che girano nella conversazione corrente. Ne parlo nella guida su come creare una skill di Claude da zero.
• Hook: garantisce che qualcosa succeda sempre, a un evento preciso, fuori dal modello.
• Server MCP: cambia cosa Claude può raggiungere, come database, ticket e API. Approfondisco nella guida a MCP e ai server MCP.

Si combinano: un subagent può precaricare skill con il campo skills, avere i suoi hook nel frontmatter e i suoi server MCP con mcpServers. La mia regola: se il problema è "questo output è troppo grande per il mio contesto", serve un subagent. Se è "rispiego sempre la stessa procedura", serve una skill. Se cerchi skill già pronte, guarda le migliori skill di Claude Code.

Quando non usare un subagent di Claude Code

I subagent di Claude Code non sono sempre la scelta migliore. Resta nella conversazione principale quando:

• il compito richiede molti scambi e correzioni continue;
• più fasi condividono tanto contesto, come pianificazione, sviluppo e test;
• devi fare una modifica veloce e mirata;
• conta la velocità: un subagent che non è un fork parte da zero e ha bisogno di tempo per raccogliere il contesto.

Per una domanda su qualcosa che è già nella conversazione c'è /btw: non ha accesso agli strumenti e la risposta non entra nella cronologia.

Sicurezza: strumenti, permessi e plugin

Quando imposto Claude Code su un progetto, questa è la parte su cui insisto di più. Alcune regole che valgono sempre:

• Dai solo gli strumenti necessari: un subagent di ricerca con tools: Read, Grep, Glob non può scrivere né lanciare comandi.
• Blocca comandi specifici nelle impostazioni: una voce come Bash(git push *) in disallowedTools toglie al subagent tutto Bash. Per bloccare solo quel comando, mettila in permissions.deny.
• I subagent dei plugin hanno meno poteri: per sicurezza ignorano i campi hooks, mcpServers e permissionMode.
• Il report del subagent viene scansionato: Claude Code segnala testi che imitano i suoi messaggi o citano impostazioni come bypassPermissions. La scansione non giudica se un testo è malevolo e non sostituisce la limitazione degli strumenti.
• Puoi spegnere i subagent: aggiungi un tipo a permissions.deny, oppure nega lo strumento Agent per impedire qualsiasi delega.

Se vuoi un livello in più di isolamento, puoi far girare Claude Code in una microVM: ne parlo nella guida a Docker Sandbox per Claude Code e Codex.

Leggi anche

• Claude Code Projects: come funziona, quanto consuma, limiti
• Claude Code mods: cosa sono, come si installano e i rischi
• Codex vs Claude Code: quale conviene? Prezzi e limiti 2026
• Claude Cowork vs Claude Code: quale usare
• Pi coding agent: cos'è, come si installa e novità della 1.5

Conclusione: parti da un solo subagent

Il modo migliore per iniziare con i subagent di Claude Code è crearne uno solo, per il compito più rumoroso che hai: di solito i test o la ricerca nel codice. Dagli strumenti in sola lettura, un modello economico e una description chiara. Poi guarda con /usage quanto pesa sui tuoi limiti prima di moltiplicarli.

Se vuoi portare agenti come questi nel lavoro della tua azienda, con permessi e costi sotto controllo, trovi cosa faccio nella pagina sull'automazione AI per aziende. Per un progetto concreto puoi scrivermi dalla pagina contatti.