Come creare agenti con Claude Code: ruolo, regole e prova

Come creare agenti con Claude Code: il lavoro lungo che non ti riempie la chat

Per creare un agente con Claude Code scrivi un file di testo nella cartella .claude/agents del tuo progetto, con un nome, una descrizione e le sue istruzioni. L'agente fa un lavoro a parte, con i soli strumenti che gli dai, e alla conversazione torna un riassunto. Il file lo metti nel progetto prima di aprire Claude Code, poi, secondo la documentazione, gli affidi il lavoro a parole o con @agent-nome.

La documentazione lo chiama subagente: è la stessa cosa (pagina ufficiale sui subagenti, anche in italiano). Claude Code è il programma di Anthropic che lavora sui file di una cartella del tuo computer, e non è nel piano gratuito: serve un account a pagamento (installazione, pagina dei piani, verificato a novembre 2026).

L'esempio di questa guida è il bar «Da Rosa» di Catania, che non esiste: l'abbiamo inventato noi, con Rosa e le sue recensioni. Ha un anno di recensioni in un file. Prima Rosa le incolla in chat, legge pagine di passaggi intermedi, e la conversazione si riempie di roba che non rileggerà più. Dopo un agente le rilegge a parte e riporta cosa tornano a lamentare i clienti, quante volte, con quali frasi. Le recensioni contano anche per farsi trovare: nella guida alla scheda Google della tua attività c'è il perché, e come chiederle senza violare le regole di Google.

La prova, e prima di tutto cosa non è. L'avvio di un agente vero col modello vero, a parole e per nome, non è provato. Da terminale, la finestra in cui si scrivono i comandi, il nostro Claude Code non aveva l'accesso. E una sessione, cioè una conversazione con il programma dall'apertura alla chiusura, se è già aperta su una cartella più in alto non rileva l'agente. Quello che abbiamo provato, e con cosa, sta nel capitolo «Cosa abbiamo provato e cosa no».

I testi qui sotto sono quindi un'altra cosa: testo prodotto da un modello piccolo a cui abbiamo dato le istruzioni dell'agente. Modello Haiku di Claude, una sessione nuova per ogni richiesta, che non sapeva niente del resto, e 60 recensioni inventate. Non è un agente lanciato da Claude Code. Le uscite sono copiate così come sono, difetti compresi.

Guarda bene cosa cambia, perché non è «senza agente sbaglia». I conteggi sono giusti tutti e due: la differenza fra 6 e 7 sulla granita dipende da una recensione al limite, e noi stessi l'abbiamo segnata così. Su questi dati facili, due agenti su cinque danno lo stesso risultato anche senza istruzioni: questo e quello delle consegne. Con le istruzioni cambia la forma: i numeri delle recensioni per ricontrollare, le frasi copiate, niente ipotesi non chieste, una lunghezza decisa da te. E il limite va detto: l'uscita è di 255 parole contro un massimo di 250. Una regola scritta nel testo è una richiesta, non un blocco.

La differenza si vede di più su un lavoro piccolo: dividere 40 messaggi inventati per tipo e segnalare quelli da vedere subito.

Con le istruzioni: i conti tornano con le nostre soluzioni, e ci sono i quattro messaggi che avevamo segnato come urgenti (3, 5, 15, 22), più il 36, accettabile. Senza istruzioni, con la stessa richiesta più il nome del file: 791 parole, sette gruppi decisi da lui, consigli non chiesti, nessun conteggio per gruppo, e fra i messaggi da leggere subito ci sono il 22 e il 5 ma non il 3 e il 15. Sono poche prove su dati inventati: non è una statistica.

Quando conviene. Quando un lavoro laterale riempirebbe la conversazione di risultati che non rileggerai, quando vuoi un controllo fatto da chi non ha scritto il testo, e quando stai lanciando sempre lo stesso lavoratore con le stesse istruzioni (subagenti, panoramica delle funzioni, verificato a novembre 2026). Quando no. Per un botta e risposta o una modifica di un attimo basta la conversazione: un agente parte da zero e deve prima raccogliere le informazioni.

Quanto costa davvero. Niente cifre, ma lo dice Anthropic stessa: ogni agente fa le sue richieste, che pesano sugli stessi limiti d'uso della conversazione (subagenti). A volte è più lento che farlo nella conversazione. E sullo stesso compito, con lo stesso modello o uno più piccolo, ti dà occhi nuovi, non una risposta più intelligente (buone pratiche, verificato a novembre 2026). Quella che tieni libera è la conversazione, non il tuo piano. Il comando /usage serve a vedere quanto pesa (pagina sui costi): non l'abbiamo provato.

