Subagenti di Claude Code: isolamento del contesto, orchestratore e revisore, quando non servono

Che cosa sono i subagenti di Claude Code

Un subagente è un'altra istanza dell'agente che l'agente principale avvia per un compito separato. Ha una propria finestra di contesto, un proprio prompt di sistema e un proprio elenco di strumenti consentiti. L'agente principale gli passa la descrizione del compito, il subagente lavora in autonomia — legge file, esegue comandi — e restituisce soltanto il messaggio finale.

La parola chiave è isolamento. Tutto ciò che il subagente ha letto lungo il cammino — decine di file, un output lungo dei test, ipotesi scartate — resta nel suo contesto e non entra in quello della sessione principale. L'agente principale vede un risultato breve: «l'errore è nella funzione X, la causa è questa, ci sono tre punti coinvolti».

I subagenti di Claude Code sono un caso particolare dell'idea più generale dei sistemi multi-agente: invece di un unico ciclo «ragiona — agisce — verifica» compare un grafo di più nodi, ciascuno con il proprio ruolo e la propria responsabilità.

Perché serve l'isolamento del contesto

La finestra di contesto è la risorsa principale dell'agente. Vi convivono contemporaneamente le istruzioni di CLAUDE.md, la cronologia del dialogo, il codice letto e l'output dei comandi. Quando l'agente passa mezz'ora a cercare la causa di un bug, il contesto si riempie di rumore: file che alla fine non c'entrano e log dei quali conta una sola riga.

Le conseguenze sono note a chi lavora a lungo con gli agenti: il modello comincia a rispettare peggio le regole del progetto, confonde i dettagli e, quando la cronologia viene compressa automaticamente, perde ciò che era importante. Il subagente risolve il problema in modo strutturale: il lavoro sporco si fa in un contesto separato, che viene scartato dopo la risposta.

• Ricerca e indagine. «Trova tutti i punti in cui viene chiamata la funzione di pagamento e descrivi come sono fatti» è un compito tipico per un subagente.
• Verifiche rumorose. Eseguire i test e analizzare quelli caduti: affidatelo a un subagente e ricevete l'elenco delle cause.
• Lettura di documenti grandi. Una specifica di centinaia di pagine serve per pochi fatti: lasciate che il subagente li estragga.

Come configurare un subagente: la cartella .claude/agents

Un subagente personalizzato si descrive con un file Markdown con intestazione YAML. I file di progetto stanno in .claude/agents/ nel repository e sono disponibili a tutto il team tramite git; quelli personali in ~/.claude/agents/ funzionano in tutti i vostri progetti. Si può creare e modificare un subagente anche in modo interattivo, con il comando /agents di Claude Code.

---
name: code-reviewer
description: Controlla le modifiche al codice alla ricerca di errori e violazioni delle regole del progetto. Usalo dopo aver completato il compito, prima del commit.
tools: Read, Grep, Glob, Bash
---
Sei un revisore del codice. Non devi correggere nulla.

