Workbranch › Guide

Come usare i subagent in Claude Code

Le ricerche lunghe e l'output rumoroso dei test riempiono in fretta la tua conversazione con Claude Code. I subagent spostano quel lavoro in un contesto separato e ti restituiscono un riepilogo. Questa guida spiega cosa sono, come crearne di tuoi e quando conviene usarli.

Aggiornato 30 ottobre 2026

I dettagli qui sotto provengono dalla documentazione di Claude Code di Anthropic a ottobre 2026. Claude Code cambia spesso, quindi esegui claude update se manca qualcosa di quanto descritto.

Cosa sono i subagent

Quando Claude incontra un compito che corrisponde alla descrizione di un subagent, può delegarglielo. Il subagent parte da zero: non vede la tua conversazione, solo le istruzioni che Claude gli passa. Fa il suo lavoro, come leggere decine di file o eseguire una suite di test, e restituisce un riepilogo. La tua conversazione principale resta breve.

Claude Code include alcuni subagent integrati, tra cui:

• Explore: ricerca e analisi rapide, in sola lettura, di un codebase.
• Plan: ricerca in sola lettura mentre sei in plan mode.
• General-purpose: compiti in più passaggi che richiedono sia di esplorare sia di modificare.

Non devi configurarli; Claude li usa quando sono adatti.

Crea il tuo subagent

1. Decidi l'ambito. Per un subagent che tutto il team può usare in un repository, crea la cartella .claude/agents/ nel progetto. Per uno che ti segue in tutti i progetti, usa ~/.claude/agents/.
2. Crea un file Markdown in quella cartella, per esempio code-reviewer.md.
3. Inizia il file con il frontmatter tra due righe ---. La prima riga del file deve essere ---.
4. Aggiungi i due campi obbligatori: name (un identificatore univoco, per esempio code-reviewer, senza due punti) e description (quando Claude dovrebbe usarlo, per esempio Reviews code for quality and best practices. Use after code changes.).
5. Se vuoi, aggiungi tools per limitare cosa può usare, per esempio Read, Glob, Grep per un revisore in sola lettura, e model (un alias di modello come sonnet o haiku, un ID di modello completo oppure inherit).
6. Sotto la riga --- di chiusura, scrivi le istruzioni del subagent in linguaggio semplice: il suo ruolo, cosa controllare e cosa restituire.
7. Salva il file. Claude Code recepisce entro pochi secondi le modifiche in una cartella agents esistente; se hai creato la cartella durante la sessione, riavvia Claude Code.

Usare un subagent

• Lascia scegliere a Claude: Claude confronta la tua richiesta con la description di ogni subagent. Espressioni come "use proactively" nella descrizione lo incoraggiano a delegare.
• Chiedilo per nome: per esempio Usa il subagent code-reviewer per controllare le mie ultime modifiche.
• Menzionalo: digita @ e scegli il subagent. Così hai la garanzia che sia quel subagent a occuparsi del compito.
• Per un'intera sessione: esegui claude --agent code-reviewer.

Quando i subagent aiutano e quando no

Le indicazioni di Anthropic si riassumono così:

Da sapere

• Se due subagent hanno lo stesso nome, vince la posizione con priorità più alta: impostazioni gestite, poi il flag --agents, poi la cartella del progetto, poi la tua cartella utente, poi i plugin.
• Un subagent non vede la cronologia della chat né i file che Claude ha già letto, quindi si basa sulle istruzioni che Claude gli dà.
• Per impostazione predefinita possono essere in esecuzione fino a 20 subagent contemporaneamente.
• I nomi dei campi sono in camelCase (per esempio disallowedTools, maxTurns) e i campi non riconosciuti vengono ignorati senza avviso, quindi controlla come li scrivi.
• I file dei subagent di progetto si possono includere in un commit, così tutto il team ha gli stessi assistenti.

Se non funziona

• Claude non trova il nuovo subagent: se la cartella agents non esisteva all'avvio della sessione, riavvia Claude Code.
• Il file viene saltato senza avviso: le cause comuni sono un name o una description mancanti, YAML non valido oppure --- non sulla prima riga. Esegui claude --debug e leggi il log di debug, oppure esegui claude plugin validate .claude/agents per trovare i file il cui frontmatter non viene interpretato.
• Claude segnala un errore che nomina strumenti non risolti: quando nessuna voce di tools corrisponde a uno strumento reale, di solito Claude Code non avvia il subagent. Correggi i nomi degli strumenti.
• Modello sbagliato: esegui /tasks per vedere quale modello usa davvero ogni subagent.

Conserva i risultati, non solo il riepilogo

Il rapporto di un subagent finisce nella tua sessione, che sparisce dalla vista quando la sessione si chiude. Con il plugin Workbranch per Claude Code, dicendo "save this to Workbranch" (salva questo su Workbranch) archivi in un progetto i compiti, le decisioni e le domande aperte della sessione, e la sessione successiva in quella cartella parte da ciò che è ancora aperto. Vedi Workbranch per Claude. Se una sessione ha esaurito lo spazio, come riprendere una sessione di Claude Code spiega come rientrare.

Fonti

• Use Claude Code with your Pro or Max plan (Claude Help Center, verificato il 30 ottobre 2026)
• Create custom subagents (Claude Code docs, verificato il 30 ottobre 2026)

Domande frequenti