Claude Code: la guida completa per usarlo davvero bene

Claude Code è lo strumento di agentic coding di Anthropic, e in Lasting Dynamics lo usiamo ogni giorno su progetti reali per clienti reali. Questa guida è quella che avremmo voluto trovare noi: non un elenco di feature, ma come si usa bene — configurazione, workflow, costi, e gli errori che vediamo fare a quasi tutti all'inizio.

Cos'è Claude Code (e perché è diverso)

Claude Code è un agente di programmazione. La differenza rispetto ai completamenti in editor è di architettura, non di grado: tu descrivi un risultato ("aggiungi il rate limiting a questo endpoint e coprilo di test") e l'agente pianifica, legge il codebase, modifica i file, esegue comandi e test, e itera finché non ha finito o non è bloccato. Tu dirigi e fai review, come faresti con un collega.

Nasce come CLI da terminale — ed è lì che dà il meglio — ma oggi gira anche come estensione per VS Code e JetBrains, come app desktop e sul web. Sotto ci sono i modelli Claude di Anthropic; sopra, un sistema di estensioni fatto di MCP server, hooks, skills e subagenti.

Il punto chiave da capire subito: Claude Code è potente in proporzione a quanto sei preciso tu. È un moltiplicatore del tuo giudizio da ingegnere, non un sostituto. Tienilo a mente per tutta la guida, perché ogni sezione torna lì.

Installazione e primo avvio

Da terminale:

npm install -g @anthropic-ai/claude-code

oppure con l'installer nativo indicato nella documentazione ufficiale di Anthropic. Poi, dentro la cartella di un progetto:

claude

Al primo avvio ti autentichi con un account Claude (abbonamento Pro o Max) oppure con una API key. Da lì in poi parli con l'agente in linguaggio naturale, in italiano o in inglese.

I comandi che userai da subito:

• /init — analizza il progetto e genera un primo CLAUDE.md (ci arriviamo tra un attimo)
• /help — l'elenco dei comandi
• /clear — azzera il contesto quando cambi argomento
• claude --continue / --resume — riprendi una sessione precedente

CLAUDE.md: il file che cambia tutto

Se porti via una sola cosa da questa guida, che sia questa: il progetto deve avere un CLAUDE.md curato.

È un file markdown nella root del repository che Claude Code legge all'avvio di ogni sessione. Dentro ci metti quello che diresti a una persona brava appena entrata nel team:

# Progetto X

## Comandi
- build: `npm run build`
- test: `npm test`
- lint: `npm run lint`

## Convenzioni
- TypeScript strict, niente `any`
- I componenti UI vivono in src/components/ui
- Le migrazioni al DB si fanno SOLO in prisma/migrations
- Ogni fix di bug parte da un test che riproduce il bug