Lavoro con più di 30 agenti, divisi in squadre con un coordinatore. Come si mettono in squadra è il passo dopo questo, in un'altra guida di questa serie, in arrivo. Qui si parte da uno.

Cos'è un agente e in cosa è diverso da una skill, da CLAUDE.md e da una chat

Un agente di Claude Code è un file di testo con un nome, una descrizione e delle istruzioni, che lavora a parte, nel suo contesto e con i soli strumenti elencati nel file, e alla fine restituisce un riassunto. Il contesto è la memoria di lavoro di una conversazione: tutto quello che il modello ha davanti in quel momento. Gli strumenti sono le azioni che può fare: leggere un file, scriverne uno, lanciare un comando.

Nella tabella ci sono le quattro cose che si confondono di più, con l'esempio del bar (pagina ufficiale di confronto, subagenti, verificato a novembre 2026).

Se il lavoro è più corto e lo vuoi dentro la conversazione, ti basta una skill per Claude Code: è il passo prima di questo, e lì non la rispieghiamo.

Cosa vede e cosa non vede. Secondo la documentazione un agente all'avvio riceve le sue istruzioni, qualche dato sull'ambiente come la cartella di lavoro, il compito che gli scrive Claude, i tuoi CLAUDE.md, lo stato di git (il registro delle versioni dei file) se lo usi e le skill precaricate. Non riceve la conversazione, né le skill già usate, né i file già letti (subagenti, verificato a novembre 2026). L'abbiamo controllato sul nostro banco di prova, cioè Claude Code vero collegato a un servizio di prova sul nostro computer, leggendo la richiesta che partiva: CLAUDE.md c'era, una regola detta solo in chat no. La conseguenza pratica: quello che incolli in chat può non arrivargli. Mettilo in un file e digli quale.

Non ti fa domande. Lo strumento per farle gli viene tolto sempre, anche se lo elenchi (documentazione, confermato sul banco). Possono comparire solo le richieste di permesso. Per questo nel suo file devi scrivere cosa fa quando manca un dato: se non lo scrivi, decide lui.

Dove vive un agente e cosa serve per usarlo

Il progetto è semplicemente la cartella da cui apri Claude Code: per Rosa, Bar Da Rosa. La cartella in cui metti il file decide dove vale (subagenti, verificato a novembre 2026).

La regola che spiazza: conta da dove apri. Gli agenti di progetto si cercano salendo dalla cartella in cui apri Claude Code, mai scendendo nelle sottocartelle (documentazione). Sul banco, con l'agente in una sottocartella e la sessione nuova aperta sulla cartella sopra, l'agente non è stato caricato e non è partito. Apri la cartella del bar, non quella che la contiene.

Cosa serve. Claude Code, con un account a pagamento (pagina dei piani, verificato a novembre 2026), e un minimo di confidenza con le cartelle. Si installa con le istruzioni della pagina ufficiale. Il terminale è la finestra in cui si scrivono i comandi: su Windows è PowerShell, che trovi nel menu Start. Su Mac è Terminale.

Esiste anche l'app desktop, che usa gli stessi file di configurazione, e dal menu con i tre puntini, Background tasks, mostra il lavoro degli agenti (pagina sull'app desktop, verificato a novembre 2026). Quella pagina però non spiega come si chiama un agente, e noi nell'app non l'abbiamo provato: quindi i modi di usarlo qui sotto li descriviamo per il terminale.

Passo 1 a mano: scegli il lavoro e scrivi il file dell'agente

Scegli il lavoro. Un lavoro solo, lungo o ripetitivo, con un risultato che sai giudicare: la documentazione chiede un compito preciso per ogni agente (subagenti). Se per descriverlo ti serve «e anche», sono due agenti. Rosa sceglie la rilettura delle recensioni dell'anno. Una parrucchiera di Bari sceglierebbe le disdette dell'anno, un idraulico gli interventi del mese, un B&B il controllo dell'annuncio prima di pubblicarlo.

Scrivi l'intestazione. Il file ha due parti. In alto l'intestazione, fra due righe di tre trattini; la prima riga del file deve essere proprio ---. Sono obbligatori solo name e description (documentazione, verificato a novembre 2026). Negli agenti del kit c'è sempre anche tools.

---
name: lettore-recensioni
description: Rilegge tutte le recensioni del bar Da Rosa e dice cosa tornano a lamentare, quante volte e con quali frasi. Da usare per capire di cosa si lamentano i clienti, non per rispondere a una recensione.
tools: Read, Grep, Glob
---

