Claude Code: la guida completa in italiano

🧭 Cos'è Claude Code e perché vive nel terminale

Claude Code è la CLI di Anthropic: un agente che apri nella cartella del tuo progetto e a cui parli in linguaggio naturale. La differenza rispetto all'autocompletamento dell'IDE non è la qualità del codice generato — è che l'agente agisce. Legge i file che gli servono, ne modifica più d'uno nello stesso giro, lancia i test, legge l'errore e riprova.

Il terminale non è una scelta estetica. Un agente utile deve poter fare le stesse cose che fai tu quando sviluppi: git, il build, i test, gli script del repo. Vivere dove vivono quei comandi gli evita un livello di traduzione — ed è anche il motivo per cui gira uguale in locale, dentro un container o in CI.

La conseguenza pratica è che il lavoro si sposta: scrivi meno codice a mano e passi più tempo a descrivere l'obiettivo e verificare il risultato. È un buon affare solo se la verifica è veloce e affidabile, ed è il motivo per cui metà di questa guida parla di guardrail invece che di prompt.

• Opera nella cartella del progetto, con i tuoi strumenti e i tuoi script.
• Modifica più file per volta e verifica da solo eseguendo comandi.
• Stessa esperienza in locale, in container e in CI.

⚡ Installazione e primo avvio

Serve Node.js 18 o superiore. L'installazione è un pacchetto globale e il primo claude lanciato dentro una cartella apre la sessione interattiva e chiede l'autenticazione (abbonamento Claude o API key).

Il consiglio che do sempre: la primissima sessione falla su un repo che non ti spaventa perdere, e chiedi qualcosa di innocuo — «spiegami come è organizzato questo progetto». Serve a vedere come l'agente chiede i permessi prima di toccare qualcosa, che è la cosa che conviene capire per prima.

# 1) Installazione globale (serve Node 18+)
npm install -g @anthropic-ai/claude-code

# 2) Entra nella cartella del progetto e apri la sessione
cd ~/progetti/il-mio-repo
claude

# 3) Utile da subito: una domanda sola, senza sessione interattiva
claude -p "riassumi la struttura di questo repo"

🧠 Il modello mentale: contesto, permessi, turno

Tre concetti spiegano quasi tutti i comportamenti che all'inizio sembrano strani.

Il contesto è ciò che l'agente ha sotto gli occhi in questo momento: la conversazione più i file che ha letto. Non è memoria permanente — chiusa la sessione, sparisce. Quasi tutte le frustrazioni del tipo «ma te l'avevo detto» nascono da qui, e si risolvono scrivendo le cose che devono valere sempre in un file (il capitolo dopo).

I permessi decidono cosa può fare senza chiedere. È la manopola tra «mi ferma a ogni riga» e «ha appena fatto una cosa che non volevo». Il turno è l'unità di lavoro: tu chiedi, l'agente lavora quanto serve — anche molti minuti e molti comandi — e poi si ferma. Sapere dove finisce un turno conta, perché è lì che si agganciano i controlli automatici.

• Contesto: volatile, per-sessione. Ciò che deve valere sempre va su file.
• Permessi: cosa l'agente fa da solo e cosa deve chiederti.
• Turno: l'unità di lavoro, e il punto in cui puoi agganciare un gate.

📄 CLAUDE.md — le regole che l'agente legge sempre

CLAUDE.md è un file markdown nella radice del progetto che l'agente carica a ogni sessione. È il posto dove metti quello che ti sei stufato di ripetere: il package manager giusto, lo stile del codice, i comandi per i test, le cose da non toccare mai.

L'errore che ho fatto per primo è stato scriverlo troppo lungo. Ogni riga occupa contesto in tutte le sessioni, comprese quelle dove è irrilevante. Le regole che funzionano sono poche, specifiche e verificabili: «usa yarn, mai npm» funziona; «scrivi codice pulito» no, perché non è controllabile.

Il secondo errore è stato descrivere la struttura del progetto. Quella l'agente la scopre da solo, e appena rinomini una cartella il file mente. Scrivi solo ciò che non è deducibile dal codice: convenzioni, vincoli, decisioni prese. Ne ho parlato più a fondo nel tips dedicato a CLAUDE.md.

# Progetto — regole

## Vincoli non derivabili dal codice
- Package manager: **yarn**, mai npm.
- I test si lanciano con `yarn test` (vitest), non con jest.
- `src/legacy/` è congelato: non modificarlo senza chiedere.

## Stile
- TypeScript ovunque, niente `any`.
- Niente graffe su `if` di una sola istruzione.

