Subagent Claude Code: come crearli e usarli

Quando lavoro a un task grosso con Claude Code, il problema non è la potenza del modello: è il contesto. Una ricerca su venti file, l’output di una suite di test, mille righe di log — tutto questo finisce nella conversazione principale e la intasa di roba che non rileggerò mai. I subagent di Claude Code risolvono esattamente questo: assistenti specializzati che fanno il lavoro sporco nella loro finestra di contesto e mi restituiscono solo la sintesi. In questa guida spiego cosa sono, come si definiscono e quando conviene davvero usarli.

Cosa sono i subagent in Claude Code

Un subagent è un assistente AI specializzato che gestisce un tipo specifico di task. La caratteristica che lo rende utile è l’isolamento: ogni subagent gira in una propria finestra di contesto, con un system prompt dedicato, un accesso agli strumenti definito da me e permessi indipendenti. Quando Claude incontra un compito che corrisponde alla descrizione di un subagent, glielo delega; quello lavora per conto suo e riporta indietro le conclusioni.

I vantaggi concreti sono quattro:

• Preservare il contesto. Esplorazione e output verboso restano fuori dalla conversazione principale.
• Imporre vincoli. Posso limitare quali strumenti un subagent può usare (per esempio, solo lettura).
• Riusare configurazioni. Un subagent definito a livello utente è disponibile in tutti i progetti.
• Controllare i costi. Posso instradare i task semplici verso un modello più rapido ed economico come Haiku.

Claude Code arriva già con alcuni subagent integrati che usa in automatico quando servono:

• Explore — agente di sola lettura, ottimizzato per cercare e analizzare codebase. Gira su Haiku per essere veloce ed economico, senza accesso a Write ed Edit.
• Plan — agente di ricerca usato in plan mode per raccogliere contesto prima di proporre un piano. Sola lettura.
• general-purpose — agente completo per task multi-step che richiedono sia esplorazione sia azione. Ha accesso a tutti gli strumenti ed eredita il modello della conversazione principale.

Come si crea un subagent

I subagent sono file Markdown con un blocco di frontmatter YAML in testa. Posso crearli a mano oppure, più comodamente, con il comando /agents dentro Claude Code, che apre un’interfaccia guidata (e può perfino generare descrizione e system prompt al posto mio).

Dove vanno i file

La posizione determina lo scope. I due casi che uso più spesso:

• Progetto: .claude/agents/ nella cartella del progetto. Ideale per subagent specifici di una codebase; li metto sotto version control così tutto il team li condivide.
• Utente: ~/.claude/agents/ nella home. Subagent personali, disponibili in tutti i miei progetti.

Esistono anche scope a priorità più alta (managed settings dell’organizzazione, il flag --agents per la singola sessione) e uno a priorità più bassa (i plugin). Quando due subagent hanno lo stesso name, vince quello nello scope a priorità maggiore.

La struttura del file

Il frontmatter definisce metadati e configurazione; il corpo Markdown diventa il system prompt che guida il comportamento del subagent. Un esempio di revisore di codice in sola lettura:

Il subagent riceve solo questo system prompt (più qualche dettaglio d’ambiente come la working directory), non l’intero system prompt di Claude Code.

I campi del frontmatter

Soltanto name e description sono obbligatori. Gli altri sono opzionali. I principali:

• name (obbligatorio) — identificatore univoco, lettere minuscole e trattini.
• description (obbligatorio) — quando Claude dovrebbe delegare a questo subagent. È il campo su cui si basa la delega automatica, quindi va scritto con cura.
• tools — gli strumenti consentiti (allowlist). Se omesso, eredita tutti gli strumenti della conversazione principale.
• disallowedTools — strumenti da negare (denylist), rimossi dalla lista ereditata.
• model — sonnet, opus, haiku, un ID completo (per esempio claude-opus-4-8) oppure inherit. Se omesso, il default è inherit, cioè lo stesso modello della conversazione principale.
• permissionMode — la gestione dei permessi: default, acceptEdits, plan e altri.

Per restringere gli strumenti uso tools come allowlist oppure disallowedTools come denylist. Se imposto entrambi, viene applicato prima disallowedTools e poi tools sul pool rimanente.

Come si invocano

Ci sono due modi, e nella pratica li uso entrambi.

Delega automatica. Claude decide da solo se delegare, in base alla mia richiesta e al campo description del subagent. Per favorire la delega proattiva, nella descrizione conviene inserire frasi come “use proactively”.