La descrizione dice quando, non solo cosa (documentazione). Le descrizioni occupano contesto, quindi vanno tenute corte.

La riga tools è il limite vero. Non lo è la frase «leggi soltanto» scritta nelle istruzioni: quella è una richiesta. La documentazione lo dice chiaro (buone pratiche, verificato a novembre 2026) e noi l'abbiamo visto da tutti e due i lati. Sul banco, con tools: Read, Grep, Glob, la scrittura e il terminale chiesti apposta hanno risposto No such tool available e nessun file è nato. Invece il modello Haiku a cui abbiamo dato le stesse istruzioni, ma con tutti gli strumenti a disposizione, nell'uscita che hai letto sopra ha usato il terminale, anche se il testo diceva «leggi».

Scrivi le istruzioni. Sotto l'intestazione c'è il corpo, che diventa le istruzioni dell'agente (documentazione). Cinque blocchi bastano: chi è, cosa leggere, i passi, le regole, come consegnare. Il file intero, da copiare, è più sotto nell'assaggio. Questo è il blocco che tutti dimenticano:

- Non puoi fare domande a chi ti ha dato il compito. Se manca un dato, scrivilo in «Da chiedere» e vai avanti con il resto.

Nel corpo niente note per te: sul banco anche i commenti scritti fra i segni di commento dell'HTML arrivano al modello. Le righe che iniziano con il cancelletto, dentro l'intestazione, invece no.

Si può anche chiedere a Claude di crearlo: è uno dei due modi indicati dalla documentazione. Non aspettarti la schermata guidata con /agents: oggi stampa solo un promemoria (elenco dei comandi, verificato a novembre 2026), e sul banco ha scritto The /agents wizard has been removed. Se una guida te la racconta, è ferma a una versione vecchia.

Se non vuoi partire dal foglio bianco, fatti scrivere la bozza da una chat. Tutti i prompt di questa guida li abbiamo provati con il modello Haiku di Claude, su casi italiani inventati: la prova dice com'è il testo che danno, non che il file uscito funzioni in Claude Code, perché quei file non li abbiamo caricati. Questo, alla prima prova, ha aggiunto il terminale sul bar e una percentuale non chiesta sulla parrucchiera di Bari. Corretto il testo, niente terminale e niente calcoli in più; sul bar però ha messo una formula a mano per il giorno della settimana, avvisando lui stesso di controllarla con un calendario. Rileggi sempre il file.

Non sei sicuro che serva un agente? Prima chiedilo. Provato sui due casi: sul bar ha dato l'agente solo a due lavori su cinque (le recensioni dell'anno e i messaggi della settimana). Sulla parrucchiera di Bari ha risposto che nessuno dei cinque lavori ne ha bisogno, che è una risposta utile. Non è infallibile: ha lasciato a mano il controllo del volantino, che è proprio il mestiere di uno degli agenti del kit.

Passo 2 a mano: mettilo nella cartella giusta, fallo caricare e usalo

Prima crei la cartella, poi apri Claude Code. Una sessione non vede una cartella agents nata dopo: lo dice la documentazione, e sul banco era ancora invisibile dopo 8 e dopo 23 secondi (subagenti, verificato a novembre 2026).

Apri PowerShell. Scrivi cd, uno spazio e il percorso del progetto tra virgolette, poi lancia le altre righe. Sostituisci percorso e nome dell'agente con i tuoi.

cd "C:\I miei lavori\Bar Da Rosa"
New-Item -ItemType Directory -Force ".claude\agents"
New-Item -ItemType File ".claude\agents\lettore-recensioni.md"
notepad ".claude\agents\lettore-recensioni.md"

Si apre il Blocco note su un file vuoto che si chiama già nel modo giusto: incolla il testo e salva. Così eviti lettore-recensioni.md.txt, che Claude Code non legge. Le due righe New-Item le abbiamo lanciate davvero il 04/11/2026 su Windows 11 con PowerShell 5.1, in una cartella con spazi nel nome. L'apertura del Blocco note no.

Su Mac e Linux i comandi equivalenti sono questi. Li abbiamo provati solo in Git Bash su Windows, mai su un Mac.

cd "percorso/del/progetto"
mkdir -p ".claude/agents"
touch ".claude/agents/lettore-recensioni.md"

Apri Claude Code nel progetto: dal terminale, stando in quella cartella, scrivi claude. Se ti chiede se ti fidi della cartella, rispondi sì solo se è tua.