⚙️ settings.json e i permessi

Se CLAUDE.md dice all'agente come lavorare, settings.json dice cosa gli è concesso. Vive in .claude/settings.json (condiviso col team, versionato) oppure in ~/.claude/settings.json per le tue preferenze personali.

Il pezzo che cambia davvero la giornata è permissions: una lista di allow per i comandi sicuri e ripetitivi, e una di deny per quelli che non deve toccare mai. Mettere in allow le letture innocue — git status, ls, i test — elimina il grosso delle interruzioni senza rinunciare al controllo dove serve.

Sul deny sono categorico: ci metto i file con i segreti. Non perché mi aspetti un comportamento malevolo, ma perché un .env letto per sbaglio finisce nel contesto, e da lì potenzialmente in un log o in una richiesta. Il dettaglio della configurazione sta nell'articolo su settings.json.

{
  "permissions": {
    "allow": [
      "Bash(git status)",
      "Bash(git diff:*)",
      "Bash(yarn test)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./**/secrets/**)"
    ]
  }
}

🔌 MCP — dare all'agente strumenti esterni

Il Model Context Protocol è lo standard con cui un agente parla con sistemi che non sono il filesystem: un database, un issue tracker, un browser, le tue API interne. Un server MCP espone degli strumenti; Claude Code li vede e li usa quando servono.

È il momento in cui l'agente smette di essere «uno che scrive codice» e diventa «uno che può guardare i dati veri». Un esempio concreto dal mio lavoro: con il server MCP di MongoDB collegato, invece di descrivere a parole com'è fatta una collection, l'agente la interroga.

Il consiglio è di aggiungerli uno alla volta. Ogni server porta in contesto le descrizioni dei suoi strumenti, quindi collegarne dieci «per averli» costa token in ogni sessione e confonde le scelte. Ho scritto sia come aggiungerli a Claude Code e Codex, sia come configurarli in VS Code.

• Un server MCP = un insieme di strumenti esterni esposti all'agente.
• Trasporti tipici: stdio in locale, HTTP per i server remoti.
• Aggiungine uno per volta: ognuno costa contesto in ogni sessione.

🪝 Hook — rendere deterministico ciò che il modello dimentica

Gli hook sono comandi di shell che Claude Code esegue in punti fissi del ciclo di vita: prima di usare uno strumento, dopo una modifica, quando la sessione sta per chiudersi. Non sono prompt: sono codice che gira sempre.

La distinzione è il motivo per cui contano. Una regola scritta in CLAUDE.md è un'istruzione che il modello di solito segue; un hook è un cancello che non può aggirare. Se il formatter deve girare dopo ogni modifica, un PostToolUse lo garantisce al 100%, mentre «ricordati di formattare» ha una percentuale di successo.

I due che uso su ogni progetto: un PreToolUse che blocca la lettura dei file con segreti — la rete di sicurezza sotto il deny dei permessi — e uno Stop che rilancia i test quando l'agente prova a dichiarare finito. Con l'uscita in codice 2 la chiusura viene bloccata e il messaggio di errore torna all'agente come istruzione.

#!/usr/bin/env bash
# .claude/hooks/test-gate.sh — agganciato all'evento Stop.
# Exit 2 = blocca la chiusura del turno; lo stderr torna all'agente.

if ! yarn test --silent 2>&1; then
  echo "Suite rossa: correggi i test prima di dire che hai finito." >&2
  exit 2
fi

🤖 Subagent — delegare senza sporcare il contesto

Un subagent è un agente separato, con il proprio contesto e i propri strumenti, che l'agente principale può incaricare di un compito. Torna indietro solo il risultato: tutto il rumore intermedio — i file letti, i tentativi falliti — resta nel suo contesto e non nel tuo.

È utile in due casi. Le ricerche ampie, dove serve leggere venti file per rispondere a una domanda sola: il subagent li legge e ti riporta la conclusione. E i controlli indipendenti, dove un secondo agente rilegge il lavoro del primo con occhi puliti — un revisore che non è affezionato al codice che sta giudicando.

Li configuri con il comando /agents, che scrive un file per agente con il suo prompt e i suoi strumenti. Il consiglio è di dare a ciascuno un compito solo e ben definito: i subagent generici tendono a restituire riassunti vaghi.

🧩 Skill e plugin — impacchettare il proprio metodo

Una skill è una procedura scritta che l'agente carica quando serve: il tuo modo di fare una code review, i passi di un rilascio, le convenzioni di un certo tipo di file. Sta in una cartella con un SKILL.md e una descrizione che dice quando usarla — ed è quella descrizione a determinare se verrà invocata al momento giusto.