Invocazione esplicita. Tre modi, dal più leggero al più vincolante:

• Linguaggio naturale: nomino il subagent nel prompt e di norma Claude delega — per esempio “Use the code-reviewer subagent to look at my recent changes”.
• @-mention: digito @ e scelgo il subagent dalla lista, esattamente come si menziona un file. Questo garantisce che quel subagent venga eseguito.
• Sessione intera: con il flag --agent <nome> avvio una sessione in cui il thread principale assume direttamente system prompt, restrizioni e modello del subagent.

Quando conviene usarli

I subagent rendono al massimo in alcuni scenari ben precisi.

Isolare operazioni verbose

È l’uso più efficace. Far girare i test, scaricare documentazione, processare file di log: tutto output che consuma contesto. Delegando a un subagent, il malloppo resta nella sua finestra e nella conversazione principale rientra solo il riassunto utile. Per esempio: “Usa un subagent per lanciare la suite di test e riportare solo i test falliti con i relativi messaggi di errore”.

Ricerca in parallelo

Per indagini indipendenti, posso lanciare più subagent che lavorano in contemporanea — uno sul modulo di autenticazione, uno sul database, uno sulle API. Ognuno esplora la sua area, poi Claude sintetizza i risultati. Funziona meglio quando i percorsi di ricerca non dipendono l’uno dall’altro. Ho approfondito questa tecnica nell’articolo su come lanciare agenti AI in parallelo con il fan-out dei subagent.

Review del codice con vincoli

Un revisore di codice in sola lettura (niente Edit, niente Write) è il caso da manuale: gli do tools: Read, Grep, Glob, Bash, un system prompt che elenca cosa cercare e come formattare l’output, e lo richiamo dopo ogni modifica importante.

Concatenare i subagent

Per i flussi multi-step, chiedo a Claude di usare i subagent in sequenza: ognuno completa il suo compito e passa il contesto rilevante al successivo. Per esempio: “Usa il subagent code-reviewer per trovare i problemi di performance, poi il subagent optimizer per correggerli”.

Quando invece restare nella conversazione principale

Il subagent non è sempre la scelta giusta. Resto nella conversazione principale quando:

• Il task richiede continuo scambio o rifinitura iterativa.
• Più fasi condividono molto contesto (pianificazione, implementazione, test).
• Sto facendo una modifica veloce e mirata.
• Conta la latenza: i subagent partono da zero e possono impiegare tempo a raccogliere il contesto che serve.

C’è anche un costo da considerare: quando i subagent finiscono, i loro risultati rientrano nella conversazione principale. Lanciarne tanti che restituiscono ciascuno output dettagliato consuma comunque parecchio contesto. Se voglio un prompt riutilizzabile che giri nel contesto principale invece che isolato, valuto le Claude Skills.

Best practice

Dalla documentazione ufficiale e dall’uso quotidiano, quattro regole che ripagano sempre:

• Un subagent, un compito. Ognuno deve eccellere in una cosa sola. I subagent tuttofare delegano peggio.
• Descrizioni dettagliate. Claude sceglie a chi delegare leggendo il campo description: più è chiaro, più la delega automatica è precisa.
• Accesso minimo agli strumenti. Concedo solo i permessi necessari, per sicurezza e per tenere il subagent concentrato.
• Version control. Metto i subagent di progetto sotto Git così il team li usa e li migliora insieme.

In sintesi

I subagent di Claude Code sono lo strumento giusto quando un task secondario rischia di sommergere la conversazione principale di output che non rileggerò. Si definiscono in file Markdown dentro .claude/agents/ (progetto) o ~/.claude/agents/ (utente), con un frontmatter dove servono almeno name e description, e un corpo che fa da system prompt. Li gestisco col comando /agents, li limito negli strumenti e nel modello, e li richiamo per delega automatica o esplicita. Funzionano al meglio su lavori isolati, verbosi e indipendenti; per tutto il resto, la conversazione principale resta la scelta più pulita. Vale anche la pena ricordare l’arrivo di Opus 4.8 in Claude Code come modello da assegnare ai subagent più impegnativi.

Fausto Pitzalis

Blogger dal 2001, Nativo Digitale, Developer.
Da 15 anni mi occupo di IT per una grande Azienda.
Lavoro per abbattere il Digital Divide.
Visita i miei altri progetti
sardiniamobility.com
www.cyberness.it