Quando serve riaprire. Un file nuovo o cambiato, in una cartella agents che c'era già all'avvio, viene visto entro pochi secondi e vale alla delega successiva (documentazione). Sul banco, subito no e dopo 6 secondi sì, anche per un testo cambiato o un file cancellato. Se invece la cartella agents è nata a sessione aperta, chiudi e riapri: è il consiglio sicuro, anche se sul banco ha funzionato /reload-plugins.

Controlla che lo veda. Scrivi /context: mostra anche gli agenti personalizzati, con la provenienza (pagina sulla configurazione, verificato a novembre 2026). Sul banco, lanciato da riga di comando, ha stampato una tabella «Custom Agents» con i nostri agenti e la scritta «Project». Se /context nella finestra ti mostra altro, chiedi direttamente a Claude quali agenti vede.

Usalo. La tabella dice cosa promette la documentazione, cosa abbiamo letto sul banco e cosa resta aperto (subagenti, verificato a novembre 2026).

Il risultato non si aspetta. Secondo la documentazione un agente lanciato dalla conversazione lavora di norma in background, cioè mentre tu fai altro. Il risultato torna alla conversazione principale, di solito più tardi, come notifica in un turno successivo. Nel terminale, in VS Code e nell'app desktop Claude non può fermarsi ad aspettarlo, salvo spegnere quella modalità con l'impostazione CLAUDE_CODE_FORK_SUBAGENT a 0 (subagenti, verificato a novembre 2026). Non l'abbiamo visto con il modello vero.

Se chiede un permesso, la richiesta compare nella sessione principale con il suo nome, Esc nega quella sola azione, e una risposta che vale oltre quell'azione vale per tutta la sessione (stessa pagina). Sul banco, in un lancio senza schermata, una scrittura senza permesso è stata rifiutata e nessun file è nato. La domanda sullo schermo non l'abbiamo vista.

Controlla che abbia usato solo i suoi strumenti. Finito il lavoro, per 30 secondi compare /tasks to see subagents: entro quei 30 secondi, in /tasks, Invio apre il suo registro. Lo stesso comando mostra su quale modello gira. Nell'app c'è Background tasks. Il registro di ogni agente è anche un file: ~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl (documentazione, app desktop). /tasks sullo schermo non l'abbiamo provato. Per lettore-recensioni la prova che cerchi è semplice: nessun file nuovo o cambiato nella cartella.

Per toglierlo cancella il suo file. Una sessione lunga col modello vero non l'abbiamo provata, quindi se vuoi essere sicuro aprine una nuova.

Le richieste di prova fattele preparare da questo prompt, da usare su dati finti. Corretto dopo una prima prova con richieste troppo lunghe, sul bar ha dato tre richieste senza nominare l'agente e con parole diverse dalla descrizione, come «Sui commenti di Google del mio locale, cosa non va secondo chi è passato? Dammi i numeri.», e 12 controlli con risposta sì o no. Sulla parrucchiera di Bari ha trovato un buco che non avevamo visto: le regole non dicono cosa fare con una disdetta dell'anno prima.

Se non parte, guarda prima la descrizione, poi la cartella da cui hai aperto. Se il messaggio dice Agent type ... not found, l'agente non è stato caricato: percorso, nome del file e prima riga sono i primi tre posti dove guardare.

Cosa abbiamo provato e cosa no

L'avvio di un agente vero col modello vero, a parole e per nome, non è provato. Il perché è semplice: da terminale il nostro Claude Code non aveva l'accesso, e non siamo andati a cercare credenziali. L'altra strada, quella usata per le skill nella guida precedente, qui non funziona: abbiamo messo un agente in una sottocartella, aperto un suo file nella sessione già aperta su una cartella più in alto, e la risposta è stata Agent type 'sonda-agente' not found. Quindi le prove sono tre, e ognuna dice una cosa sola.

Dove e con cosa. 04/11/2026, Windows 11, Claude Code 2.1.309, Windows PowerShell 5.1 e Git Bash 5.2. La documentazione aperta quel giorno cita versioni più recenti di quella provata: Claude Code cambia spesso, quindi le funzioni possono essere andate avanti.

Resta non provato, oltre all'avvio: la scelta automatica di Claude senza nominare l'agente; @agent-nome fino in fondo; la schermata interattiva, con /tasks, il menu di @ e la domanda di permesso; l'app desktop; Mac e Linux veri. In più, sul banco, non abbiamo provato due campi per chi è già esperto (hooks e mcpServers), e neppure memory con i suoi file.

