Claude Code: manuale di sopravvivenza

Un agente AI nel tuo computer è un’arma. Qualche consiglio per togliere la sicura senza spararsi sui piedi.

⏱️ Lettura: ~12 minuti
☕ Caffè necessari: 2 o 3

---

Se hai usato Claude nella sua interfaccia web, cioè quella trovi su https://claude.ai/, hai interagito con un modello conversazionale. Tu scrivi un prompt e Claude ti restituisce un testo. Il testo può anche essere codice che fai “girare” da qualche parte, dopo un copia-e-incolla, ma c’è poco da aggiungere: tu chiedi, Claude risponde. Fine.

Claude Code è una cosa completamente diversa: è un agente che vive nel tuo terminale, legge i tuoi file, esegue comandi bash, modifica il codice, gestisce i commit Git e prende decisioni operative in autonomia. Non è un’interfaccia: è un collaboratore che ha accesso diretto alla tua macchina e a tutti i contenuti cui tu gli permetti di accedere¹.

Se hai capito la differenza, hai anche capito che per imparare a pilotare una cosa simile devi procedere con molta prudenza e molta disciplina.

---

Prima di cominciare

Nota sulla data. Questo articolo è aggiornato al 21 marzo 2026. Claude Code è un prodotto in sviluppo attivo: Anthropic rilascia aggiornamenti anche più volte a settimana, e comandi, flag, modelli, pricing e limiti di utilizzo possono cambiare senza preavviso. Se stai leggendo questo pezzo a distanza di settimane o mesi dalla pubblicazione, verifica sempre le informazioni e la documentazione ufficiale su code.claude.com/docs e il changelog su GitHub. I principi operativi come commit preventivo, scoping, gestione del contesto, igiene dei permessi è probabile che restino validi indipendentemente dalla versione. I dettagli tecnici, no.

---

Cos’è davvero

Claude Code è il tool CLI² di Anthropic per lo sviluppo assistito da AI. Quando lo avvii in una directory di progetto, indicizza il codice, comprende l’architettura, risponde a domande sul codebase e — soprattutto — scrive, modifica e cancella file in autonomia. Può eseguire test, lanciare build, gestire worktree Git, integrare servizi esterni tramite MCP³ e delegare sotto-task a sub-agenti con contesti separati.

Non hai capito niente? Abbandona immediatamente la lettura di questo articolo. Quello che segue può seriamente danneggiarti e se il tuo computer dovesse prendere fuoco, innescando una guerra termonucleare che azzererà la popolazione umana e ucciderà cuccioli e gattini, non potrai addossarne la responsabilità alle righe che seguono.

Poi non dite che non siete stati avvisati…

Claude Code funziona su macOS, Linux (compreso il container Linux dei Chromebook via Crostini) e Windows (via WSL o Git Bash). Si integra nativamente con VS Code, Cursor, Windsurf e gli IDE JetBrains e un sacco di altri editor.

Come installarlo

L’installazione nativa è oggi il metodo raccomandato da Anthropic. Non richiede Node.js:

# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows (PowerShell)
irm https://claude.ai/install.ps1 | iex

Se stai ancora usando l’installazione via npm (npm install -g @anthropic-ai/claude-code), sappi che è ufficialmente deprecata. Per migrare:

# 1. Installa il binario nativo
claude install

# 2. Rimuovi la vecchia installazione npm
npm uninstall -g @anthropic-ai/claude-code

Le configurazioni esistenti (~/.claude/settings.json e .claude/ del progetto) vengono preservate automaticamente.

Alternative:

• brew install --cask claude-code su macOS/Linux,

• winget install Anthropic.ClaudeCode su Windows.

Attenzione: Homebrew e WinGet non supportano l’auto-update — dovrai aggiornare manualmente con

• brew upgrade claude-code

• winget upgrade Anthropic.ClaudeCode

Dopo l’installazione, naviga nella directory del tuo progetto e lancia:

claude

Al primo avvio, si aprirà un browser per l’autenticazione OAuth⁴.

---

Il colore dei TUOI soldi

Questo è il punto dove la maggior parte delle guide sorvola, e dove si annidano le sorprese in fattura. Ci sono due strade, con implicazioni molto diverse.

