Quando usare un subagent in Claude Code

Stai cercando la causa di un bug e chiedi a un secondo agente di leggere tutti i log, mentre tu continui a discutere la soluzione. Sembra parallelismo utile. Ma se il secondo incarico dipende da cinque decisioni prese nella conversazione principale e restituisce soltanto «trovato», hai separato il contesto senza progettare il passaggio di consegne.

Un subagent di Claude Code funziona bene quando riceve un problema autonomo, un perimetro leggibile e un formato di ritorno. Può esplorare molto materiale senza riempire la conversazione principale e può avere strumenti più stretti del resto della sessione.

Non è però una copia indipendente dell'intero ambiente. Separare il contesto, separare i file e separare le autorizzazioni sono tre decisioni diverse.

Che cos'è un subagent

La documentazione ufficiale sui subagent descrive agenti specializzati con una propria finestra di contesto, un prompt di sistema e strumenti configurabili. Claude può delegare loro un incarico e riceverne il risultato nella conversazione principale.

Questo aiuta soprattutto quando l'attività produce molte letture o dettagli intermedi. Il subagent può cercare riferimenti, confrontare implementazioni o controllare test senza consumare tutto il contesto della discussione principale.

Il vantaggio non nasce dal numero di agenti. Nasce dalla qualità del confine. Un incarico vago moltiplica l'ambiguità; un incarico autonomo restituisce un pezzo utilizzabile.

Il test di delegabilità

Prima di delegare, valuta quattro caratteristiche.

Autonomo: il risultato può essere prodotto senza chiedere continuamente decisioni alla conversazione principale?

Condiviso: quanta parte del contesto corrente è indispensabile per non interpretare male la domanda?

Compatto: il risultato finale può essere restituito in una forma breve e definita?

Rumoroso: la ricerca richiede molte letture, tentativi o confronti che non devono restare tutti nel filo principale?

Un incarico è un buon candidato quando è abbastanza autonomo, richiede poco contesto condiviso, ha un ritorno compatto e genera molto lavoro intermedio. Cercare tutti i punti in cui viene chiamata una funzione è spesso adatto. Decidere insieme quale promessa fare a un cliente, dopo una discussione ricca di sfumature, lo è molto meno.

Quando restare nella conversazione principale

Mantieni l'attività nel filo principale quando il lavoro è iterativo e ogni passaggio dipende dalla risposta precedente. È il caso di una diagnosi in cui cambi ipotesi dopo ogni prova, di una revisione editoriale basata su preferenze emerse durante la conversazione o di una decisione architetturale ancora aperta.

La conversazione principale è anche il posto migliore quando vuoi vedere il ragionamento operativo passo dopo passo e intervenire sui confini. Delegare troppo presto può ridurre la visibilità proprio nel momento in cui serve discutere.

Non usare un subagent per evitare di formulare la domanda. Se non sai ancora quale risultato ti serve, prima chiariscilo nel contesto condiviso.

Quando il subagent è la scelta giusta

I casi più adatti hanno un input stabile e un'uscita verificabile:

• mappare tutti i riferimenti a un'API nel repository;

• confrontare l'implementazione con una specifica fornita;

• leggere log voluminosi e raggruppare errori con evidenze;

• eseguire una revisione in sola lettura su un perimetro preciso;

• cercare test mancanti per un comportamento già definito;

• raccogliere fonti in un elenco con URL e claim supportati.

In questi casi il subagent può isolare il materiale intermedio e tornare con una sintesi. Chiedi comunque percorsi, righe, comandi o fonti che ti permettano di ricontrollare le conclusioni.

Contesto isolato non significa file isolati

Il subagent ha una finestra di contesto propria, ma gli strumenti concessi possono agire sullo stesso progetto della sessione principale. Se può modificare file, due agenti potrebbero intervenire sulla stessa area. Se può eseguire comandi, le conseguenze appartengono comunque all'ambiente condiviso.

Perciò devi decidere separatamente:

1. quale conversazione e quali istruzioni riceve;

2. quali strumenti può usare;

3. quali file o servizi può raggiungere;

4. se altre attività stanno lavorando sullo stesso stato.

Per una ricerca non serve concedere scrittura. Per una revisione del codice bastano spesso lettura, ricerca e ispezione del diff. Limitare gli strumenti riduce sia il rischio sia le interpretazioni possibili dell'incarico.

Subagent o sessione separata

Un subagent e una sessione in un worktree risolvono problemi diversi. Il primo separa soprattutto contesto e specializzazione. La seconda può separare lo stato persistente dei file e il branch su cui avvengono le modifiche.

Usa un subagent quando vuoi una ricerca o una verifica che torni alla sessione principale. Valuta una sessione separata quando un'attività deve proseguire a lungo, creare una propria serie di commit o modificare file in parallelo senza sovrapporsi al lavoro corrente. La documentazione sui workflow comuni illustra l'uso di più sessioni e worktree per attività parallele.

Non confondere quindi «ha un suo contesto» con «ha una sua copia del repository». Se ti serve il secondo risultato, devi predisporlo esplicitamente.

