Subagenti in Claude Code: cosa fanno e quando usarli

Risposta breve: un subagente è un contesto separato a cui Claude Code delega del lavoro, con un proprio prompt di sistema, propri permessi sugli strumenti e, volendo, un proprio modello. La documentazione di Anthropic elenca cinque motivi per usarli: preservare il contesto tenendo esplorazione e implementazione fuori dalla conversazione principale, imporre vincoli limitando quali strumenti un subagente può usare, riutilizzare configurazioni tra progetti, specializzare il comportamento con prompt di sistema mirati e controllare i costi indirizzando attività verso modelli più veloci ed economici. Il primo e l’ultimo sono quelli che cambiano di più la giornata.

Il problema di contesto che risolvono

Ogni messaggio in una sessione di Claude Code si porta dietro l’intera conversazione. Se leggi quaranta file cercando qualcosa, quei quaranta file restano nel contesto per tutto il resto della sessione, in competizione con il lavoro che ti interessa davvero.

Da qui due sintomi visibili. Le sessioni lunghe diventano più lente e più costose, perché il fattore di costo è la finestra di contesto e non il numero di messaggi. E la qualità cala, perché il segnale che ti serve resta sepolto sotto output di esplorazione rilevanti solo per cinque minuti.

Un subagente risolve la cosa in modo strutturale. Il lavoro delegato avviene nel suo contesto e torna indietro solo il risultato. Dodici file letti durante una ricerca ti costano un riassunto nella conversazione principale invece di dodici file di rumore.

È per questo che esistono gli agenti di esplorazione integrati, ed è per questo che saranno quelli che userai di più, spesso senza accorgertene.

I subagenti integrati

Anthropic documenta diversi tipi forniti con Claude Code, e sapere a cosa è vincolato ciascuno spiega parecchi comportamenti altrimenti sconcertanti.

Due dettagli di quella tabella meritano una sosta.

L’agente Explore ha un tetto a Opus sull’API di Claude, e Anthropic spiega che serve a evitare che Explore giri su un modello più costoso di quello già scelto per la sessione. È un freno di costo voluto, e significa che cercare nella tua codebase non viene addebitato di nascosto a tariffa da modello di punta.

Explore e Plan sono entrambi in sola lettura, con Write e Edit negati. È questo a rendere sicura la delega: puoi mandare un agente a indagare senza alcuna possibilità che nel frattempo inizi a modificare.

Scrivere il proprio

Un subagente personalizzato è un file Markdown con frontmatter. La struttura è abbastanza breve da ricordarsi a memoria.

---
name: code-improver
description: Analizza i file e propone miglioramenti di leggibilità, prestazioni e buone pratiche. Da usare dopo aver scritto o modificato codice.
tools: Read, Grep, Glob
model: sonnet
---
Sei uno specialista del miglioramento del codice. Per ogni problema trovato, spiega la causa, mostra il codice attuale e fornisci una versione migliorata.

Quattro campi fanno tutto il lavoro. name è il modo in cui viene invocato. description è ciò che Claude legge quando decide se delegare, il che la rende la riga più importante del file. tools limita ciò che può fare. model sceglie il livello.

La descrizione merita più cura di quanta ne riceva di solito. Claude la usa per decidere quando quell’agente si applica, quindi una descrizione vaga produce un agente mai usato oppure usato per le cose sbagliate. Indica esplicitamente la condizione di attivazione, come nell’esempio sopra con “Da usare dopo aver scritto o modificato codice”.

Il modo più rapido per crearne uno è chiederlo a Claude Code. Descrivi cosa vuoi, dove deve stare e cosa gli è consentito fare, poi rileggi il file generato prima di usarlo.

Dove risiedono le definizioni dei subagenti

Anthropic documenta cinque posizioni con un ordine di precedenza definito, e conoscerlo evita la confusione ricorrente in cui un agente si comporta diversamente dal file che stai guardando.

1. Impostazioni gestite, distribuite centralmente a livello di organizzazione. Priorità massima.
2. Il flag --agents della CLI, che accetta JSON e vale per la sessione corrente.
3. .claude/agents/, limitato al progetto corrente.
4. ~/.claude/agents/, disponibile in tutti i tuoi progetti.
5. La cartella agents/ di un plugin, ovunque quel plugin sia attivo. Priorità minima.

La regola pratica: le definizioni di progetto prevalgono su quelle personali, e ciò che la tua organizzazione distribuisce tramite impostazioni gestite prevale su entrambe.

Il flag --agents è poco sfruttato ed è comodo per lavori occasionali. Passi un oggetto JSON che definisce agenti in linea all’avvio di Claude Code, utile quando ti serve una configurazione specializzata una volta sola senza lasciare un file dietro di te.

Cosa sapere prima di costruire una flotta

Delegare costa un giro di andata e ritorno. Il subagente va avviato, gli va dato contesto e il suo risultato va restituito. Per un’attività che la conversazione principale chiuderebbe in due passi, quel sovraccarico è una perdita. La delega conviene quando il lavoro riverserebbe altrimenti molto materiale nel contesto principale.

Il subagente non vede la tua conversazione. Parte da zero con quello che gli passi. Un incarico che presuppone contesto condiviso produce un agente che lavora sul problema sbagliato, ed è di gran lunga il fallimento più comune.

Le restrizioni sugli strumenti sono il punto, non un limite. Un revisore in sola lettura che non può modificare è più utile di uno senza vincoli, perché puoi lanciarlo senza poi controllare cosa ha toccato.