Subscription (Pro, Max). Con un piano Pro (20$/mese) o Max (100$ o 200$/mese), Claude Code è incluso. L’utilizzo condivide i limiti con l’interfaccia web di claude.ai: lo stesso budget copre entrambi. Tutti i piani a pagamento danno accesso a tutti i modelli, Opus 4.6 compreso. La differenza tra Pro e Max non è quali modelli puoi usare, ma quanto: Opus brucia il budget molto più velocemente di Sonnet, quindi con un Pro raggiungi il limite prima.

Da agosto 2025, Anthropic ha introdotto limiti settimanali oltre a quelli per sessione che si resettano sette giorni dopo l’inizio del primo utilizzo nel ciclo.

Quando raggiungi il limite del tuo piano, Claude Code ti propone di passare alla fatturazione API. Se confermi, paghi a consumo ai prezzi standard. Se hai l’auto-reload attivo nella Console Anthropic, i crediti si ricaricano automaticamente — e qui nasce il rischio. Se non vuoi addebiti imprevisti:

# Fai logout e rientra SOLO con le credenziali del piano
claude logout
claude login
# Autenticati solo con Pro/Max, senza aggiungere credenziali Console API

Un dettaglio insidioso: se hai una variabile d’ambiente ANTHROPIC_API_KEY impostata nel tuo .zshrc o .bashrc, Claude Code la userà per l’autenticazione al posto della tua subscription, generando addebiti API senza chiedertelo. Controlla.

API (pay-per-use). L’alternativa è autenticarsi tramite API key della Console Anthropic. Paghi esattamente per i token consumati: Sonnet a 3$/15$ per milione di token input/output, Opus a 5$/25$, Haiku a 1$/5$. Nessun tetto, ma nessun paracadute. Un utente che ha tracciato il proprio consumo su otto mesi ha calcolato che il costo equivalente API del suo utilizzo con piano Max sarebbe stato superiore ai 15.000$, contro gli 800$ pagati. La subscription conviene quasi sempre se ne fai un uso regolare.

---

Le regole di ingaggio

Questo non è un tutorial. È un protocollo operativo che individua le le buone pratiche da fare sempre, prima e durante qualsiasi sessione di lavoro con Claude Code. Alla fine, trovate una checklist riassuntiva.

1. Controlla il paracadute

Claude Code scrive e modifica file in autonomia. Se l’agente produce una soluzione errata e sovrascrive un file critico, non c’è Ctrl+Z a livello di file system.

La regola è ferrea e non ammette eccezioni: il progetto deve essere un repository Git con working tree pulito prima di delegare qualsiasi modifica all’agente.

git add . && git commit -m "pre-claude-refactor"

Se l’agente devasta il tuo codice, un git restore . riporta tutto allo stato precedente in una frazione di secondo. Per un approccio più granulare, puoi creare un branch dedicato:

git checkout -b claude/refactor-auth

Così puoi fare cherry-pick delle modifiche buone e scartare il resto.

2. Non tenere armi libere in casa

Non lanciare mai Claude Code dalla tua cartella Home (~). Se chiedi “cerca un file” senza contesto, l’agente può innescare una scansione ricorsiva dell’intero file system accessibile, saturando memoria e contesto.

Naviga sempre nella directory specifica del progetto — o meglio, del sotto-progetto — prima di invocare claude. Per i monorepo, posizionati nella sotto-directory rilevante e, se necessario, aggiungi directory adiacenti con il flag --add-dir:

cd ~/projects/backend/auth-service
claude --add-dir ~/projects/shared/types

Se ti serve aggiungere una directory a sessione già avviata, usa lo slash command /add-dir senza dover riavviare.

3. Non coinvolgere i civili

L’errore più costoso è far indicizzare all’agente file inutili al tuo lavoro. Claude Code invia massivamente contesto al server per comprendere il progetto. Se non lo filtri, leggerà qualsiasi cosa, bruciandoti il budget di token in minuti.

Crea un file .claudeignore nella root del progetto prima di inizializzare Claude:

# .claudeignore — sintassi analoga a .gitignore
node_modules/
.git/
dist/
build/
__pycache__/
*.log
*.bin
*.o
.env
coverage/

La logica è facile: tutto ciò che non è rilevante per il ragionamento logico sull’architettura o la logica del codice va escluso.