## Confini
- Non toccare src/legacy/** senza chiederlo
- Niente nuove dipendenze senza motivazione

La differenza tra un progetto con un buon CLAUDE.md e uno senza è la differenza tra istruire un collega una volta e ripetergli tutto ogni mattina. Nel nostro team il CLAUDE.md è mantenuto come codice: va in review, si aggiorna quando cambiano le convenzioni, e quando l'agente sbaglia qualcosa di sistematico la prima domanda è "manca una riga al CLAUDE.md?".

Permessi: la parte che nessuno legge e tutti dovrebbero leggere

Claude Code chiede il permesso prima di azioni potenzialmente rischiose: eseguire certi comandi, scrivere fuori dal progetto, chiamare strumenti esterni. All'inizio le richieste sembrano attrito; resisti alla tentazione di approvare tutto alla cieca.

L'approccio che insegniamo:

1. Leggi cosa sta per fare, non solo il nome del comando.
2. Autorizza in modo permanente solo ciò che è davvero sempre sicuro (il test runner, il linter, il build).
3. Lascia il resto su richiesta. Il prompt di permesso è un checkpoint di review gratuito: usalo.

Su un repository con dati veri, la disciplina sui permessi non è paranoia: è il motivo per cui puoi dare all'agente compiti seri dormendo tranquillo.

Il workflow che usiamo in produzione

Dopo mesi di uso quotidiano sui progetti clienti, il nostro flusso standard è questo:

1. Brief, non prompt. Un compito ben posto ha contesto, vincoli e una definizione di fatto: "Aggiungi la validazione dell'input all'endpoint /apply. Usa zod come nel resto del progetto. Un input invalido risponde 400 con lo stesso formato errore degli altri endpoint. Aggiungi i test e falli passare." Questo brief batte qualsiasi prompt "furbo".

2. Prima il piano, poi il codice. Su qualsiasi task non banale, chiedi il piano prima dell'esecuzione (la modalità plan serve esattamente a questo). Bocciare un piano sbagliato costa dieci secondi; bocciare un diff sbagliato costa un pomeriggio.

3. Incrementi verificabili. Un obiettivo grande come "migra il modulo" diventa "migra questo file, esegui i suoi test, fermati". L'agente lavora meglio, e tu fai review di pezzi che stanno in testa.

4. I test sono il guinzaglio. Un agente che può verificare il proprio lavoro converge; uno che non può, tira a indovinare con sicurezza. Se il progetto ha test deboli, la prima cosa da far fare a Claude Code è scrivere test, non feature.

5. Git come rete di sicurezza. Commit piccoli e frequenti. Claude Code usa git benissimo — sfruttalo: ogni incremento verificato è un commit, e tornare indietro non fa mai paura.

6. Review vera, sempre. Ogni riga che l'agente produce è tua: la firmi tu, la mantieni tu. "L'ha scritto l'AI" non è una frase che esiste in un team serio.

MCP, skills, hooks e subagenti

Quando i fondamentali funzionano, il livello successivo è l'estensibilità:

• MCP (Model Context Protocol) collega Claude Code a strumenti esterni: il database, il browser, sistemi di ticketing, API interne. Si aggiungono con claude mcp add. È il modo giusto per dare all'agente accesso a ciò che serve al tuo progetto.
• Skills — procedure riusabili che carichi nel progetto (o nel tuo profilo) e richiami quando servono: il runbook del deploy, la checklist di review, il flusso di release.
• Hooks — comandi che scattano automaticamente su certi eventi (per esempio: lint dopo ogni modifica). Trasformano le convenzioni in vincoli che l'agente non può dimenticare.
• Subagenti — agenti secondari con un compito circoscritto (esplorare il codebase, fare una ricerca) che lavorano in parallelo e riportano il risultato, tenendo pulito il contesto principale.

Il consiglio onesto: non partire da qui. Il 90% del valore sta in un buon CLAUDE.md, brief precisi e test affidabili. L'estensibilità moltiplica un flusso che funziona; non ripara un flusso che non funziona.

Quanto costa

Claude Code è incluso negli abbonamenti Claude (Pro per uso normale, Max per uso intenso) oppure va a consumo con API key. Le sessioni agentiche lunghe su codebase grandi consumano token veri: per un uso quotidiano da professionista, l'abbonamento è quasi sempre la scelta razionale.

Il costo di cui nessuno parla è un altro: il tuo tempo di review. Uno strumento che genera codice più in fretta di quanto tu riesca a rivederlo responsabilmente non ti ha reso più veloce — ha spostato il collo di bottiglia e l'ha nascosto. Metti in conto il tempo di review, non solo i token.

Gli errori che vediamo fare a tutti

1. Prompt vaghi su codebase grandi. L'agente prenderà decisioni ragionevoli che non volevi, in scala. La cura è la precisione, non la sfiducia.
2. Sessioni infinite senza /clear. Il contesto si riempie di rumore e la qualità cala. Cambio argomento = contesto nuovo.
3. Approvare tutto per fare prima. Vedi la sezione permessi. Il giorno che serve, quel checkpoint vale la giornata.
4. Usarlo per non capire. Il codice che non capisci oggi è il bug che non sai riparare tra tre mesi. Se l'agente produce qualcosa che non ti è chiaro, la mossa giusta è chiedergli di spiegartelo — lo fa benissimo — non accettare e andare avanti.
5. Giudicarlo su un tentativo da cinque minuti. Come ogni strumento professionale, il valore arriva con la pratica deliberata: configurazione, workflow, abitudini.

Come si impara davvero

Puoi imparare i comandi di Claude Code in un pomeriggio. Quello che non si impara in un pomeriggio è il giudizio che lo rende potente: capire quando un diff plausibile è sbagliato, come si specifica un lavoro con precisione, cosa va testato, che aspetto ha una buona architettura. Gli strumenti AI hanno reso più facile che mai produrre codice che non si capisce — e hanno reso enormemente più produttivi gli ingegneri che capiscono.

È esattamente la scommessa della Lasting Dynamics Academy: da dieci anni formiamo gli ingegneri che poi assumiamo, e oggi l'uso concreto di agentic AI e LLM è parte del curriculum — insegnato sopra i fondamentali (architetture, design pattern, testing) con task reali e una review settimanale col mentore. È gratuita, full remote, a numero chiuso, e chi completa il percorso riceve un'offerta di lavoro. Se questa guida ti è sembrata il modo giusto di pensare, è esattamente così che insegniamo nel programma di agentic coding — la prossima coorte è aperta.

Domande frequenti

Claude Code funziona anche in italiano? Sì: puoi dargli istruzioni in italiano e risponde in italiano. Il codice, i commenti e le convenzioni seguono quello che stabilisci tu (o il tuo CLAUDE.md).

Meglio Claude Code o Cursor? Domanda sbagliata: fanno cose diverse e molti nostri ingegneri li usano entrambi nello stesso giorno. La regola pratica: se sai descrivere il risultato ma non le modifiche, Claude Code; se le modifiche le vedi già in testa, l'editor. Ne abbiamo scritto un confronto onesto e dettagliato (in inglese): Claude Code vs Cursor.

Serve saper programmare per usarlo? Per giocare, no. Per lavorare, sì — e più sei bravo, più vale. Senza il giudizio per fare review dell'output, stai accumulando codice che non sai mantenere.

Posso usarlo su un codebase legacy enorme? È uno dei suoi punti di forza: esplorazione del codebase, refactoring lunghi, migrazioni. Vale doppio la regola degli incrementi verificabili — e serve una suite di test di cui fidarsi.

Quanto ci vuole per diventare produttivi? Con un CLAUDE.md fatto bene e i workflow di questa guida, giorni. La padronanza vera — quella che moltiplica — cresce con la pratica deliberata e con la review di qualcuno più esperto. È il motivo per cui l'academy funziona.