I modelli più economici spesso bastano. Anthropic elenca l’inoltro di attività a modelli più veloci ed economici come Haiku tra i cinque motivi per usare i subagenti. A 1 dollaro per milione di token in ingresso contro 5 di Opus 5, un’attività meccanica delegata a Haiku è un risparmio reale senza costi di qualità.

Puoi disattivarli. Per bloccare un tipo integrato, aggiungilo a permissions.deny. Per fermare del tutto la delega, nega lo strumento Agent stesso. Per rimuovere solo Explore e Plan, imposta CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1, che richiede Claude Code v2.1.198 o successivo e fa leggere i file direttamente a Claude. In modalità non interattiva e nell’Agent SDK, CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1 rimuove tutti i tipi integrati lasciando solo i tuoi.

Un quadro decisionale: delegare o no

Passa un’attività attraverso queste cinque domande prima di scriverle un agente.

1. Genererà molto output che poi non mi serve? Cercare, esplorare, leggere molti file, scorrere log. Se sì, delega: è l’argomento più forte.
2. Conviene impedire la scrittura? Revisione, audit, analisi e indagine traggono tutti vantaggio da un agente in sola lettura, e il vincolo è proprio il valore.
3. È abbastanza meccanica per un modello più economico? Formattazione, refactoring meccanici, ricerche semplici. Instradala su Haiku e tieni la sessione principale sul modello che ti serve davvero.
4. Lo farò più di un paio di volte? Una cosa isolata non giustifica un file di definizione. Qualcosa di settimanale sì, e il riuso si accumula.
5. Posso istruirlo senza la cronologia della conversazione? Se l’attività ha senso solo con tre ore di contesto accumulato, la delega ti deluderà. Riscrivi l’incarico o tienilo nel filo principale.

Tre o più sì significano scrivere l’agente. Meno significa farlo in linea.

Errori comuni in questo momento

• Scrivere una description vaga, così Claude non delega mai a quell’agente o gli delega il lavoro sbagliato.
• Dare tutti gli strumenti a ogni agente personalizzato, buttando via il principale vantaggio di sicurezza.
• Delegare qualcosa di piccolo, dove il sovraccarico del giro supera il risparmio.
• Dare per scontato che il subagente veda la conversazione e istruirlo come se fosse così.
• Costruire una grande libreria di agenti prima di aver verificato che almeno uno venga usato.

Tre agenti da scrivere per primi

Se preferisci punti di partenza concreti ai principi, questi tre si ripagano nella maggior parte delle codebase e costano pochi minuti ciascuno.

Un revisore in sola lettura. Strumenti limitati a Read, Grep e Glob, modello su Sonnet, con un prompt di sistema che gli chiede di segnalare i problemi del codice attuale e una sostituzione proposta invece di apportare modifiche. Poiché non può modificare, puoi lanciarlo su qualsiasi cosa senza controllare dopo cosa ha toccato.

Un investigatore dei test che falliscono. Dagli la capacità di eseguire test e leggere file, e un prompt che gli chieda di trovare la causa radice e riferirla invece di riparare qualcosa. La separazione conta: un agente che diagnostica e riferisce ti lascia decidere se vale la pena correggere, mentre uno che diagnostica e ripara ti vincola alla sua prima teoria.

Un verificatore della documentazione su Haiku. Lavoro meccanico di confronto tra ciò che la documentazione afferma e ciò che il codice fa. È esattamente il profilo per un modello economico: alto volume, poco giudizio, output facile da verificare.

Nota che due dei tre sono in sola lettura e il terzo gira sul modello più economico. Quel rapporto non è casuale. Gli agenti che vengono davvero usati sono quelli sicuri da lanciare senza supervisione o abbastanza economici da lanciare spesso.

Dove si colloca in un flusso più ampio

I subagenti si sposano naturalmente con la modalità piano. Indagare in un agente in sola lettura, riportare un riassunto, pianificare rispetto a quel riassunto nella conversazione principale e poi eseguire. L’esplorazione non entra mai nel contesto principale e il piano si costruisce su una sintesi pulita invece che su quaranta file di output grezzo.

Cambiano anche il comportamento delle sessioni lunghe. L’effetto pratico di deviare l’esplorazione è che una sessione resta utilizzabile molto più a lungo prima che la pressione sul contesto la degradi, e per chi sta portando avanti un’attività grossa questo vale più del risparmio di token.

Costruire il giudizio dietro la configurazione

La meccanica di questa pagina si impara in venti minuti. Quello che richiede più tempo è capire quale lavoro delegare, come istruire un agente perché il suo output sia utilizzabile e quando un vincolo migliora un risultato invece di limitarlo.

È lo stesso giudizio che vale per ogni strumento ad agenti: scomporre un’attività in parti eseguibili in autonomia, specificarne ciascuna perché l’output sia verificabile e progettare il passo di revisione che intercetta ciò che va storto. Impararlo in una sequenza strutturata invece che per tentativi produce un metodo che regge quando gli strumenti cambiano, cosa che in questo campo accade con regolarità. Se vuoi un percorso strutturato, esplora le lezioni di Coursiv e verifica i dettagli dei piani correnti sul sito ufficiale.

Domande frequenti

Il prossimo passo

Prendi l’indagine che ripeti più spesso, quella in cui finisci per leggere una dozzina di file per rispondere a una domanda ricorrente, e scrivile un agente in sola lettura con tools: Read, Grep, Glob e una descrizione che dica quando va usato. Lancialo una volta e confronta com’è la tua conversazione principale dopo, rispetto a una sessione in cui hai fatto la stessa ricerca in linea. Quel singolo confronto sostiene la delega meglio di qualsiasi spiegazione del meccanismo.