4. Ricorda chi sei

Questo è al tempo stesso la cosa più importante del tuo setup e la pratica più sottovalutata da chi si avvicina a Claude Code.

CLAUDE.md è un file Markdown che l’agente legge automaticamente a ogni avvio di sessione. È la sua “costituzione” locale: gli dice come funziona il progetto, quali convenzioni seguire, quali comandi usare, cosa non toccare.

Se non esiste, crealo con /init nella sessione interattiva, oppure scrivilo a mano. Un CLAUDE.md efficace potrebbe essere fatto più o meno così:

# Progetto: auth-service

## Architettura
Backend Express + TypeScript. Database PostgreSQL via Prisma ORM.
Frontend separato (non in questa directory).

## Comandi
- Build: `npm run build`
- Test: `npm run test`
- Lint: `npx eslint . --fix`

## Convenzioni
- TypeScript strict per tutto il codice nuovo.
- Test con Jest, co-locati con i sorgenti (*.test.ts).
- Commit convenzionali (feat:, fix:, refactor:).

## Divieti
- Non modificare mai file in /config/production/
- Non eseguire migrazioni database senza conferma esplicita

Il punto chiave: tutto ciò che inserisci nel CLAUDE.md sopravvive alla compattazione del contesto (vedi più avanti). Se una regola è importante, va scritta lì.

Tieni il file sotto le 200 righe. Un CLAUDE.md troppo lungo viene parzialmente ignorato: le istruzioni importanti si perdono nel rumore. Se il progetto è molto complesso, usa file CLAUDE.md gerarchici nelle sotto-directory — l’agente li carica tutti, dando priorità al più specifico. Puoi aggiungere una sezione “Compact Instructions” per controllare cosa viene preservato durante la compattazione automatica.

5. Controlla il contesto

Il contesto è la vera risorsa fondamentale. Ogni messaggio che invii viene reinviato insieme all’intera cronologia della sessione. Se passi ore sullo stesso bug, paghi token per log di tentativi falliti che non servono più a nulla. Scriviti da qualche parte questi comandi e ricorda di usarli.

/context — Il cruscotto. Mostra una griglia colorata del consumo di contesto. Usalo spesso: è il tuo indicatore di carburante.

/compact — Comprime la cronologia mantenendo un riassunto strutturato. Puoi specificare cosa preservare: /compact conserva la lista dei file modificati e i comandi di test. Dalla versione 2.0.64, la compattazione è istantanea. Claude compatta automaticamente intorno al 75% del contesto, ma la compattazione manuale con istruzioni specifiche produce risultati migliori.

/clear — Tabula rasa. Cancella tutta la cronologia conversazionale, preservando CLAUDE.md e la memoria del progetto. I tuoi file non vengono toccati. Usalo quando cambi task: non ha senso trascinare il contesto di un refactoring nel debug di un bug completamente diverso.

Regola operativa: /compact quando chiudi un task e ne inizi uno correlato; /clear quando cambi completamente argomento.

6. Nessuno ha carta bianca

Di default, Claude Code chiede conferma prima di ogni operazione potenzialmente distruttiva. Questo è intenzionale. Non disabilitare i permessi globalmente⁵.

Quello che puoi fare è configurare allow-list e deny-list nel file .claude/settings.json del progetto:

{
  "permissions": {
    "allow": [
      "Read(./src/**)",
      "Read(./tests/**)",
      "Bash(npm run test)",
      "Bash(npm run lint)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git add *)",
      "Bash(git commit *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./config/production/**)",
      "Bash(rm -rf *)",
      "Bash(sudo *)"
    ]
  }
}

Permetti esplicitamente le operazioni sicure e routinarie; nega esplicitamente quelle distruttive. Per tutto il resto, Claude continuerà a chiedere conferma. Puoi gestire i permessi anche interattivamente con /permissions durante una sessione.

7. Monitoraggio costante

Claude Code offre tre comandi distinti per il monitoraggio:

• /cost — Token consumati e costo in dollari della sessione corrente. Utile per utenti API; irrilevante per chi ha una subscription (il costo è compreso nel piano).

• /usage — Consumo rispetto ai limiti del tuo piano. Questo è il comando che vuoi controllare se sei su Pro o Max.