La differenza rispetto a CLAUDE.md è il costo: le regole del file di progetto pesano in ogni sessione, una skill pesa solo quando serve. È la casa giusta per le procedure lunghe e usate di rado.

I plugin sono il passo dopo: impacchettano skill, hook, subagent e comandi in qualcosa di installabile e condivisibile via marketplace, anche un semplice repo GitHub. È il modo in cui il metodo smette di vivere sulla tua macchina e diventa qualcosa che il team installa.

• Skill: una procedura, caricata a richiesta. Descrizione = quando usarla.
• Plugin: skill + hook + subagent + comandi, installabili insieme.
• Marketplace: anche solo un repo GitHub con un file manifest.

💸 Contesto e costi — /compact, --resume e i limiti

Il contesto è finito, e quando si riempie le risposte peggiorano prima di smettere di funzionare. /compact riassume la conversazione fin lì e riparte con lo spazio libero: il momento giusto per usarlo è quando finisci un pezzo di lavoro, non quando l'agente comincia a confondersi.

--resume riapre una sessione precedente con il suo contesto. È la risposta al «devo rispiegargli tutto da capo domattina»: se il lavoro continua, riprendi la sessione invece di aprirne una nuova.

Sul consumo, la regola che mi ha fatto risparmiare di più non riguarda le opzioni ma le abitudini: sessioni corte e mirate. Una sessione lunga porta in contesto tutto quello che ha letto, e ogni turno successivo lo ripaga. Tre sessioni da venti minuti su tre problemi distinti costano meno di una da un'ora su tutti e tre.

• /compact a fine attività, non quando la qualità è già calata.
• --resume per continuare, invece di ricostruire il contesto da zero.
• Sessioni corte e mirate: è la leva più efficace sul costo.

🧪 Il metodo — TDD e review come guardrail

Qui arriva la parte che conta più di ogni configurazione. Un agente produce codice plausibile molto in fretta; il collo di bottiglia diventa verificare che sia giusto. Se la verifica è lenta o approssimativa, la velocità guadagnata la restituisci tutta in debug.

Il test-driven development è il guinzaglio migliore che ho trovato: il test scritto prima è una specifica eseguibile, e «fatto» smette di essere un'opinione dell'agente per diventare uno stato del sistema. Combinato con l'hook Stop del capitolo sugli hook, diventa un criterio che si fa rispettare da solo.

Il secondo guardrail è la review, e vale la pena non farla fare allo stesso agente che ha scritto il codice: chi ha appena prodotto una soluzione tende a trovarla convincente. Un secondo modello con contesto pulito, o la review automatica sulla pull request in CI, prendono cose che sfuggono.

🆚 Claude Code e le alternative

Non è l'unico agente in circolazione e non è sempre la scelta giusta. GitHub Copilot resta imbattibile sul completamento dentro l'editor: se quello che vuoi è scrivere codice più in fretta riga per riga, è un altro mestiere. Cursor porta l'agente dentro un IDE completo, e a chi non ama il terminale la cosa cambia la vita.

Dove Claude Code prende il largo è nei compiti lunghi e a più passi: refactoring che tocca venti file, migrazioni, «fai passare questa suite», tutto ciò che richiede leggere, provare, correggere e riprovare senza che tu approvi ogni singolo passaggio.

La risposta onesta è che non si escludono: io uso il completamento in editor mentre scrivo e passo all'agente quando il compito ha più passi che righe. Il confronto dettagliato con Copilot, Cursor e Gemini è in un articolo a parte.

✅ Checklist — da zero a un setup che regge

L'ordine conta: ogni passo rende utile il successivo. Se ti fermi dopo il quarto hai già l'80% del valore, e i primi tre si fanno in una sera.

• 1. Installa, apri una sessione su un repo innocuo, fai una domanda di sola lettura.
• 2. Scrivi un CLAUDE.md corto: package manager, comando dei test, cosa non toccare.
• 3. Configura i permessi: allow sui comandi ripetitivi, deny sui file con segreti.
• 4. Adotta un criterio di «fatto» verificabile — i test — e non accettarne altri.
• 5. Aggiungi un hook Stop che quel criterio lo fa rispettare da solo.
• 6. Collega il primo server MCP, uno solo, quello che ti serve davvero.
• 7. Quando ti accorgi di ripetere una procedura, trasformala in una skill.
• 8. Quando la skill serve anche agli altri, impacchettala in un plugin.