Negli ultimi mesi a Milano, Roma e Bologna sono nati piccoli gruppi di sviluppatori che lavorano con Claude Code: l'agente da terminale di Anthropic. La promessa è chiara: aprire una shell, scrivere in linguaggio naturale cosa si vuole ottenere e lasciare che il modello legga il codice, lo modifichi, esegua i test, faccia il commit. Si chiama, con un'espressione che divide la community, vibe coding. Questa guida spiega come iniziare davvero, evitando i tre errori più comuni.

A chi serve e cosa otterrai

Il tutorial è pensato per uno sviluppatore con almeno una conoscenza base di terminale (Linux, macOS o Windows con WSL) e di git. Al termine sarai in grado di: installare Claude Code in modo pulito; configurare il primo permission profile in modo che non vada in loop di prompt; usare i principali slash command (/init, /review, /clear); integrare un MCP server per dare al modello accesso ai tuoi strumenti; impostare un hook che blocca azioni pericolose; gestire un workflow ricorrente.

Strumenti e modelli: cosa scegliere e perché

Claude Code richiede un account Anthropic. Le opzioni disponibili oggi:

  • Claude Pro (20 dollari/mese): include un quota mensile di uso di Claude Code sufficiente per uno sviluppatore che lo usa qualche ora al giorno. Prima scelta per chi inizia.
  • Claude Max 5x e 20x (rispettivamente 100 e 200 dollari/mese): pacchetti pensati per chi usa Claude Code a tempo pieno o per piccoli team.
  • API a consumo: paghi per token, l'opzione più flessibile per chi alterna momenti di uso intenso e momenti di pausa.

Il modello di default è Claude Opus 4.7, rilasciato il 16 aprile 2026, oggi il più capace di Anthropic per ingegneria del software: 87,6% su SWE-bench Verified, 64,3% su SWE-bench Pro. Esiste anche Claude Sonnet 4.6 come alternativa più rapida ed economica. Si possono alternare con uno slash command (/model).

1) Installazione pulita

Su macOS e Linux serve Node.js 20+ installato. Su Windows si usa WSL2 (Ubuntu 24.04 LTS). Il comando è uno solo:

# Installazione globalenpm install -g @anthropic-ai/claude-code# Verificaclaude --version# Login (apre il browser)claude login

Se ricevi EACCES: permission denied, configura prima un prefix npm utente con npm config set prefix ~/.npm-global e aggiungi ~/.npm-global/bin al tuo PATH. Non usare mai sudo per installare npm pacchetti globali: è la causa numero uno di permessi rotti su Mac.

2) Primo avvio in una repo reale

Sposta il terminale dentro un progetto vero (anche un piccolo script Python o un'app React). Quindi:

cd ~/progetti/mia-appclaude

Al primo avvio Claude Code chiede il permesso di leggere i file della directory. Accetta. Subito dopo, il primo comando consigliato è:

> /init

Questo crea un file CLAUDE.md nella root del progetto: una pagina di documentazione "per l'agente" che descrive l'architettura, le dipendenze, i comandi tipici, le convenzioni di codice. Non saltarlo: Claude Code la usa come guida ogni volta che apre la repo.

Il primo comando da dare è /init: genera la pagina di documentazione per l'agente.

3) Slash command essenziali

Una decina di slash command fanno la differenza tra usare bene o male Claude Code:

  • /init: come visto, crea il CLAUDE.md.
  • /clear: cancella la conversazione corrente (utile quando si cambia compito).
  • /compact: riassume la conversazione per liberare contesto.
  • /review: chiede una code review della modifica in corso.
  • /model: alterna Opus 4.7 e Sonnet 4.6.
  • /cost: mostra quanto hai speso in token nella sessione.
  • /permissions: gestisce i permessi (vedi paragrafo 4).
  • /hooks: configura gli hook (paragrafo 5).
  • /mcp: lista, abilita e disabilita gli MCP server (paragrafo 6).
  • /agents: definisce sub-agenti specializzati.

4) Permessi: il primo punto in cui ci si blocca

Claude Code, per default, chiede conferma su qualunque comando bash, qualsiasi scrittura su disco, qualsiasi chiamata HTTP. È sicuro, ma rallenta. Per uno sviluppo fluido, configura un permission profile (in ~/.claude/settings.json) come questo:

{  "permissions": {    "allow": [      "Read",      "Write",      "Edit",      "Bash(npm install)",      "Bash(npm test)",      "Bash(pytest)",      "Bash(ruff*)",      "Bash(git status)",      "Bash(git diff*)",      "Bash(git log*)"    ],    "ask": [      "Bash(git push*)",      "Bash(git reset*)",      "Bash(rm*)"    ],    "deny": [      "Bash(curl*production*)",      "Bash(sudo*)"    ]  }}

Con questa configurazione l'agente esegue senza chiedere i comandi sicuri, chiede conferma su git push e operazioni distruttive, rifiuta in automatico chiamate a sistemi di produzione e l'uso di sudo. È la base.