• /stats — Analytics personali: modello preferito, grafico di utilizzo, streak. Non è uno strumento di fatturazione.

Per un monitoraggio continuo senza digitare comandi, configura la status line con /statusline: uno script personalizzabile che mostra modello attivo, branch Git, costo e percentuale di contesto usato nella barra inferiore del terminale, aggiornato in tempo reale.

8. Scegli le munizioni giuste

Non tutti i task richiedono lo stesso modello. Opus è potente ma costoso in termini di consumo; Sonnet è veloce e sufficiente per la maggior parte del lavoro quotidiano; Haiku è economico per operazioni semplici.

Il modello default è un alias intelligente: parte da Opus e scala automaticamente su Sonnet quando ti avvicini ai limiti di utilizzo. Non è una scelta fissa: l’agente gestisce il fallback in autonomia. Se ti serve un controllo più fine:

/model

Questo comando mostra i modelli disponibili per il tuo piano e ti permette di cambiare al volo. La modalità opusplan merita attenzione: usa Opus per la fase di pianificazione e analisi architetturale, poi passa automaticamente a Sonnet per la scrittura del codice. Il meglio di entrambi i mondi: ragionamento profondo dove serve, velocità dove basta.

Strategia razionale per l’uso quotidiano: Sonnet come default, Opus per decisioni architetturali complesse o debugging multi-file, Haiku per i sub-agenti con task semplici. Il 90% del lavoro è codice Sonnet.

9. Vai avanti, ferma!, torna indietro

Se vedi Claude andare in una direzione sbagliata, non aspettare che finisca. Il tasto Esc interrompe l’agente a metà azione, immediatamente. È il freno a mano.

Esc premuto due volte attiva il rewind (è come inviare il comando /rewind): un menu ti permette di selezionare qualsiasi punto precedente nella conversazione e scegliere tra tre opzioni — ripristinare codice e conversazione, solo la conversazione, o solo il codice. È il tuo punto di salvataggio automatico.

Il principio: intervieni presto. I risultati migliori vengono da cicli di feedback stretti, non dal lasciare l’agente lavorare indisturbato per venti minuti.

10. Dove eravamo rimasti?

Le sessioni di Claude Code sono persistenti. Non devi ricominciare da zero ogni volta che chiudi il terminale.

# Riprendi l'ultima sessione nella directory corrente
claude -c

# Riprendi una sessione specifica per ID
claude --resume <session-id>

# Riprendi una sessione collegata a una PR
claude --from-pr <numero-o-url>

Utile per tornare su un problema abbandonato e chiedere all’agente di riassumere come lo aveva affrontato; informazione che puoi poi usare per aggiornare il CLAUDE.md. Prima di chiudere una sessione, usa /rename per darle un nome descrittivo: ritrovarla sarà molto più facile.

11. Hooks: i guardiani dei guardiani

Gli hooks sono script che si eseguono automaticamente prima o dopo le azioni dell’agente. Sono più affidabili delle istruzioni nel CLAUDE.md, perché si attivano a ogni singola operazione senza possibilità di essere “dimenticati” sotto pressione di contesto.

Configurali in .claude/settings.json:

{
  "hooks": [
    {
      "matcher": "Edit|Write",
      "hooks": [
        {
          "type": "command",
          "command": "prettier --write \"$CLAUDE_FILE_PATHS\""
        }
      ]
    }
  ]
}

Questo esempio esegue Prettier su ogni file che Claude modifica. Puoi usare gli hooks per: validazione TypeScript post-modifica, lint automatico, blocco di scrittura su percorsi protetti, log delle azioni. Non sono una barriera di sicurezza assoluta, visto che un’iniezione di prompt sufficientemente creativa può aggirarli, ma sono comunque dei guardrail piuttosto efficaci per il lavoro quotidiano.

12. Calling all agents

Quando Claude esplora il codebase per rispondere a una domanda, legge decine di file e tutto finisce nel tuo contesto principale. I sub-agenti operano in finestre di contesto separate e restituiscono solo il risultato finale.

Usa un sub-agente per investigare come il sistema di autenticazione
gestisce il refresh dei token, e se esistono utility OAuth riutilizzabili.

