Da zero al primo workflow: setup completo di Claude Code in 30 minuti

Claude Code non è un chatbot per il codice. È un agente che legge l'intero repository, modifica file, esegue comandi e si integra con git. Questa guida ti porta dalla prima installazione al primo workflow funzionante in meno di 30 minuti.

---

Perché Claude Code è diverso da tutto il resto

La maggior parte degli strumenti AI per il codice funziona in questo modo: tu scrivi, copi, incolli, aspetti. Claude Code funziona diversamente: è un agente che vive nel tuo terminale, legge l'intero codebase, apre file, esegue comandi e ragiona sull'architettura del progetto come farebbe un senior developer.

La differenza concreta: invece di risponderti con uno snippet da copiare, Claude Code modifica direttamente il file giusto, esegue i test, vede se passano e se non passano cerca di capire perché.

Incluso nel piano Pro ($20/mese). Non serve un abbonamento separato.

---

Installazione

Prerequisiti

• Node.js v18 o superiore (node --version per verificare)
• Account Claude Pro attivo su claude.ai
• Accesso a un repository locale (qualsiasi linguaggio)

Installazione via npm

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

Verifica l'installazione:

claude --version

IMPORTANTE — Security update: assicurati che la versione installata sia ≥ 2.1.90. Le versioni precedenti contengono un bug critico scoperto a marzo 2026: Claude Code ignorava silenziosamente le regole di sicurezza quando un comando conteneva più di 50 sottocomandi. Anthropic ha rilasciato il fix in 2.1.90.

Alternativa: VS Code Extension

Se preferisci un'interfaccia grafica, installa l'estensione Claude Code di Anthropic dal VS Code Marketplace. Avrai una chat window integrata nell'IDE con le stesse funzionalità del terminale.

---

I tre modelli di Claude Code

Claude Code mette a disposizione tre modelli con caratteristiche diverse. Scegliere il modello giusto per ogni task fa la differenza tra velocità e qualità.

Modello	Velocità	Costo API	Quando usarlo
Haiku 4.5	Molto veloce	$0.80/M token in	Task semplici, classificazione, query rapide
Sonnet 4.6	Bilanciato	$3/$15 per M	Sviluppo quotidiano, refactoring, debug
Opus 4.6	Il più potente	$15/$75 per M	Architettura complessa, monorepo, decisioni critiche

Come cambiare modello nella sessione:

/model

Claude mostra un menu per selezionare il modello. La scelta vale solo per la sessione corrente. Per impostare il modello di default permanente, aggiungi la preferenza nel file settings.json o chiedi direttamente a Claude di farlo.

Per utenti nel piano Pro, Sonnet 4.6 è il punto di partenza ottimale per il 90% dei task.

---

I comandi fondamentali

Digita / nel terminale di Claude Code per vedere la lista completa. Questi sono quelli che usi ogni giorno:

/init — il primo comando su ogni nuovo repo

cd /path/to/your-project
claude
# dentro Claude Code:
/init

/init scansiona il repository, rileva lo stack tecnologico, riassume la struttura del progetto e crea automaticamente il file CLAUDE.md nella root. È il punto di partenza obbligatorio su ogni nuovo progetto.

/plan — Plan Mode (la tua rete di sicurezza)

/plan

Attiva la modalità di pianificazione: Claude non modifica nessun file finché non approvi esplicitamente il piano. Fondamentale per lavori su legacy code o codebase che non conosci ancora bene.

/model — cambio modello

/model

/clear e /compact

• /clear — pulisce il contesto della sessione (nuovo inizio)
• /compact — comprime il contesto mantenendo le informazioni essenziali; utile quando la sessione si allunga e la qualità delle risposte inizia a calare

! — modalità bash

Premi ! per eseguire comandi bash direttamente. Claude vede l'output e lo usa nel ragionamento.

---

CLAUDE.md: il file che cambia tutto

CLAUDE.md è il file più importante che creerai in ogni progetto. Claude lo legge automaticamente all'inizio di ogni sessione. Senza di esso, Claude parte da zero ogni volta. Con un buon CLAUDE.md, salta direttamente al lavoro.

Cosa mettere in CLAUDE.md

# Progetto: [Nome Progetto]

## Stack tecnico
- Framework: [es. Laravel 10 + Vue 3 + Inertia.js]
- Database: [es. MySQL 8 + Redis]
- Testing: [es. PHPUnit, Pest]
- CI/CD: [es. GitHub Actions → Forge]

## Struttura principale
- `app/Controllers/` — logica HTTP
- `app/Services/` — business logic
- `resources/js/` — frontend Vue
- `tests/` — PHPUnit + Pest

