Claude Code: guida pratica
Usare un agente di coding da riga di comando senza perdere il controllo
Un corso testuale completo su Claude Code, l'agente di sviluppo da terminale: cosa vede del tuo progetto, come si installa, come si scrivono istruzioni che segue davvero, come si impostano permessi e sicurezza, come si pianifica un compito grande, come si estende con comandi, hook e server MCP, come si lavora in parallelo e come lo si porta in CI e in un team. Il filo conduttore è uno solo: ottenere codice che passeresti in revisione, sapendo dove l'agente sbaglia in modo prevedibile. Al superamento della prova finale viene emesso un attestato di frequenza con Open Badge verificabile.
- Spiegare in cosa un agente di coding differisce dal completamento automatico e da un assistente conversazionale
- Capire cosa entra nel contesto di Claude Code e gestirlo con /context, /clear e /compact
- Installare Claude Code, avviarlo su un progetto e scrivere un CLAUDE.md breve, specifico e verificabile
- Configurare modalità e regole di permesso partendo dalla distinzione fra operazioni reversibili e irreversibili
- Usare la plan mode per scomporre un compito grande in passi verificabili
- Estendere l'agente con skill, hook, server MCP e subagenti, scegliendo fra istruzioni e meccanismi imposti
- Impostare un uso headless e in CI con permessi minimi, limiti espliciti e revisione umana
Prerequisiti
- Uso quotidiano del terminale e di git: clone, branch, commit, diff
- Esperienza di sviluppo in almeno un linguaggio: gli esempi usano strumenti JavaScript, ma i concetti valgono per qualsiasi stack
- Per leggere il corso e sostenere la prova non serve altro; per metterlo in pratica serve un account Claude con accesso a Claude Code, che è a pagamento
Capitolo 01
Cos'è un agente di coding
Chi ha già usato un assistente di programmazione ne conosce di solito due forme. La prima è il completamento automatico: mentre scrivi, l'editor propone le righe successive nel file che hai aperto, e tu accetti o rifiuti un suggerimento alla volta. La seconda è l'assistente conversazionale: incolli un pezzo di codice in una chat, ricevi una risposta testuale, e sta a te riportarla nel progetto, eseguirla e scoprire se funziona. In entrambi i casi il lavoro vero — decidere quali file toccare, lanciare i comandi, verificare il risultato — resta interamente nelle tue mani.
Un agente di coding come Claude Code cambia la divisione dei compiti. Non gli chiedi una riga o una risposta: gli affidi un obiettivo, e lui lavora in un ciclo che la documentazione ufficiale descrive in tre fasi che si intrecciano — raccogliere contesto, agire, verificare il risultato. Per farlo usa strumenti: legge e cerca nei file, li modifica, esegue comandi nel terminale, consulta il web. Ogni risultato di uno strumento è un'informazione nuova che orienta il passo successivo. Se gli chiedi di sistemare i test che falliscono, tipicamente lancerà la suite, leggerà l'errore, cercherà i file coinvolti, li modificherà e rilancerà i test per controllare. Non vede solo il file aperto nell'editor, ma l'intero progetto in cui lo hai avviato.
Conviene distinguere i due pezzi che compongono l'agente. Il modello è la parte che ragiona: capisce il codice, decide cosa fare, scrive le modifiche. Claude Code è lo strato attorno al modello — la documentazione lo chiama harness — che fornisce gli strumenti, gestisce cosa entra nel contesto e applica le regole che configuri, come i permessi. La distinzione tornerà in tutto il corso: alcune cose le decide il modello e possono variare da una volta all'altra, altre le impone l'harness e succedono sempre.
Vale la pena dire anche cosa non è. Non è un oracolo: produce codice plausibile con la stessa sicurezza sia quando ha ragione sia quando sbaglia. Non ricorda le sessioni precedenti: ogni sessione nuova parte con un contesto vuoto, salvo le istruzioni persistenti che vedremo nel capitolo su CLAUDE.md e le note che Claude Code può salvare da sé (la cosiddetta auto memory). Non è deterministico: la stessa richiesta, ripetuta, può seguire percorsi diversi. E non sostituisce la revisione: sposta il tuo lavoro dallo scrivere ogni riga al definire bene l'obiettivo e al controllare il risultato.
Restano due cose da sapere prima di cominciare. La prima è che tu fai parte del ciclo: puoi interrompere l'agente in qualsiasi momento con Esc, oppure scrivere una correzione mentre lavora, e lui ne terrà conto prima del passo successivo. La seconda è che Claude Code non vive solo nel terminale: esiste come estensione per VS Code e per gli IDE JetBrains, come app desktop e sul web, e può girare nelle pipeline di CI. Il ciclo e gli strumenti sono gli stessi ovunque; questo corso usa il terminale perché è la forma in cui ogni meccanismo è più visibile.
Capitolo 02
Cosa vede l'agente del tuo progetto
Un agente di coding non ha davanti l'intero repository come lo avresti tu. All'avvio di una sessione Claude Code carica alcune cose da sé — le proprie istruzioni di sistema, i file CLAUDE.md, lo stato di git (ramo corrente, modifiche non committate, commit recenti), i nomi degli strumenti disponibili — e da lì in avanti legge i file che decide di leggere, quando decide di leggerli. Tutto ciò che legge, ogni output di comando e ogni messaggio della conversazione finisce nella finestra di contesto, che ha un limite. La qualità del risultato nasce qui: se l'agente non ha letto il file giusto, produrrà codice plausibile ma sbagliato.
Questo spiega un comportamento che disorienta chi inizia: l'agente reinventa una funzione che esiste già, oppure introduce una libreria quando il progetto ne usa un'altra per lo stesso scopo. Non è ignoranza del modello, è contesto mancante. La differenza è sostanziale perché suggerisce la soluzione: dargli i riferimenti giusti invece di sperare che indovini. In pratica significa nominare il file o la cartella da cui partire, descrivere il sintomo invece della soluzione presunta, e dire cosa significa «risolto». Se hai già ciò che serve, passalo direttamente: con @ seguito da un percorso includi un file nel messaggio, puoi incollare lo screenshot di un errore, e puoi mandargli l'output di un comando dalla shell, per esempio con cat error.log | claude -p 'cosa sta succedendo?'.
I progetti che funzionano bene con gli agenti hanno una caratteristica in comune: sono navigabili. Nomi di file coerenti, struttura prevedibile, convenzioni scritte da qualche parte invece che nella testa del team. Sono le stesse proprietà che rendono un progetto comprensibile a un collega nuovo — l'agente amplifica un problema che esisteva già. Claude legge il codice molto bene da solo, e ne ricava struttura, convenzioni e framework di test; quello che non può trovare è ciò che nel repository non è mai entrato: una decisione presa in riunione, una procedura di deploy che vive nella testa di una persona, la variabile d'ambiente che serve ai test di integrazione.
La finestra di contesto si riempie man mano che la sessione va avanti. Quando si avvicina al limite, Claude Code compatta la conversazione in un riassunto: le richieste e i frammenti di codice importanti sopravvivono, ma istruzioni dettagliate date all'inizio possono perdersi. Per questo le regole che devono valere sempre vanno in CLAUDE.md, che viene ricaricato dal disco, e non affidate alla memoria della conversazione. Le finestre dei modelli attuali sono ampie e restare senza spazio è diventato meno frequente, ma un contesto pieno di lavoro vecchio ha comunque due costi: diluisce l'attenzione su ciò che conta adesso, e viene rispedito — e pagato — a ogni nuovo messaggio.
/context
/compact focus on the API changes and the test commands
/clear/context mostra cosa sta occupando spazio e conferma quali file di istruzioni sono stati caricati. /compact riassume subito la conversazione e accetta un'indicazione su cosa conservare, utile prima di cominciare un compito lungo. /clear riparte da zero ed è la scelta giusta quando passi a un lavoro non collegato: il compito successivo non si porta dietro la storia del precedente. Ricorda infine che le sessioni sono indipendenti: una sessione nuova non sa nulla delle precedenti, a meno che tu non ne riprenda una con claude --continue, che riapre l'ultima conversazione nella cartella corrente, o con claude --resume, che permette di sceglierla.
Capitolo 03
Installazione, primo avvio e primi comandi
Per usare Claude Code servono tre cose: un terminale, un progetto su cui lavorare e un account che dia accesso ai modelli. L'ultimo punto va chiarito subito, perché genera equivoci: questo corso è gratuito, lo strumento no. Claude Code richiede un abbonamento Claude a pagamento, un account sulla Claude Console con credito per le API, oppure l'accesso tramite uno dei provider cloud supportati. Piani e prezzi cambiano: verificali sulle pagine ufficiali prima di scegliere.
Il metodo consigliato dalla documentazione è l'installer nativo. Su macOS, Linux e WSL è un'unica riga; su Windows c'è l'equivalente per PowerShell. In alternativa esistono Homebrew, WinGet, i gestori di pacchetti delle principali distribuzioni Linux e npm. La differenza pratica riguarda gli aggiornamenti: l'installazione nativa si aggiorna da sola in background, quelle con Homebrew e WinGet vanno aggiornate a mano. Con npm, la documentazione raccomanda esplicitamente di non usare sudo.
# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash
# Windows PowerShell
irm https://claude.ai/install.ps1 | iex
# check the installation (open a new terminal first)
claude --versionUna nota da professionisti: la prima riga scarica uno script e lo esegue. È la procedura ufficiale, ma l'abitudine giusta resta controllare l'indirizzo esatto sulla documentazione invece di copiarlo da un tutorial qualunque — compreso questo. Se dopo l'installazione la shell non trova il comando claude, la cartella di installazione non è ancora nel PATH: apri un nuovo terminale, e se non basta claude doctor e la pagina sui problemi di installazione aiutano a capire perché.
Il primo avvio si fa dalla cartella del progetto: ti sposti con cd e lanci claude. Alla prima esecuzione ti viene chiesto di autenticarti nel browser. Se apri Claude Code in una cartella che non hai mai usato compare anche la finestra di fiducia (workspace trust): leggila, perché da quella scelta dipende se parte della configurazione presente nel repository — regole di permesso, hook — entra in gioco, e i server MCP del progetto hanno una loro approvazione separata. Su un progetto clonato da una fonte che non conosci, è il momento di guardare cosa contiene la cartella .claude prima di accettare.
Per orientarti comincia con domande che non modificano niente: cosa fa questo progetto, dov'è il punto di ingresso, com'è organizzata la struttura delle cartelle. Poi i comandi che userai ogni giorno. Dentro la sessione, quelli che iniziano con / controllano Claude Code stesso: /help li elenca, /init genera un primo CLAUDE.md, /clear e /compact gestiscono il contesto, /permissions mostra le regole attive, /usage riporta consumi e limiti, /rewind torna a un punto precedente. Un messaggio che inizia con ! esegue direttamente un comando di shell e ne aggiunge l'output alla conversazione. Shift+Tab cambia la modalità dei permessi, Esc interrompe. Dalla shell, claude seguito da una richiesta tra virgolette apre una sessione con quel compito, mentre claude -p esegue una richiesta singola e termina. Il primo compito vero sceglilo piccolo e reversibile, in un repository git con lo stato pulito: così ogni modifica dell'agente è visibile con git diff e annullabile con un comando. Non è prudenza eccessiva: è il modo più rapido per imparare come ragiona l'agente sul tuo codice, prima di affidargli qualcosa che conta.
Capitolo 04
CLAUDE.md: istruzioni di progetto che funzionano
All'avvio di ogni sessione Claude Code legge i file CLAUDE.md e li mette nel contesto. È il posto dove scrivere ciò che un collega nuovo dovrebbe sapere prima di toccare il codice e che non può ricavare leggendolo. I file possono stare in più posizioni, con ambiti diversi: CLAUDE.md (oppure .claude/CLAUDE.md) nella radice del progetto è condiviso con il team tramite git; ~/.claude/CLAUDE.md contiene le tue preferenze personali per tutti i progetti; CLAUDE.local.md nella radice del progetto è per le note personali su quel progetto, e va escluso dal versionamento. Un'organizzazione può distribuire anche un file gestito centralmente. I file non si sovrascrivono a vicenda: vengono concatenati, dal più generale al più specifico. Se il repository ha già un AGENTS.md scritto per altri agenti, Claude Code può leggere quello.
Non serve partire da un foglio bianco: /init analizza il codice e genera una prima versione con i comandi di build e di test e le convenzioni che riesce a scoprire. Da lì il lavoro consiste soprattutto nel togliere. L'errore più comune è riempire il file di buoni propositi generici, del tipo «scrivi codice pulito e ben testato»: non producono alcun effetto misurabile. Il secondo errore, più sottile, è descrivere ciò che l'agente scopre da solo — l'architettura, la struttura delle cartelle — che costa contesto in ogni sessione senza aggiungere informazioni.
Le istruzioni utili sono specifiche e verificabili. La documentazione ufficiale propone un test semplice prima di scrivere una riga: l'agente potrebbe trovarlo leggendo il codice? E andrebbe davvero a cercarlo? Se la risposta è sì a entrambe le domande, la riga non serve. Restano i comandi esatti per verificare il lavoro — test, typecheck, lint, come lanciare un singolo file di test —, i punti in cui il codice inganna, come un modulo vecchio ancora in uso da non prendere a modello, le decisioni prese fuori dal repository, e tutto ciò che hai dovuto correggere due volte.
# Commands
- Install: pnpm install
- Run one test file: pnpm vitest run path/to/file.test.ts
- Typecheck: pnpm tsc --noEmit
# Conventions
- Use the error helpers in src/lib/errors.ts, never throw raw strings
- src/legacy/ is still live: do not copy its patterns into new code
# Gotchas
- Integration tests need DATABASE_URL, see .env.exampleVale la regola opposta a quella della documentazione tradizionale: poche righe su decisioni non ovvie battono pagine ridondanti. La documentazione indica come obiettivo di restare sotto le 200 righe per file, perché ogni riga consuma contesto in ogni sessione e un file lungo riduce l'aderenza alle istruzioni. Quando una parte riguarda solo un'area del codice, si può spostare in un file della cartella .claude/rules/, limitato a certi percorsi, che si carica solo quando l'agente lavora su quei file; quando diventa una procedura in più passi, è meglio farne uno skill, come vedremo nel capitolo 7. Gli import con la sintassi @percorso aiutano a organizzare, ma non riducono il costo: i file importati si caricano insieme a quello che li importa.
Due cose, infine, da non dimenticare. CLAUDE.md è contesto, non configurazione imposta: l'agente lo segue quasi sempre, ma resta una sua decisione. Se una regola non ammette eccezioni — non leggere mai .env, non toccare la cartella delle migrazioni — scriverla in maiuscolo o aggiungere «IMPORTANTE» non risolve: va trasformata in una regola di permesso o in un hook, che vedremo nei capitoli 5 e 7. E le istruzioni vanno trattate come codice: stanno in git, si revisionano, si aggiornano quando cambiano le convenzioni. Un file obsoleto è peggio di nessun file, perché l'agente lo segue con la stessa diligenza.
Capitolo 05
Permessi e sicurezza operativa
Un agente da terminale esegue comandi: installa pacchetti, modifica file, lancia test, può fare commit. Questa è la sua utilità ed è anche il suo rischio. La domanda giusta non è «posso fidarmi?» ma «quale danno posso permettermi se sbaglia?». La distinzione pratica è fra operazioni reversibili e irreversibili. Modificare un file tracciato da git è reversibile: puoi sempre tornare indietro. Cancellare file non tracciati, riscrivere la cronologia, fare push su un ramo condiviso, toccare un database o un ambiente di produzione non lo sono. La prima categoria può procedere senza chiedere; la seconda richiede una conferma esplicita, sempre. Claude Code aiuta sul lato reversibile. Prima di modificare un file con i propri strumenti ne salva un'istantanea, un checkpoint: premendo Esc due volte, o con /rewind, puoi riportare il codice, la conversazione o entrambi a un punto precedente. Ma i checkpoint hanno confini precisi: non coprono i file cambiati da comandi di shell, e non possono annullare nulla che sia uscito dalla macchina — una query su un database, una chiamata a un'API, un deploy. Non sostituiscono git: lo affiancano.
Il secondo meccanismo sono le modalità di permesso, che stabiliscono cosa l'agente può fare senza chiedere. In modalità Manual (il valore di configurazione è default) le letture sono libere e quasi ogni modifica o comando chiede conferma. acceptEdits approva da sola le modifiche ai file e alcuni comandi comuni sul filesystem dentro la cartella di lavoro. plan permette di esplorare ma non di modificare il codice (capitolo 6). auto affida la valutazione delle azioni a un secondo modello, un classificatore, che blocca quelle che giudica rischiose. dontAsk nega tutto ciò che non è stato pre-approvato, ed è pensata per CI e script. bypassPermissions salta i controlli, e la documentazione la indica solo per container e macchine virtuali isolate. Shift+Tab passa da una modalità all'altra; quale sia quella di partenza dipende da versione e configurazione, ed è cambiata nel tempo: verificalo sulla documentazione.
Sopra le modalità si aggiungono le regole: allow (procedi senza chiedere), ask (chiedi sempre), deny (vietato). Si scrivono nei file di impostazioni — .claude/settings.json per il team, .claude/settings.local.json per te — e si gestiscono con /permissions. L'ordine di valutazione è deny, poi ask, poi allow: un deny non può essere scavalcato da un allow più specifico, e vale in ogni modalità, compresa bypassPermissions. La differenza con CLAUDE.md è sostanziale: le regole le applica Claude Code, non il modello. Per questo i «mai» vanno qui e non nelle istruzioni; anche la modalità auto, essendo il giudizio di un modello, può sbagliare.
{
"permissions": {
"allow": [
"Bash(npm run test *)",
"Bash(npm run lint)"
],
"ask": [
"Bash(git push *)"
],
"deny": [
"Read(./.env)",
"Read(./secrets/**)"
]
}
}Le regole hanno bordi da conoscere: corrispondono alle chiamate degli strumenti, non all'intenzione. Il deny su Read(./.env) ferma anche cat .env, perché Claude Code riconosce i comandi comuni di lettura, ma non uno script che apre il file per conto suo. Per un limite a livello di sistema operativo esiste la sandbox per i comandi di shell, che si attiva con /sandbox su macOS, Linux e WSL2.
Resta il rischio che non dipende da te. L'agente legge contenuti che non hai scritto — issue, commenti, pagine web, documentazione delle dipendenze, risposte di server esterni — e un testo malevolo può contenere istruzioni pensate per manipolarlo: è la prompt injection. Claude Code ha difese, per esempio non approva in automatico i comandi che scaricano contenuti dalla rete come curl, e chiede fiducia esplicita prima di usare la configurazione di un repository sconosciuto. Ma nessuna difesa è completa, ed è il motivo per cui le operazioni distruttive non dovrebbero mai essere automatiche, per quanto affidabile sembri l'agente nella pratica quotidiana.
Capitolo 06
Pianificare prima di scrivere: la plan mode
Davanti a un compito grande — una migrazione, una funzionalità che attraversa più moduli, un refactoring — l'agente tende a fare quello che fa sempre: cominciare. Il problema è che un'ipotesi sbagliata scoperta dopo venti file modificati costa molto più della stessa ipotesi discussa prima di scrivere una riga. Pianificare prima di scrivere non è burocrazia: è spostare la correzione degli errori nel punto in cui costa meno.
La plan mode serve esattamente a questo. In questa modalità Claude legge i file, esegue comandi per esplorare e scrive un piano, ma non modifica il codice sorgente finché non lo approvi. Ci entri con Shift+Tab, anteponendo /plan a una singola richiesta, oppure avviando la sessione direttamente in questa modalità. Quando il piano è pronto, Claude te lo presenta e chiede come procedere: puoi approvarlo e lasciarlo lavorare con meno conferme, approvarlo ma confermare una per una le modifiche, oppure restare in pianificazione e dire cosa cambiare. Con Ctrl+G apri il piano nel tuo editor e lo correggi direttamente.
# start the whole session in plan mode
claude --permission-mode plan
# inside a session: plan mode for one request
/plan migrate the session store to the new cache APIUn piano si legge come la proposta di un collega, cercando tre cose. Le ipotesi: il piano dà per scontato qualcosa di falso, per esempio che una funzione sia usata in un solo punto? I confini: quali file tocca, e ce ne sono che non dovrebbe toccare? E soprattutto la verifica: per ogni passo, come si saprà che è riuscito? Un passo senza un controllo oggettivo — un test che passa, il typecheck pulito, una build che termina — è un passo il cui esito si scoprirà solo alla fine, insieme a tutti gli altri.
Scomporre il lavoro in passi verificabili ha un effetto pratico immediato: ogni passo diventa un'unità che l'agente può chiudere da solo, eseguendo il controllo e correggendo finché non passa, e che tu puoi rivedere e committare separatamente. Un buon passo lascia il progetto in uno stato funzionante; uno cattivo lo lascia a metà fra due versioni. Se il piano propone «aggiorna tutti i moduli e poi sistema i test», chiedi di rovesciarlo: prima i test che descrivono il comportamento atteso, poi un modulo alla volta, con i test verdi alla fine di ciascuno.
Quando non sai ancora con precisione cosa vuoi, puoi far precedere il piano da un'intervista: chiedi a Claude di farti domande finché non ha elementi sufficienti per scrivere una specifica, e di salvarla in un file. La documentazione suggerisce poi di aprire una sessione nuova per implementarla, così il lavoro parte da un contesto pulito e da una definizione scritta di «finito», che tornerà utile anche in revisione. Per le modifiche piccole e ovvie, invece, la pianificazione esplicita è un costo senza ritorno: una correzione di una riga non ha bisogno di un piano. Un dettaglio utile nelle sessioni lunghe: il piano scritto in plan mode viene ricaricato dal disco anche dopo una compattazione del contesto, quindi resta un riferimento stabile mentre il resto della conversazione viene riassunto.
Capitolo 07
Estendere l'agente: comandi, hook e server MCP
Tutto ciò che hai visto finora si divide in due famiglie, e conviene tenerle distinte. Ci sono istruzioni che il modello legge e decide se seguire: la richiesta, CLAUDE.md, gli skill. E ci sono meccanismi che Claude Code applica sempre, qualunque cosa abbia deciso il modello: le regole di permesso, gli hook. Le estensioni di questo capitolo appartengono all'una o all'altra, e scegliere quella sbagliata è l'errore più comune: una preferenza trasformata in hook diventa un ostacolo, una regola inderogabile lasciata in un testo diventa una speranza.
I comandi personalizzati servono a non riscrivere ogni volta la stessa procedura. Un file Markdown in .claude/commands/, per esempio deploy.md, crea il comando /deploy: il contenuto è il prompt che viene eseguito, e il segnaposto $ARGUMENTS raccoglie ciò che scrivi dopo il nome. Nelle versioni recenti i comandi sono confluiti negli skill: una cartella .claude/skills/deploy/ con un file SKILL.md produce lo stesso comando, e in più permette di affiancare file di supporto e di lasciare che sia l'agente a caricare lo skill quando la sua descrizione corrisponde alla richiesta. I vecchi file in .claude/commands/ continuano a funzionare. Il corpo di uno skill entra nel contesto solo quando viene usato, ed è quindi il posto giusto per le procedure lunghe che appesantirebbero CLAUDE.md. Per uno skill che deve partire solo su tua richiesta, come un deploy, l'opzione disable-model-invocation: true nel frontmatter impedisce all'agente di avviarlo da solo.
Gli hook sono comandi di shell che Claude Code esegue in punti precisi del suo ciclo di vita: prima di usare uno strumento (PreToolUse, che può bloccarlo), dopo averlo usato (PostToolUse), quando l'agente sta per chiudere la risposta (Stop), all'avvio della sessione (SessionStart), quando serve la tua attenzione (Notification), e in diversi altri momenti. Si configurano nei file di impostazioni sotto la chiave hooks, con un matcher che sceglie gli strumenti a cui reagire, e /hooks mostra quelli attivi. Un hook PreToolUse che termina con codice di uscita 2 blocca l'azione e rimanda all'agente il proprio messaggio di errore, così può correggersi; un PostToolUse, invece, arriva quando l'azione è già avvenuta e non può annullarla. Il caso tipico è la formattazione, come nell'esempio qui sotto: invece di scrivere in CLAUDE.md «formatta sempre dopo aver modificato un file», un hook lo fa ogni volta, e non importa più se l'agente se ne ricorda. Due cautele. Gli hook girano con i permessi del tuo utente, quindi quelli presenti in un repository clonato vanno letti prima di accordare fiducia alla cartella. E vanno tenuti pochi: ogni hook prima o poi scatta quando non dovrebbe, e qualcuno deve mantenerlo.
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
}
]
}
]
}
}Il terzo meccanismo collega l'agente a sistemi esterni — issue tracker, database, servizi interni — tramite il Model Context Protocol. Come funziona il protocollo è l'argomento del nostro corso dedicato a MCP; qui conta come lo si usa in Claude Code. Un server si aggiunge con claude mcp add, si gestisce con /mcp dentro la sessione e può avere tre ambiti: locale, il predefinito (solo tu, solo in quel progetto); progetto, nel file .mcp.json da committare per il team; utente (tu, in tutti i progetti). I server di .mcp.json richiedono un'approvazione esplicita nelle sessioni interattive.
# remote server over HTTP, local scope (the default)
claude mcp add --transport http tracker https://mcp.example.com/mcp
# local stdio server, shared with the team through .mcp.json
claude mcp add --scope project --transport stdio db -- npx -y @example/mcp-server
claude mcp listLa regola di sicurezza è quella del capitolo 5: un server che porta contenuti esterni nella conversazione è una porta per la prompt injection, quindi si collegano solo server di cui ti fidi. Skill, hook, subagenti e server MCP possono infine essere raccolti in un plugin, per distribuirli fra più repository o a tutto il team.
Capitolo 08
Lavorare in parallelo: subagenti e worktree
Un subagente è un'istanza separata che lavora in una propria finestra di contesto, con un proprio prompt di sistema e, se lo decidi, con un insieme ridotto di strumenti. Riceve un compito, lo svolge per conto suo e restituisce alla conversazione principale solo un riassunto. Claude Code ne include alcuni predefiniti, fra cui Explore, in sola lettura, per cercare e analizzare il codice, e Plan, usato in plan mode per raccogliere informazioni prima di proporre un piano. Claude delega a un subagente quando il compito corrisponde alla sua descrizione; puoi anche chiederlo esplicitamente, nominandolo nella richiesta o menzionandolo con @.
Un subagente personalizzato è un file Markdown con un frontmatter: name e description sono obbligatori, tools limita gli strumenti, model sceglie il modello. Il corpo del file diventa il suo prompt di sistema. Nella cartella .claude/agents/ del progetto è condiviso con il team via git; in ~/.claude/agents/ è personale e vale in tutti i tuoi progetti. La descrizione conta più di quanto sembri, perché è ciò che Claude legge per decidere quando delegare.
---
name: reviewer
description: Reviews changed files against the spec they were built from. Use after implementing a feature, before opening the PR.
tools: Read, Grep, Glob
---
You are reviewing code you did not write. Compare the changed files
with the spec you are given, check that every requirement is
implemented and tested, and report only gaps that affect correctness.I subagenti servono in quattro situazioni: lavori indipendenti da svolgere in parallelo; output lunghi — una suite di test completa, una ricerca su tutto il repository — che altrimenti resterebbero nel contesto principale per il resto della sessione; una revisione fatta da chi non ha visto il ragionamento che ha prodotto il codice; un compito con meno permessi della sessione principale. Non servono, invece, a ottenere una risposta più intelligente: lo stesso modello sullo stesso compito dà un risultato equivalente. E hanno un costo: ogni subagente invia richieste proprie, che contano sugli stessi limiti di utilizzo, e spesso deve ricostruire un contesto che la conversazione principale aveva già, finendo per essere più lento.
I subagenti lavorano dentro una sessione. Per lavori paralleli più lunghi — una funzionalità da una parte, una correzione dall'altra — bisogna separare anche i file, altrimenti due sessioni modificano la stessa copia e si pestano i piedi. Lo strumento è il worktree di git: una directory di lavoro separata, con il proprio ramo, che condivide la cronologia del repository. claude --worktree nome (o -w) ne crea uno sotto .claude/worktrees/, su un ramo nuovo, e avvia lì la sessione; lo stesso comando con un altro nome, in un secondo terminale, apre una seconda sessione isolata. Anche un subagente può lavorare in un worktree tutto suo, con l'opzione isolation: worktree nel frontmatter.
# keep worktree contents out of the main checkout
echo ".claude/worktrees/" >> .gitignore
# terminal 1
claude --worktree feature-auth
# terminal 2
claude --worktree fix-loginUn worktree è un checkout nuovo: le dipendenze non sono installate e i file ignorati da git, come .env, non ci sono. Un file .worktreeinclude nella radice del repository elenca quelli da copiarvi automaticamente. Il limite vero del parallelismo, però, non è tecnico: ogni sessione parallela produce lavoro da rivedere, e la tua attenzione è la risorsa che finisce per prima. Due sessioni ben verificate valgono più di cinque che non riesci a controllare. Un uso che ripaga quasi sempre è il più semplice: una sessione scrive, un'altra — che non ha visto come il codice è nato — lo rivede.
Capitolo 09
Il flusso di lavoro quotidiano: test, commit piccoli, revisione
L'uso che rende davvero produttivi non è chiedere all'agente di scrivere una funzione, ma affidargli un compito completo e verificabile: «aggiungi i test per questo modulo e assicurati che passino». Un obiettivo con un criterio di successo oggettivo permette all'agente di iterare da solo: modifica, esegue il controllo, legge l'output, corregge, finché il controllo non passa. Senza un controllo, l'agente si ferma quando il lavoro sembra finito — e il collaudatore diventi tu.
Ne discende una conseguenza pratica: i progetti con una buona suite di test traggono dagli agenti un vantaggio molto maggiore. Il test è il contratto che permette di verificare senza rileggere ogni riga; dove i test mancano, la revisione umana torna a essere il collo di bottiglia. Il controllo, comunque, può essere qualunque cosa restituisca un esito leggibile: il codice di uscita di una build, un linter, il typecheck, uno script che confronta un output con un riferimento. Per una correzione di bug, la sequenza più solida è chiedere prima un test che riproduce il problema e fallisce, poi la correzione che lo fa passare. E quando l'agente dichiara di aver finito, chiedi le prove: il comando eseguito e il suo output. «Tutti i test passano», da solo, dice poco.
La richiesta conta quanto il controllo. Una richiesta utile indica da dove partire, descrive il sintomo e dice cosa significa «risolto»: non «sistema il bug del login», ma «il login fallisce dopo la scadenza della sessione; guarda il rinnovo del token in src/auth/, scrivi un test che riproduce il problema, poi correggilo». Se l'agente imbocca una strada sbagliata, fermalo subito con Esc. Se dopo due correzioni è ancora fuori strada, la documentazione suggerisce di non insistere: /clear e una richiesta nuova che incorpori ciò che hai imparato funzionano meglio di una terza correzione in una conversazione già piena di tentativi falliti.
Sul controllo di versione conviene lavorare su un ramo dedicato e in commit piccoli. Non per rigore formale, ma perché rende ogni modifica annullabile in isolamento: se una parte non convince, si scarta quella senza perdere il resto. L'agente sa usare git e può fare commit se glielo chiedi, ma la decisione su cosa entra nella cronologia — e soprattutto su cosa va sul ramo condiviso — resta tua. I checkpoint di Claude Code sono comodi per tornare indietro dentro una sessione, ma non sostituiscono la cronologia di git.
git switch -c fix/session-timeout
# after each verified step
git diff
git add -p
git commit -m "Add failing test for token refresh after timeout"Infine la revisione. Il codice generato va letto con la stessa attenzione di quello di un collega — non di più, per non annullare il guadagno, ma nemmeno di meno. Il rischio specifico è che sia sintatticamente impeccabile e concettualmente sbagliato: proprio la classe di errori che una lettura distratta non intercetta. Aiuta un secondo sguardo indipendente: il comando /code-review rivede le modifiche con un subagente che non ha visto la conversazione, e puoi anche chiedere una revisione mirata contro la specifica scritta in fase di pianificazione. In entrambi i casi chiedi di concentrarsi sulla correttezza e di lasciar perdere lo stile: un revisore a cui si chiede di trovare problemi ne trova sempre qualcuno, e inseguirli tutti produce astrazioni e test inutili.
Capitolo 10
In automazione e in team: CI, configurazione condivisa, limiti e costi
Fuori dalla sessione interattiva, Claude Code si usa con claude -p: esegue una richiesta, stampa il risultato ed esce, con un codice di uscita diverso da zero se l'esecuzione fallisce. È la forma che si inserisce in script, hook di git e pipeline di CI. Nell'uso automatico alcune opzioni diventano quasi obbligatorie: --allowedTools pre-approva gli strumenti necessari, --permission-mode dontAsk rifiuta tutto il resto invece di aspettare una conferma che nessuno darà, --max-turns limita le iterazioni, --output-format json restituisce un oggetto da elaborare. Con --bare l'esecuzione salta il caricamento di hook, skill, server MCP e CLAUDE.md, e si comporta allo stesso modo su ogni macchina; in questa modalità l'autenticazione passa da una chiave API o dalle credenziali del provider cloud, non dal login dell'abbonamento.
claude -p "Run the test suite and fix failing tests. Reply OK or FAIL." \
--allowedTools "Read,Edit,Bash(npm test *)" \
--permission-mode dontAsk \
--max-turns 20 \
--output-format jsonUn dettaglio di sicurezza da non trascurare: senza --bare, un'esecuzione con -p carica gli hook del .claude/settings.json di progetto e collega i server di .mcp.json senza mostrare né la finestra di fiducia né le approvazioni. Su un repository di cui non controlli il contenuto significa eseguire configurazione scritta da altri. Più in generale, prima di lasciare un'esecuzione senza supervisione, la documentazione propone cinque domande: sa cosa significa «finito»? Può verificare il proprio lavoro? Cosa può toccare? Cosa lo ferma? Dove va il risultato, e chi lo approva? L'ultima risposta deve sempre includere una persona, per tutto ciò che non si può annullare.
Per GitHub esiste un'integrazione ufficiale, la GitHub Action anthropics/claude-code-action. Il modo più rapido per configurarla è il comando /install-github-app dentro Claude Code, che guida l'installazione dell'app GitHub e della credenziale come secret del repository, e apre una pull request con il file di workflow da rivedere prima di unirlo. Ci sono due modi d'uso: interattivo, in cui l'agente risponde quando qualcuno lo menziona con @claude in una issue o in una pull request, e automatico, in cui esegue un prompt fisso su un evento, anche a orario. Le chiavi vanno sempre nei secret, mai nel repository; al workflow si danno solo i permessi che servono; e le modifiche proposte si rivedono prima del merge. È documentata anche l'integrazione con GitLab CI/CD.
Nel lavoro di squadra la configurazione si divide per ambito. Nel repository, versionati, stanno CLAUDE.md, .claude/settings.json con permessi e hook comuni, .mcp.json, gli skill e i subagenti di progetto. Le eccezioni personali vanno in .claude/settings.local.json e in CLAUDE.local.md, che restano fuori da git. Sopra tutto, le impostazioni gestite (managed settings) distribuite dall'organizzazione hanno la precedenza e non possono essere scavalcate: sono il posto per le policy di sicurezza. Quando la stessa chiave compare in più file vale quella del livello più alto, mentre liste come le regole di permesso si sommano.
Resta il capitolo dei costi. L'utilizzo si misura in token e varia molto con il modello scelto, la dimensione del codice e le abitudini: sessioni lunghe che accumulano compiti diversi, subagenti, esecuzioni automatiche. /usage mostra i consumi della sessione e, per chi ha un abbonamento, i limiti del piano; la cifra in dollari che riporta è una stima, non la fattura. Le abitudini che riducono la spesa sono le stesse che migliorano i risultati: /clear fra compiti non collegati, CLAUDE.md breve, richieste precise, tetti espliciti alle esecuzioni automatiche. Prezzi, piani, modelli e perfino le impostazioni predefinite cambiano spesso: per tutto ciò che è numerico o di configurazione, il riferimento è la documentazione ufficiale, non un corso — questo compreso.
Domande frequenti
Attestato, badge e accesso al corso
Il corso è gratuito? Ricevo un attestato?
Sì a entrambe. Il corso è gratuito per intero: i contenuti, la prova finale e l'attestato, senza moduli a pagamento e senza che ti venga mai chiesto un metodo di pagamento. Quando superi la prova finale con almeno l'80% di risposte corrette ricevi un Attestato di Frequenza intestato a te, con un codice di verifica, una pagina pubblica che chiunque può consultare per confermarne l'autenticità, il PDF da scaricare e un Open Badge da aggiungere al profilo LinkedIn. Nome ed email ti vengono chiesti solo alla fine, se decidi di sostenere la prova.
Serve un abbonamento a pagamento per seguire il corso?
Per leggerlo e superare la prova no. Per mettere in pratica ciò che spiega sì, perché Claude Code non è gratuito: richiede un abbonamento Claude a pagamento, un account sulla Claude Console con credito per le API oppure l'accesso tramite un provider cloud supportato. Il corso è scritto in modo che ogni concetto sia comprensibile anche senza averlo provato, ma provarlo su un tuo progetto è il modo migliore per fissarlo. Piani e prezzi cambiano: verificali sulle pagine ufficiali di Anthropic.
È un corso ufficiale di Anthropic?
No. È un corso indipendente di Rinoova Academy, non affiliato ad Anthropic né approvato da Anthropic, e l'attestato è emesso da Rinoova. Claude e Claude Code sono prodotti di Anthropic. Ogni dato tecnico del corso è stato controllato sulla documentazione ufficiale di Claude Code, che resta il riferimento per tutto ciò che riguarda comandi, configurazione e comportamento dello strumento.
Quanto dura il corso e come sono calcolate le ore?
Circa due ore. Sono dieci capitoli per circa 5.300 parole di testo tecnico, che a una lettura attenta richiedono poco meno di un'ora, più undici blocchi di comandi e configurazione da provare sul tuo progetto e la prova finale. Non è un corso video: puoi leggerlo alla tua velocità, interromperlo e riprenderlo quando vuoi.
Quali prerequisiti servono?
Il corso è di livello intermedio: dà per scontato che tu sappia usare il terminale e git nel lavoro quotidiano e che abbia esperienza di sviluppo in almeno un linguaggio. Non serve aver mai usato un agente di coding, né conoscere il Model Context Protocol: dove serve, il corso lo introduce e rimanda al corso dedicato.
Cosa succede se non supero la prova finale?
Puoi ripeterla. La soglia è l'80% e le domande coprono tutti i capitoli, quindi se una parte non è chiara conviene tornare al capitolo relativo e rileggerlo prima di riprovare. L'attestato viene emesso solo al superamento, e non viene emesso due volte per lo stesso corso alla stessa persona.
Il corso è aggiornato? Claude Code cambia spesso.
Sì, e proprio per questo è scritto in un modo preciso. I concetti — contesto, istruzioni, permessi, pianificazione, verifica — sono stabili, e su quelli si concentra la prova. I dettagli che cambiano più in fretta, come versioni, prezzi, modelli e impostazioni predefinite, sono lasciati fuori di proposito, e dove un comportamento può evolvere il testo lo dice e rimanda alla documentazione ufficiale. La data dell'ultima revisione è indicata in cima alla pagina.
Continua da qui
Altri corsi Open
Model Context Protocol: Fondamenti
Collegare i modelli linguistici ai dati e agli strumenti aziendali
2 ore · attestato incluso
AI Automation per le PMI
Identificare e automatizzare i processi che costano di più
2 ore · attestato incluso
Prompt Engineering Operativo
Istruzioni che funzionano in produzione, non solo nelle demo
2 ore · attestato incluso