Il sub-agente esplora, legge, analizza, e riporta un riassunto compatto — senza inquinare il contesto della conversazione principale. Per task di esplorazione o analisi estesa, sono lo strumento più potente a tua disposizione.

13. Oh, my Zsh!

Ok, questa è solo per chi usa Zsh in linux. Una volta interiorizzate le pratiche fondamentali, si possono centralizzare le operazioni frequenti editando il file .zshrc:

# --- Claude Code Aliases ---
alias c='claude'
alias cc='claude -c'                    # Riprendi ultima sessione
alias cask='claude -p'                  # One-shot (print mode)

Il flag -p (print mode) è particolarmente utile per interrogazioni rapide senza aprire la sessione interattiva. Ideale per il piping:

claude -p "analizza l'errore: $(cat /var/log/syslog | tail -n 20)"
claude -p "spiega questa funzione" < src/auth/middleware.ts

---

Checklist operativa

Ed eccoci allo specchietto finale…

Prima di ogni sessione:

1. ✅ Repo Git con working tree pulito (git status senza modifiche non committate)

2. ✅ Posizionarsi nella directory specifica di progetto

3. ✅ .claudeignore presente con le esclusioni appropriate

4. ✅ CLAUDE.md aggiornato con convenzioni, comandi e divieti

Durante la sessione:

5. ✅ /context regolarmente per monitorare il consumo

6. ✅ /compact con istruzioni specifiche quando chiudi un task

7. ✅ /clear quando cambi argomento

8. ✅ Esc non appena l’agente comincia a dare i numeri

9. ✅ /usage (subscription) o /cost (API) per il monitoraggio economico

Questo setup non elimina i rischi che comporta l’avere un agente IA a spasso per la propria macchina. Nessun protocollo può farlo con un sistema che ha accesso al tuo file system. Però li riduce a un livello gestibile e reversibile.

Come sempre, la parte difficile non è la configurazione, ma la disciplina necessaria a seguirla ogni volta.

---

Sitografia

• Anthropic, “Advanced setup — Claude Code Docs”: https://code.claude.com/docs/en/setup

• Anthropic, “Best Practices for Claude Code”: https://code.claude.com/docs/en/best-practices

• Anthropic, “Checkpointing — Claude Code Docs”: https://code.claude.com/docs/en/checkpointing

• Anthropic, “Common workflows — Claude Code Docs”: https://code.claude.com/docs/en/common-workflows

• Anthropic, “How Claude Code works”: https://code.claude.com/docs/en/how-claude-code-works

• Anthropic, “Manage costs effectively — Claude Code Docs”: https://code.claude.com/docs/en/costs

• Anthropic, “Model configuration — Claude Code Docs”: https://code.claude.com/docs/en/model-config

• Anthropic, “Using Claude Code with your Pro or Max plan”: https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan

• Anthropic, “What is the Max plan?”: https://support.claude.com/en/articles/11049741-what-is-the-max-plan

• Anthropic, “What is the Pro plan?”: https://support.claude.com/en/articles/8325606-what-is-the-pro-plan

• Anthropic, CHANGELOG ufficiale Claude Code: https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md

• Trail of Bits, “claude-code-config — Opinionated defaults”: https://github.com/trailofbits/claude-code-config

1. Agente AI: un sistema di intelligenza artificiale che non si limita a rispondere a domande, ma può pianificare, prendere decisioni e compiere azioni autonome nell'ambiente in cui opera — in questo caso, il tuo file system.

2. CLI (Command-Line Interface): interfaccia a riga di comando, dove si interagisce col software digitando comandi testuali nel terminale, anziché cliccando su pulsanti in un’interfaccia grafica.

3. MCP (Model Context Protocol): protocollo aperto che consente a Claude Code di connettersi a strumenti e servizi esterni — database, API, sistemi di project management come Jira, repository GitHub — tramite un’interfaccia standardizzata. Pensa a un sistema di plugin.

4. OAuth (Open Authorization): protocollo standard per l’autenticazione delegata. In pratica, ti permette di autorizzare Claude Code ad accedere al tuo account Anthropic senza inserire direttamente username e password nel terminale.

5. Il flag --dangerously-skip-permissions esiste per ambienti containerizzati e pipeline CI/CD. Il nome non è casuale. Non usarlo sul tuo ambiente di sviluppo.