## Convenzioni di codice
- PHP: snake_case per variabili, PascalCase per classi
- JS: camelCase, no jQuery, composables in `src/composables/`
- Mai usare raw SQL, sempre Eloquent
- Controller: Resource controllers, max 7 metodi standard

## Comandi importanti
- `php artisan test` — esegui tutti i test
- `npm run dev` — dev server con hot reload
- `php artisan migrate:fresh --seed` — reset DB di sviluppo

## Workflow CI
- Ogni PR deve passare: lint + test + type check
- Main branch protetto, richiede PR review

## Regole importanti
- Non modificare migration esistenti (crea nuove)
- Non committare file .env
- Ogni nuova feature deve avere test

CLAUDE.md supporta anche folder-level: puoi creare un CLAUDE.md specifico in ogni sotto-cartella del progetto (es. app/Services/CLAUDE.md con le regole specifiche dei servizi). La priorità è: cartella > root > file globale (~/.claude/CLAUDE.md).

---

Il flusso Explore-Plan-Code-Commit

Questo è il workflow base che funziona per il 90% dei task di sviluppo.

1. Explore

Prima di toccare qualsiasi cosa, fai esplorare Claude:

Ho questo bug: [descrizione]. Prima di qualsiasi modifica,
dimmi come funziona il sistema in questa area, dove potrebbe
essere la causa root e quali file sono coinvolti.

Claude legge i file rilevanti, mappa le dipendenze, identifica il punto di ingresso del problema.

2. Plan

Non saltare questo passaggio, soprattutto su codebase complessi:

Ok, ora proponi un piano di fix. Elenca i file che modificherai,
cosa cambierai in ciascuno e l'ordine delle modifiche.
Non scrivere codice ancora.

Oppure usa direttamente /plan per entrare in modalità pianificazione.

Perché pianificare prima? Claude può fare inferenze errate su dipendenze non ovvie. Un piano esplicito ti permette di intercettare l'errore prima che venga scritto codice.

3. Code

Con il piano approvato, Claude procede con le modifiche:

Piano approvato. Procedi con il fix seguendo esattamente il piano.
Dopo ogni modifica significativa fermati e dimmi cosa hai cambiato.

4. Commit

Genera un commit message descrittivo per questi cambiamenti,
seguendo il formato: tipo(scope): descrizione breve
Es. fix(auth): correggi redirect dopo login con SSO

---

Gestire il contesto: la regola d'oro

Una sessione Claude Code a 90% di utilizzo del context window produce output peggiori. Le istruzioni precedenti si "seppelliscono" e la qualità del codice generato cala visibilmente.

La soluzione:

Prima di aprire una nuova sessione per lo stesso task, chiedi a Claude di creare un handoff document:

Riassumi tutto quello che abbiamo fatto in questa sessione:
(1) cosa è stato modificato e perché,
(2) le decisioni di architettura prese,
(3) il prossimo step esatto,
(4) eventuali dipendenze o rischi da tenere in mente.

Scrivi come se un Claude fresco senza contesto dovesse
riprendere esattamente da qui.

Salva questo documento nel repo (es. docs/claude-handoff.md). Caricalo all'inizio della nuova sessione.

---

Primo test pratico

Prova subito su un repository reale:

1. Apri il terminale nella root del progetto
2. Lancia claude
3. Esegui /init e approva la creazione di CLAUDE.md
4. Chiedi: "Spiega come funziona il sistema di autenticazione di questo progetto"
5. Poi: "C'è qualcosa di migliorabile nel codice di autenticazione? Fai solo un'analisi senza modificare nulla."

In 5 minuti hai già un'analisi del codebase che a mano richiederebbe un'ora.

---

Prossimi passi

Questo tutorial copre il setup e il flusso base. Il tutorial successivo ti insegna a costruire un CLAUDE.md professionale per progetti complessi — con Skills, regole di sicurezza, comandi personalizzati e il modo giusto di strutturare la .claude/ folder per massimizzare l'efficienza.

---

Vuoi mettere in pratica quello che hai imparato? Scopri il servizio di Sviluppo Web — realizziamo applicazioni web su misura con AI integrata: architettura, sviluppo e deploy gestiti da professionisti che usano Claude Code ogni giorno. Up next →CLAUDE.md: il README per l'AI che trasforma Claude nel tuo senior dev 12 min

---

Fonti: DeepLearning.AI — Claude Code: A Highly Agentic Coding Assistant (corso ufficiale Anthropic); Henrique Siebert Domareski — A Practical Guide to Automating Your Development Workflow; Frank's World — Leveraging Claude Code: A Senior Engineer's Guide.