Il piccolo aiutante

Cos'è e perché conta

Un subagent è un aiutante che Claude lancia per un lavoro preciso. Ha un contesto tutto suo: apre i file, cerca, legge, e alla fine ti torna solo il riassunto. Tutto il materiale che ha letto per arrivarci resta lì e non finisce nella tua conversazione.

Perché conta: la conversazione principale ha uno spazio limitato. Se Claude apre cinquanta file per capire dove sta il login, tutto quel testo occupa la chat e dopo un po' Claude fa più fatica a seguire il filo. Con un subagent la ricerca la fa lui, e a te arriva una risposta di poche righe.

«Piccolo» qui vuol dire che fa un compito solo, non che è meno capace: di solito un subagent usa lo stesso modello della conversazione principale. Nelle sessioni normali di solito lavora in background, e tu intanto continui a parlare con Claude.

Claude Code ne ha già alcuni pronti. Quello che uso di più è Explore: serve a cercare e capire il codice ed è di sola lettura, cioè non può scrivere né modificare i file. Poi ci sono quelli che crei tu, e li vediamo più sotto.

1. Cercare senza riempire la chat

È il caso più semplice. Devo capire dove sta una cosa nel progetto e non mi interessa vedere tutti i file che Claude apre per trovarla.

Usa un subagent Explore per trovare dove si gestisce il login. Dimmi solo i file e le righe.

La seconda frase conta quanto la prima. «Dimmi solo i file e le righe» dice all'aiutante cosa riportare. Se non lo dici, ti torna un riassunto lungo che riempie la chat lo stesso.

Ricordati che Explore non vede la nostra conversazione e parte anche senza il file CLAUDE.md del progetto, così resta veloce. Quindi nella frase metti quello che gli serve: cosa cerchi, in che parte dell'app, cosa vuoi indietro.

2. Tre lavori insieme

Quando ho più lavori che non dipendono l'uno dall'altro, li lancio in parallelo. Ogni aiutante ha il suo contesto e il suo compito, e alla fine Claude mette insieme i risultati.

Lancia tre subagent in parallelo: uno cerca dove si gestisce il login, uno legge i log dell'ultimo errore e mi dice la causa, uno scrive i test per la pagina dei prezzi. Quando finiscono, fammi un riassunto di tutti e tre.

Funziona perché i tre lavori non si incrociano: cercare il login non serve per leggere i log, e nessuno dei due tocca i test dei prezzi. Se il secondo lavoro ha bisogno del risultato del primo, non è un lavoro parallelo: fallo dopo.

3. Ctrl+B e /tasks

Se un lavoro sta prendendo tempo e ti blocca, tipo un comando che gira da minuti, premi Ctrl+B: va in background e tu continui a scrivere. Ctrl+B funziona sia con i comandi sia con gli aiutanti. Se usi tmux, premilo due volte.

Per vedere chi sta lavorando, scrivi:

/tasks

Ti mostra il lavoro in background della sessione: i comandi che girano e i subagent, anche quelli appena finiti. Da lì puoi aprire il lavoro di un aiutante e leggere cosa ha fatto, oppure fermarlo se ha preso la strada sbagliata.

4. Un aiutante fisso

Se un lavoro lo ripeti spesso, conviene un aiutante fisso. È un file nella cartella .claude/agents del progetto: in alto ci sono il nome, una descrizione di quando usarlo e gli strumenti che può usare, sotto le istruzioni scritte in parole normali. Non serve scriverlo a mano: lo chiedi a Claude.

Creami un subagent in .claude/agents che rivede il codice senza modificare niente, e chiamalo code-reviewer.

Il risultato somiglia a questo:

---
name: code-reviewer
description: Rivede il codice e segnala i problemi. Non modifica nessun file.
tools: Read, Grep, Glob
---

Sei un revisore di codice. Leggi le modifiche che ti indico e cerca bug, casi non gestiti e parti poco chiare. Per ogni problema dimmi il file, la riga e come lo sistemeresti. Non modificare niente.

La riga che conta è tools: sono gli strumenti che l'aiutante può usare. Per un revisore bastano quelli per leggere e cercare, cioè Read, Grep e Glob. Non devono esserci Write ed Edit, e nemmeno Bash, perché anche dal terminale si possono modificare i file. Se non sei sicuro, chiedilo:

Apri il file del subagent code-reviewer e dimmi quali strumenti può usare. Se c'è qualcosa che gli permette di modificare i file, toglilo.

Poi lo usi così, quando hai finito un pezzo di lavoro:

Fai controllare le ultime modifiche al subagent code-reviewer.

Nel file puoi aggiungere anche una riga model per scegliere il modello: haiku per lavori semplici e veloci, sonnet o opus per quelli più impegnativi, inherit per usare lo stesso della conversazione.

Il file in .claude/agents vale per quel progetto. Se lo metti in ~/.claude/agents, lo ritrovi in tutti i tuoi progetti. Esiste anche il comando /agents, ma il modo più semplice resta chiederlo a Claude o aprire il file.

5. Quando non li lancio

• Lavori piccoli: cambiare un testo, un colore, una riga. Un aiutante parte da zero e prima deve capire il progetto: ci mette più che farlo direttamente.
• Lavori che toccano gli stessi file: due aiutanti sullo stesso file si pestano i piedi. Falli uno dopo l'altro, oppure ognuno nella sua copia del progetto, i worktree. Per un aiutante fisso basta aggiungere nel suo file la riga isolation: worktree.
• Quando voglio seguire ogni passo: l'aiutante ti porta il risultato alla fine. Se devo correggerlo a ogni passo, resto nella conversazione principale.
• Quando serve tutto quello che ci siamo detti: un aiutante come Explore parte con un contesto pulito e non vede la nostra chat. Va spiegato da capo, quindi spiegalo bene nella frase.

Una regola

Ogni aiutante consuma token suoi, e contano negli stessi limiti di utilizzo della conversazione principale. Tre aiutanti con un compito chiaro ciascuno sì, dieci lanciati «tanto per» no.

Gli errori più comuni

• Lanciare un aiutante per una modifica da una riga: falla direttamente, si fa prima.
• Scrivere una frase vaga tipo «guarda il login»: di' cosa cercare, dove, e cosa vuoi indietro.
• Dare per scontato che l'aiutante sappia cosa vi siete detti: non vede la chat, quindi mettigli il contesto nella frase.
• Mettere due aiutanti sugli stessi file nello stesso momento: falli lavorare uno dopo l'altro, o ciascuno nel suo worktree.
• Fidarsi di un revisore «di sola lettura» senza guardare la riga tools: apri il file e controlla che non ci siano Write, Edit o Bash.
• Lanciarne tanti «tanto per»: ognuno consuma token suoi, quindi lancia solo quelli con un compito chiaro.

Checklist

• Il lavoro è abbastanza grande da valere un aiutante
• La frase dice cosa cercare e cosa riportare
• Il contesto che serve è scritto nella frase
• I lavori in parallelo non toccano gli stessi file
• So che con /tasks vedo chi sta lavorando
• Il revisore fisso ha solo strumenti per leggere

Domande frequenti