Definisci lo scope in una frase

Un buon incarico comincia con un oggetto e un confine: «Analizza la validazione dei file caricati sotto src/upload/ e trova i percorsi che possono accettare un tipo non consentito. Non modificare file».

Poi aggiunge ciò che è fuori perimetro: niente dipendenze, niente test live, niente modifiche all'autenticazione. Infine definisce la condizione di stop: se per rispondere serve accedere a un servizio esterno o decidere una policy, torna con il blocco invece di estendere l'incarico.

Il confine non deve contenere tutta la storia del progetto. Deve includere i fatti senza i quali il subagent prenderebbe una strada diversa.

Scegli gli strumenti minimi

La configurazione di un subagent può limitare gli strumenti disponibili. Un profilo in sola lettura, illustrativo, potrebbe essere impostato così:

---
name: source-checker
description: Verifica le fonti dichiarate e restituisce i riscontri.
tools: Read, Glob, Grep
---

Controlla soltanto le fonti nel perimetro indicato.
Per ogni claim restituisci fonte, passaggio rilevante e limite.
Non modificare file e non colmare i vuoti con supposizioni.

I nomi e i campi vanno controllati sulla versione corrente. Il principio resta: non assegnare strumenti di scrittura a un'attività che deve soltanto osservare. Se serve un comando specifico, concedi quello e definisci la prova attesa.

La configurazione dei permessi di Claude Code può aggiungere regole più precise allo scope del profilo.

Scrivi un contratto di ritorno

«Fammi sapere cosa trovi» produce risultati difficili da integrare. Un contratto di ritorno dovrebbe specificare quattro elementi:

• domanda: la decisione che il risultato deve informare;

• fonti: percorsi, righe, URL o comandi da citare;

• formato: tabella, elenco ordinato, patch proposta o verdetto;

• prova: come distinguere un fatto verificato da un'ipotesi.

Per esempio:

Restituisci massimo cinque risultati.
Per ciascuno indica file e riga, comportamento osservato,
rischio concreto e test che lo dimostrerebbe.
Se non trovi evidenza, scrivi "non verificato".
Non proporre una soluzione fuori dal perimetro.

Questo formato riduce il costo della delega. La sessione principale non deve ricostruire da zero come il subagent è arrivato alla conclusione.

La guida al contratto di output nei workflow AI mostra come rendere espliciti schema, stato e prove prima di affidare un passaggio a un altro componente.

Passa solo il contesto necessario

Il subagent non riceve magicamente ogni sfumatura utile della conversazione. Includi le decisioni già prese, le definizioni particolari e gli artefatti da considerare. Evita invece cronologie lunghe che nascondono la domanda.

Un pacchetto di contesto essenziale può contenere:

• obiettivo e motivo della ricerca;

• file o directory di ingresso;

• decisioni già chiuse;

• vincoli e divieti;

• esempio del risultato corretto;

• formato di ritorno.

Se un fatto è disponibile in un file del progetto, indica il percorso invece di parafrasarlo in modo incompleto. Se il fatto è temporaneo, dichiaralo come tale.

Verifica il ritorno prima di usarlo

Quando il subagent termina, non trattare la sintesi come una prova sufficiente. Apri almeno i riscontri che sostengono le conclusioni principali. Controlla se il perimetro richiesto è stato coperto e se le assenze sono state distinte dai risultati negativi.

Una risposta «non ho trovato chiamate» può significare che non esistono, che la ricerca era troppo stretta o che lo strumento non ha letto una parte del progetto. La checklist di verifica degli output AI aiuta a controllare copertura, evidenza e limiti prima di usare l'output in una decisione.

Se il ritorno apre una nuova domanda, decidi se affidare un secondo incarico delimitato o riportare il tema nella conversazione principale. Non allargare automaticamente lo stesso subagent fino a trasformarlo in un progetto senza confini.

Evita conflitti tra attività parallele

Due ricerche in sola lettura possono procedere sullo stesso repository con poco rischio. Due modifiche sulla stessa funzione no. Prima di lavorare in parallelo assegna proprietà chiare per file o componenti e stabilisci chi integra il risultato.

Se gli incarichi possono cambiare stato condiviso, usa sessioni o worktree separati e pianifica il merge. Se uno dei due deve soltanto informare l'altro, tienilo in sola lettura e restituisci una proposta, non una modifica.

Il parallelismo utile riduce il tempo senza nascondere la responsabilità. Se nessuno sa quale versione dei file è stata analizzata, il vantaggio scompare.

Crea un subagent da un incarico ricorrente

Non partire da un ruolo generico come «esperto di qualità». Scegli un incarico che hai già eseguito più volte e di cui conosci input, confini e uscita. Scrivi il profilo minimo, limita gli strumenti e provalo su tre casi: uno normale, uno senza evidenza e uno fuori scope.

Nel programma su Claude Cowork e Code di MAIKER HUB puoi progettare un subagent sul tuo lavoro reale e verificare il passaggio di consegne. Un buon subagent non è quello che sa fare tutto. È quello che torna con il pezzo giusto, nelle condizioni in cui puoi fidarti della prova.