5) Hook: blocchi e automatismi

Gli hook sono script che il sistema esegue prima o dopo certi eventi (Stop, PreToolUse, PostToolUse). Esempio classico: lanciare i test in automatico ogni volta che Claude finisce un'edit.

{  "hooks": {    "PostToolUse": [      {        "matcher": "Edit|Write",        "hooks": [          {            "type": "command",            "command": "npm test --silent || echo 'TEST FALLITI'"          }        ]      }    ]  }}

Da quel momento, ogni volta che Claude modifica un file, partono i test. Se falliscono, l'agente lo vede subito e prova a sistemare.

6) MCP server: dare strumenti veri

Il Model Context Protocol (MCP) è lo standard aperto che Anthropic ha rilasciato a fine 2024 per connettere modelli a strumenti esterni. In Claude Code si gestisce con /mcp. Esempio: collegare il MCP server di GitHub.

claude mcp add github -- npx -y @modelcontextprotocol/server-github

Dopo qualche secondo l'agente avrà accesso ai tuoi repository, alle pull request, alle issue. Con un comando in chat ("chiudi la issue #142 e linkala al commit di stamattina") Claude può eseguire l'azione direttamente.

Gli MCP server collegano Claude Code a GitHub, database, sistemi di ticketing.

7) Tre prompt che cambiano il workflow

Il prompt è tutto. Tre esempi che funzionano davvero, da usare dopo aver aperto Claude Code dentro la repo:

Aggiungi una rotta GET /api/health che restituisce 200 e {"status":"ok"}. Implementala, scrivi un test unitario con vitest, esegui i test e mostrami il diff prima di committare.
Trova tutti i punti del progetto in cui si usa la libreria moment.js, valuta se possiamo sostituirla con date-fns. Fammi prima una lista di file con linea, poi proponimi un piano di migrazione.
Il file utils/auth.ts ha un bug: in caso di token scaduto torna 200 invece di 401. Riproduci il bug con un test, mostralo rosso, sistema il codice, mostra il test verde.

In tutti e tre i casi la struttura è la stessa: obiettivo concreto, criteri di completamento, vincoli espliciti.

8) Errori comuni e soluzioni

  • "Cannot connect to MCP server": 9 volte su 10 manca un token nelle variabili d'ambiente. Definisci GITHUB_TOKEN, OPENAI_API_KEY nei rispettivi server e ricarica con /mcp reload.
  • L'agente "non vede" un file: probabilmente è in .gitignore o in .claudeignore. Controlla.
  • "Rate limit exceeded": passa temporaneamente a Sonnet 4.6 con /model oppure aspetta il refresh della quota.
  • L'agente continua a fare lo stesso errore: dagli un esempio risolto. "Ecco come faccio io: ...". Il single-shot example è una scorciatoia potente.

9) Alternative e quando non usare Claude Code

Claude Code è oggi il riferimento per chi vuole un agente che lavora dentro un terminale con permessi controllati. Per casi d'uso diversi conviene valutare:

  • Cursor: meglio per chi vuole un editor visuale con suggerimenti inline; la versione 1.0 SDK del 14 maggio 2026 lo apre a uso programmatico in CI/CD.
  • Devin: agente più autonomo, eseguito su VM in cloud; meglio per task lunghi e autonomi.
  • OpenAI Codex CLI: l'omologo OpenAI, gratuito con piano Plus; valida alternativa se hai già un abbonamento ChatGPT.
  • Continue/Cody/Aider: strumenti gratuiti e open-source con un'ottima base ma meno integrati di Claude Code.

Quando non usare Claude Code? Se la repo è troppo grande (oltre 500.000 righe) senza un buon CLAUDE.md, il contesto si satura velocemente. Se devi lavorare su codice altamente sensibile dal punto di vista della sicurezza (chiavi private, infrastrutture critiche) considera l'opzione self-hosted dei modelli open di Anthropic, oggi non ancora disponibile. Se non hai mai usato il terminale, parti da Cursor o GitHub Copilot.

10) Come proseguire

Dopo le prime ore con Claude Code, i passi successivi sono tre. Primo: scrivere il proprio CLAUDE.md curato (i progetti con CLAUDE.md ben fatto ottengono risultati 2-3 volte migliori). Secondo: definire 2-3 sub-agenti specializzati con /agents (uno per i test, uno per la documentazione, uno per la code review). Terzo: integrare almeno 2 MCP server reali nel proprio workflow (GitHub e il database del proprio progetto sono il punto di partenza ideale).

La documentazione ufficiale è in continuo aggiornamento e copre dettagli avanzati come l'integrazione con Codex CLI, gli agenti remoti e le esecuzioni in background. Per la community italiana il canale Telegram "Claude Italia" e il subreddit r/ClaudeAI sono i due punti di scambio più attivi. Buon vibe coding.