I sub agents di Claude Code sono assistenti AI specializzati, ciascuno con un compito preciso, una finestra di contesto separata dalla conversazione principale, un prompt di sistema dedicato e un elenco di strumenti autorizzati. Servono a una cosa sola: far lavorare Claude su un compito mirato senza riempire la sessione principale di log, risultati di ricerca e file letti. Il sub agent esegue, e alla conversazione principale torna solo una sintesi. La documentazione ufficiale di Anthropic li descrive così, e la pagina che avevo letto nell'estate 2025 introduceva questa possibilità per ottimizzare workflow specifici e gestire meglio il contesto.

Perché usarli

Quattro vantaggi, in ordine di importanza pratica:

  • Preservazione del contesto. Ogni sub agent opera nel proprio contesto, quindi la conversazione principale resta concentrata sugli obiettivi di alto livello invece di essere contaminata dai dettagli di un singolo compito.
  • Competenza specializzata. Con istruzioni dettagliate per un dominio specifico (revisione del codice, esecuzione dei test, analisi dei log) il tasso di successo su quel compito aumenta.
  • Riutilizzabilità. Una volta creato, un sub agent funziona in progetti diversi e può essere condiviso con il team, così il flusso di lavoro resta coerente.
  • Autorizzazioni flessibili. Ogni sub agent può avere livelli di accesso diversi agli strumenti: gli strumenti potenti si riservano ai soli sub agent che ne hanno davvero bisogno.

Un esempio concreto dell'ultimo punto: un revisore di codice non ha motivo di poter scrivere file, quindi gli si concedono solo gli strumenti di lettura. Il vincolo sta nella configurazione, non nella fiducia.

Creare il primo sub agent

Il percorso che descrivevo in origine passa dal comando /agents, con una procedura in quattro passi:

  1. Aprire l'interfaccia dei sub agents con /agents.
  2. Scegliere "Crea nuovo agente", a livello di progetto o di utente.
  3. Descrivere in dettaglio cosa fa e quando va usato, poi selezionare gli strumenti a cui ha accesso.
  4. Salvare. Claude lo userà in automatico quando il compito è pertinente, oppure lo si richiama esplicitamente.

Il comportamento di /agents è cambiato nelle versioni recenti. Secondo la documentazione, dalla versione 2.1.197 in poi il comando ricorda che si può chiedere a Claude di creare l'agente o modificare direttamente le cartelle degli agenti, mentre le versioni precedenti aprono ancora la procedura guidata. Il risultato finale è lo stesso: un file.

Com'è fatto un sub agent

Un sub agent è un file Markdown con frontmatter YAML. Solo name e description sono obbligatori; tools è facoltativo e, se omesso, il sub agent eredita tutti gli strumenti disponibili. Un esempio minimo, ripreso dalla documentazione:

---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---

You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.

La description è il campo che conta di più: è quella che permette a Claude di decidere quando delegare. Va scritta come una regola di attivazione ("usalo dopo aver modificato il codice"), non come una presentazione generica.

Dove vivono i file e chi ha la precedenza

I sub agents si salvano in due posizioni principali:

  • .claude/agents/ per i sub agent di progetto, disponibili solo nel progetto corrente e adatti a essere versionati insieme al codice.
  • ~/.claude/agents/ per i sub agent utente, disponibili in tutti i progetti.

Quando i nomi sono in conflitto, vince il livello di progetto su quello utente. La documentazione attuale elenca anche altri livelli (impostazioni gestite dall'organizzazione, flag --agents da riga di comando, agenti dei plugin), ma per l'uso quotidiano la distinzione tra progetto e utente resta quella che conta. L'identità di un agente viene dal campo name, non dal nome del file.

Quando conviene e quando no

Un sub agent vale la pena quando il compito produce molto output che alla conversazione principale non serve (test eseguiti, log, documentazione consultata) o quando richiede restrizioni sugli strumenti. Per il lavoro che richiede scambi continui, invece, conviene restare nella conversazione principale: un sub agent parte da zero e può aggiungere latenza. Anche i costi vanno guardati, perché la documentazione precisa che le richieste dei sub agent contano negli stessi limiti d'uso della conversazione principale.

Il risultato è un piccolo team virtuale di assistenti specializzati, ciascuno incaricato di compiti specifici, con il contesto sotto controllo. Chi vuole capire cosa cambia quando la finestra di contesto disponibile cresce molto può leggere Claude Sonnet 4 con 1 milione di token di contesto.

Fonte: Sub agents, documentazione Claude Code.