Quindi: prova tu, sui dati finti, prima di fidarti. Se a parole l'agente non parte, correggi la descrizione o chiedilo con la menzione, e guarda cosa succede. È il primo controllo da fare, e la guida ti dice come.

L'assaggio del kit: un agente del bar Da Rosa, intero

Questo è il file vero del kit, così com'è. L'uscita che hai letto in cima viene dalla versione di prima: l'unica riga cambiata è «Successo una o due volte», che prima diceva «una volta sola» e lasciava senza posto un argomento citato da due recensioni. Rifatta la prova con il modello Haiku sugli stessi dati: stessi tre argomenti, 12 e 7, e sulla granita 7, di cui 2 segnate come incerte. Va in .claude/agents/lettore-recensioni.md, nel progetto, prima di aprire Claude Code. Il bar «Da Rosa», Rosa e le recensioni sono inventati.

A mano parti da un foglio bianco e un agente solo. Nel kit hai cinque agenti interi, ognuno per un caso diverso (leggere, controllare senza modificare, modello piccolo, scrivere un file, usare una skill), più un modello con le note già al posto giusto. Hai anche i dati finti con le loro soluzioni, quindi puoi giudicare il risultato prima di dargli dati veri, cosa che da solo dovresti prepararti. E la lista di controllo contiene le trappole che abbiamo trovato sul banco. Tutto è testo, quindi puoi leggere ogni file prima di usarlo. Il riquadro qui sotto elenca il contenuto e quanto pesa: il kit si scarica dopo la donazione libera.

Domande frequenti sugli agenti di Claude Code

Cosa sono gli agenti di Claude Code?

Sono file di testo con un nome, una descrizione e delle istruzioni, che Claude Code fa lavorare a parte, con i soli strumenti elencati nel file. La documentazione li chiama subagenti. Un agente non vede la tua conversazione: riceve il compito che gli scrive Claude e alla fine riporta un riassunto alla conversazione principale. Serve per i lavori lunghi di cui ti interessa solo il risultato.

Meglio un agente o una skill?

Dipende da dove vuoi che avvenga il lavoro. La skill dice come si fa una cosa dentro la conversazione, e tu segui ogni passaggio. L'agente fa un lavoro lungo fuori dalla conversazione, oppure lavora con meno strumenti, per esempio un controllo che non deve poter modificare niente. Si possono anche combinare: un agente può caricare una skill all'avvio.

Un agente di Claude Code può modificare i miei file?

Sì, se ha gli strumenti per farlo. Se nel file manca la riga tools ha tutti gli strumenti disponibili, compreso il terminale. Con tools: Read, Grep, Glob può solo leggere e cercare: nella nostra prova su Windows, con Claude Code collegato a un servizio di prova, la scrittura è stata rifiutata e nessun file è nato. Con Bash o PowerShell invece può scrivere file, anche se non ha Write.

Che modello usa un agente e come lo cambio?

Se nel file non c'è la riga model, di norma usa il modello della conversazione. Per cambiarlo scrivi nell'intestazione model: haiku, oppure sonnet, opus, fable o inherit, come indica la documentazione di Claude Code, verificata a novembre 2026. Attenzione: un nome sbagliato non dà errore quando il file viene caricato. Per i lavori semplici la documentazione consiglia haiku.

Un agente può chiamarne un altro?

Sì, secondo la documentazione di Claude Code, verificata a novembre 2026: fino a tre livelli sotto la conversazione. Per impedirlo a un agente basta non mettere Agent nella sua riga tools, e nella nostra prova, con Claude Code collegato a un servizio di prova, senza quella voce lo strumento non c'è. Per chi inizia conviene partire da un agente solo.

Si possono creare agenti gratis?

Il file è testo e lo scrivi tu, quindi quello non costa niente. Claude Code invece non è nel piano gratuito di Claude: serve un account a pagamento, e ogni agente fa le sue richieste, che pesano sui limiti del tuo piano. Per i piani guarda la pagina ufficiale di Claude. Verificato a novembre 2026.

Le fonti delle risposte: i subagenti, la panoramica delle funzioni, i modelli, l'installazione e i piani, tutte aperte a novembre 2026.

Da fare oggi: pensa all'ultima volta che hai incollato in chat una montagna di testo per farti dire due cose. Scrivi in tre righe qual era il lavoro, quale file serviva e come volevi il risultato, poi mettile nel prompt del passo 1. Se ti blocchi, scrivi a Fabio: raccontagli il lavoro e incolla il file che è uscito.