1. Guarda le modifiche: git diff.
2. Controlla ogni modifica per errori di logica, gestione degli errori,
   sicurezza (SQL, escaping dell'output, segreti).
3. Confrontala con le regole di AGENTS.md.
4. Restituisci l'elenco delle osservazioni: file, riga, problema, perché è importante.
   Se non ci sono osservazioni, scrivilo esplicitamente.

Il significato dei campi:

Il corpo del file è il prompt di sistema del subagente. Non vede la cronologia del vostro dialogo, quindi tutto ciò che deve sapere sul ruolo e sul formato della risposta deve stare nel prompt o nel compito che l'agente principale gli passa.

Come richiamare un subagente

L'agente principale può scegliere lui stesso il subagente, se il compito corrisponde alla sua description. È più affidabile chiederlo esplicitamente: «Usa il subagente code-reviewer per controllare le modifiche». Frasi come «usalo in modo proattivo» nella descrizione aumentano la probabilità che venga richiamato senza sollecitazione, ma non la garantiscono.

Subagente esploratore

Il secondo file che conviene avere quasi in ogni progetto è un esploratore in sola lettura. Risponde a domande sul codice e non modifica nulla.

---
name: explorer
description: Cerca nella base di codice le risposte su dove e come è costruito qualcosa. Usalo quando bisogna leggere molti file per ottenere un risultato breve.
tools: Read, Grep, Glob
---
Esplori il codice e non modifichi nulla.
Restituisci: una risposta breve alla domanda, l'elenco dei file con le righe
su cui si basa, e ciò che non è stato possibile verificare.

Un subagente così è particolarmente utile all'inizio del compito: l'agente principale ottiene una mappa dei punti giusti senza spendere contesto nella lettura di tutto, e prosegue lavorando sui file concreti.

Lo schema «orchestratore ed esecutori»

Lo schema multi-agente più diffuso è questo: un agente orchestratore tiene il piano e la visione d'insieme e distribuisce i singoli passi agli esecutori. L'orchestratore non legge tutto il codice da solo: formula i compiti, accetta i risultati e decide il passo successivo.

1. L'orchestratore scompone il compito in parti indipendenti e per ciascuna scrive un incarico autosufficiente: obiettivo, dove cercare, che cosa considerare completato, in quale forma restituire la risposta.
2. Gli esecutori svolgono gli incarichi nei rispettivi contesti.
3. L'orchestratore raccoglie le risposte, verifica che le parti combacino e avvia il passo successivo o un ritorno a quello precedente.

Il punto debole dello schema è il passaggio del compito. Il subagente conosce solo ciò che gli è stato scritto. Un incarico del tipo «correggi il bug di cui abbiamo parlato» per lui è vuoto: non ha visto la discussione. Un buon incarico si legge come un compito per un nuovo collega che apre il repository per la prima volta.

Che cosa deve restituire un esecutore

Definite in anticipo il formato della risposta: elenco dei file, output, cause trovate, che cosa non è stato possibile verificare. Una risposta breve e strutturata risparmia il contesto dell'orchestratore, e la voce «non verificato» protegge dalla falsa sicurezza — l'esecutore, come ogni agente, tende a riferire un successo.

Revisore separato: perché distinguere giudice ed esecutore

Quando lo stesso agente scrive il codice e poi lo verifica da sé, giudice e imputato condividono la stessa testa. L'agente ricorda che cosa voleva fare e vede nel codice la propria intenzione, non ciò che è scritto. Inoltre ha interesse a concludere: la verifica diventa una formalità.

Il revisore in un contesto separato è privo di questi problemi. Non conosce la storia delle decisioni, vede solo il diff e le regole del progetto, e valuta il risultato con uno sguardo nuovo. È lo stesso principio di un team reale: l'autore non approva la propria pull request.

• Date al revisore solo strumenti di lettura ed esecuzione delle verifiche, senza il diritto di modificare i file. Così non si metterà a «correggere in silenzio» invece di segnalare il problema.
• Descrivete esplicitamente i criteri: che cosa è considerato un errore, quali regole del progetto sono obbligatorie.
• La decisione su che cosa fare delle osservazioni lasciatela all'orchestratore o alla persona. Il revisore trova, l'esecutore corregge.

Il revisore non sostituisce le verifiche meccaniche. Test, linter e controllo dei tipi sono nodi deterministici, più affidabili di qualunque modello. Il revisore intercetta ciò che la meccanica non vede: logica sbagliata, violazioni di accordi, complessità inutile.

Avvio in parallelo dei subagenti

Claude Code può avviare più subagenti contemporaneamente. Questo accelera il lavoro quando le parti del compito sono davvero indipendenti: studiare tre moduli, verificare le modifiche da tre punti di vista (sicurezza, prestazioni, test), raccogliere informazioni da più fonti.

Il parallelismo funziona bene in lettura e male in scrittura. Se due esecutori modificano contemporaneamente gli stessi file, si sovrascrivono a vicenda le modifiche e nessuno se ne accorge. Nei termini del grafo degli agenti, è uno stato condiviso senza una regola di fusione. Regole pratiche:

• In parallelo vanno l'indagine, l'analisi, la revisione. In sequenza le modifiche a file che si sovrappongono.
• Se gli esecutori scrivono comunque in parallelo, dividete le zone: ognuno lavora solo nei propri file oppure nella propria copia del repository (per esempio in un git worktree separato).
• I risultati li riunisce un solo nodo — l'orchestratore — e non gli esecutori tra loro.

Quando i subagenti non servono

Lo schema multi-agente ha un costo: più token, più tempo, più punti in cui le informazioni si perdono nel passaggio. I subagenti di Claude Code non sempre ripagano.

Prima di costruire un grafo di agenti, rispondete a poche domande semplici: chi è responsabile dell'obiettivo comune, chi può mettere il veto e annullare una modifica, quali metriche definiscono il successo. Se non ci sono risposte, più agenti moltiplicano solo la confusione di uno.

Errori tipici con i subagenti

Descrizione vaga

La descrizione «assistente per il codice» non aiuta l'agente principale a capire quando chiamarlo. Scrivete il trigger: «dopo modifiche nella cartella api/, prima del commit».

Incarico senza contesto

Il subagente riceve un compito senza percorsi, senza criteri di completamento e senza limiti, e spende metà del lavoro per indovinare che cosa ci si aspetta da lui. Il rimedio è un modello di incarico: obiettivo, dati di ingresso, vincoli, formato della risposta.

Permessi troppo ampi

L'esploratore e il revisore non hanno bisogno del diritto di modificare file. Il campo tools è un modo economico per rendere il ruolo un vincolo meccanico, non una richiesta nel prompt.

Fiducia nel rapporto senza verifica

«Tutti i test sono passati» nella risposta di un subagente è un'affermazione, non un fatto. L'orchestratore deve basarsi su ciò che è verificabile: output del comando, codice di ritorno, righe precise.

In breve

I subagenti di Claude Code servono a tre cose: tenere pulito il contesto principale, separare la verifica dall'esecuzione e parallelizzare il lavoro indipendente. Si descrivono con brevi file Markdown in .claude/agents/, e la qualità del loro lavoro dipende quasi interamente dalla descrizione del ruolo, dall'insieme di strumenti e da quanto è autosufficiente l'incarico. Dove il compito è piccolo o strettamente legato al dialogo, un solo agente resta la scelta migliore. Il passaggio da un ciclo singolo a un sistema di nodi, archi e stato condiviso è approfondito in pratica nel corso.