Tutorial su Claude Code: setup, refactoring e debugging nella pratica

Che cos’è Claude Code?

Claude Code è uno strumento che opera direttamente nel tuo terminale, comprende la tua codebase e ti assiste nelle attività di sviluppo usando comandi in linguaggio naturale. Si integra con il tuo ambiente di sviluppo con una configurazione minima, così puoi concentrarti sulla scrittura e il miglioramento del codice.

Ecco alcune funzionalità chiave di Claude Code:

• Editing e refactoring: modifica, ottimizza e migliora la tua codebase con suggerimenti basati sull’AI.
• Correzione bug: identifica e risolve errori, dipendenze mancanti e colli di bottiglia nelle prestazioni.
• Comprensione del codice: poni domande sull’architettura, la logica e le dipendenze del tuo codice.
• Test e linting automatizzati: esegui e correggi test falliti, avvia comandi di linting e migliora la qualità del codice.
• Integrazione con Git: cerca nella cronologia git, risolvi conflitti di merge, crea commit e genera pull request senza sforzo.

Che tu stia lavorando a un progetto open source o gestendo codebase di livello enterprise, Claude Code può aiutarti con un’automazione intelligente che si adatta al tuo stile di coding e ai requisiti del progetto. Gli aggiornamenti recenti hanno aggiunto l’auto mode (meno interruzioni per i permessi), il plan mode (workflow design-first) e le Routines (agent in cloud pianificati che si avviano su trigger senza che il tuo computer sia acceso).

Ecco alcuni utenti ideali per questo servizio:

• Sviluppatori software: migliorare qualità e manutenibilità del codice.
• Contributor open source: comprendere e migliorare codebase non familiari.
• Ingegneri DevOps: automatizzare review del codice e attività di linting.

Claude Code ora usa di default Claude Opus 4.7 sui piani Max e Team Premium. Gli utenti Pro partono con Sonnet 4.6 ma possono passare ai modelli Opus per attività impegnative. Puoi cambiare modello a sessione in corso con il comando /model o regolare la profondità di ragionamento con lo slider /effort. Puoi anche creare agent AI stand-alone usando il Claude Agents SDK.

Anthropic ha anche introdotto Cowork per un aiuto in stile agent nelle attività quotidiane su file e documenti oltre al coding. È disponibile per tutti gli abbonati ai piani a pagamento (Pro, Max, Team, Enterprise) nell’app desktop di Claude.

Iniziamo con il nostro progetto pratico.

Passo 1: Configurare Claude Code

Per iniziare con Claude Code ti serve un terminale, un progetto di codice su cui lavorare e un abbonamento a Claude (Pro/Max/Teams/Enterprise) oppure un account Claude Console con fatturazione attiva.​

Installa Claude Code eseguendo semplicemente uno dei seguenti comandi nel terminale, in base al tuo sistema operativo e terminale.

macOS / Linux / WSL: 

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell: 

irm https://claude.ai/install.ps1 | iex

Windows CMD:  

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Nota: L’installazione tramite npm install -g @anthropic-ai/claude-code esiste ancora ma è deprecata, quindi è preferibile usare il processo di installazione nativo indicato sopra. Se in passato hai installato via npm, puoi migrare con claude install.

Una volta installato, vai nella directory del tuo progetto e avvia Claude eseguendo:

cd your-project-directory
claude

Per l’autenticazione, ti verrà chiesto se vuoi usare Claude Code in base a un abbonamento a pagamento o alla fatturazione per uso API.

Successivamente riceverai un link di login che porta a un codice di verifica da inserire nel terminale in cui gira Claude Code. Fatto questo, verrà creato automaticamente uno spazio di lavoro dedicato “Claude Code” per il monitoraggio dell’uso e la gestione dei costi.

Ora Claude Code è pronto all’uso.

Passo 2: Configurare l’ambiente di sviluppo

Per questa demo userò la libreria Python di Supabase supabase-py, un client Python open source per interagire con Supabase, un backend-as-a-service basato su PostgreSQL. Supabase offre una suite di strumenti, tra cui autenticazione, sottoscrizioni in tempo reale, storage e API generate automaticamente.

Iniziamo clonando il repository e configurando l’ambiente di sviluppo.

1. Apri il terminale, vai nella directory in cui vuoi clonare il repository Supabase-py (es. cd Desktop) ed esegui il seguente comando:

git clone https://github.com/supabase/supabase-py.git
cd  supabase-py

2. Poi crea un ambiente virtuale e installa le dipendenze necessarie eseguendo, una alla volta, i seguenti comandi nel terminale

python3 -m venv env
source env/bin/activate  # On Windows, use ./env/Scripts/activate
pip install -e .

Il tuo ambiente Python è ora configurato con tutte le dipendenze necessarie per eseguire la libreria Supabase, e il tuo repository è pronto per essere esplorato. 

Passo 3: Identificare aree su cui contribuire

Un ottimo modo per contribuire è esplorare la scheda Issues su GitHub. Nel repository Supabase, ho individuato un problema in client.py relativo a leggibilità del codice, struttura e mancanza di commenti significativi.

Ecco cosa faremo con Claude Code:

• Faremo refactoring del codice per migliorarne leggibilità, manutenibilità e struttura.
• Aggiungere docstring significative e commenti inline per chiarire lo scopo delle varie componenti.
• Identificare e correggere bug analizzando le issue e altri potenziali errori.

Passo 4: Sperimentare con Claude Code

Dal momento che siamo già nella cartella supabase-py, vai nella directory supabase che contiene il file client.py ed esegui Claude Code:

cd supabase
claude

Ora Claude Code ha accesso a tutti i file e le cartelle all’interno della cartella Supabase-py. Adesso, sperimentiamo.

Refactoring del codice

Come parte del miglioramento della SDK Python di Supabase, facciamo il refactoring del file client.py per migliorarne leggibilità, manutenibilità e organizzazione. Inserisci semplicemente il seguente prompt nella riga di comando:

Prompt: Esegui il refactoring del codice nel file client.py situato nella cartella Supabase.

Claude chiederà conferma prima di procedere. Premi Invio per approvare le modifiche. Al termine, Claude Code aggiornerà il file, mostrerà le modifiche nel terminale e fornirà un riepilogo degli interventi effettuati.

Usando Claude Code, abbiamo applicato i seguenti miglioramenti a client.py:

• Import ordinati:  Claude Code ha raggruppato gli import correlati in sezioni logiche (errori di auth, tipi API, errori delle funzioni), rinominato gli import per maggiore chiarezza e rimosso alias ridondanti per coerenza.
• Maggiore leggibilità: ha aggiunto commenti di sezione per classificare gli import e rimosso duplicazioni nella lista __all__ per un’organizzazione più pulita.
• Opzioni client semplificate: ha anche ridotto più righe combinando import simili in un’unica istruzione.

Ecco un confronto affiancato tra codice originale e rifattorizzato.

Documentazione del codice

Oltre al refactoring, Claude Code può generare, aggiornare e standardizzare la documentazione del codice in tutto un progetto. Può identificare sezioni non documentate, generare docstring o commenti strutturati e verificare la conformità agli standard di documentazione del progetto.

Abbiamo usato Claude Code per migliorare la documentazione in client.py, ottenendo:

• Docstring a livello di modulo chiare che spiegano lo scopo del file.
• Commenti di sezione dettagliati che categorizzano gli import (tipi di errore, implementazioni client, servizi di storage).
• Commenti inline per descrivere tipi di errore, funzioni del client e componenti importanti.

Ecco un confronto affiancato tra codice rifattorizzato e documentato.

Prompt: Documenta il codice di client.py aggiungendo commenti per migliorarne la comprensione.

Una volta aggiunta la documentazione, puoi verificarne la conformità agli standard del tuo progetto chiedendolo a Claude:

Prompt: Verifica se la documentazione segue gli standard del nostro progetto.

Correzione dei bug

Il debugging può richiedere tempo, ma Claude Code accorcia il ciclo analizzando i messaggi di errore, identificando le cause alla radice e suggerendo correzioni. Che tu stia affrontando import mancanti, errori di runtime o problemi logici, restringe il campo e propone correzioni mirate.

Ecco come usare Claude Code per il debugging:

1. Identifica il problema:  condividi il messaggio di errore con Claude.
2. Ottieni raccomandazioni di fix: chiedi a Claude possibili soluzioni.
3. Applica e verifica il fix:  implementa i suggerimenti di Claude e verifica se il problema è risolto.

Claude Code ha effettuato i seguenti interventi per risolvere problemi legati agli import nel file client.py: 

• Commenti di type ignore: aggiunti commenti # type: ignore per sopprimere avvisi dell’IDE e del type checker per import non risolti.
• Categorizzazione coerente degli errori: Claude Code ha assicurato che gli import degli errori da autenticazione, database, storage e funzioni fossero chiaramente raggruppati.
• Mantenuta la leggibilità del codice: sono stati aggiunti commenti per indicare perché certi import sono stati ignorati invece di rimuoverli.

Ecco un confronto affiancato tra il codice originale e quello corretto.

Prompt: Vedo alcuni bug, ad esempio “Import gotrue.errors non può essere risolto”. Aiutami a correggere tutti gli errori in client.py.

Comandi di Claude Code

Ecco alcuni comandi da provare con Claude.

Per approfondire, ti consiglio la nostra guida ai comandi slash di Claude Code.

Funzionalità avanzate di Claude Code

Quando hai preso confidenza con le basi del refactoring e del debugging, puoi estendere le capacità di Claude Code personalizzandone il comportamento. Hooks e Plugin ti permettono di automatizzare compiti ripetitivi e integrare sistemi esterni.

Hook di Claude Code

Gli hook di Claude Code sono trigger automatizzati che eseguono comandi shell quando si verificano eventi specifici durante la tua sessione con Claude Code. Automatizzano attività ripetitive come formattazione del codice, esecuzione dei test e controlli di sicurezza che Claude altrimenti potrebbe saltare.

Gli hook usano un sistema evento-azione, in cui definisci tre cose:

• L’evento: quando si attiva l’hook?

• Il matcher: quali azioni sono interessate?

• Il comando: cosa viene eseguito quando si attiva l’hook?

Per esempio, un hook può attivarsi dopo che Claude scrive un file Python ed eseguire automaticamente black per formattare il codice. Gli hook ricevono contesto JSON su ciò che è successo, abilitando decisioni intelligenti basate su tipi o percorsi di file. Possono inviare output alla trascrizione di Claude o mandare messaggi di errore direttamente a Claude per bloccare operazioni.

Casi d’uso comuni per gli hook includono i seguenti

• Formattazione del codice: eseguire automaticamente linters e formattatori dopo la scrittura del codice

• Testing: eseguire suite di test dopo le modifiche per intercettare presto i bug

• Sicurezza: bloccare modifiche a file sensibili come config di produzione o chiavi API

• Documentazione: generare automaticamente documentazione API quando cambiano i sorgenti

• Automazione Git: creare commit intelligenti e validare policy di protezione dei branch

• Notifiche: avvisare il team via Slack quando cambiano file importanti

• Conformità: applicare header di licenza o standard di coding prima di consentire modifiche

Configura gli hook usando il comando /hooks in Claude Code o modifica direttamente ~/.claude/settings.json.

Plugin di Claude Code

I plugin sono estensioni che collegano Claude Code a strumenti, servizi e API esterni. Mentre gli hook automatizzano comandi shell locali, i plugin si integrano con il tuo ecosistema di sviluppo più ampio come pipeline CI/CD, strumenti di project management e piattaforme di comunicazione del team.

I plugin possono includere più componenti—subagent (assistenti Claude specializzati per compiti specifici), server MCP (integrazioni standardizzate di tool) e hook—riuniti in un unico pacchetto che li orchestra insieme.

Un plugin può analizzare le modifiche al codice e aprire automaticamente issue in Jira, o connettersi alla tua infrastruttura di test interna. I plugin rispondono agli stessi eventi degli hook ma inviano dati a servizi esterni ed elaborano le risposte per influenzare il workflow di Claude.

Ecco alcuni compiti in cui i plugin di Claude Code sono ottimi:

• Integrazione CI/CD: avviare build, test e deployment quando i file cambiano

• Project management: creare o aggiornare automaticamente issue in Jira, GitHub o Linear

• Comunicazione del team: pubblicare aggiornamenti su Slack o Teams quando si verificano modifiche

• Code review: creare automaticamente pull request e gestire review su GitHub/GitLab

• Analisi esterna: chiamare SonarQube, CodeClimate o Snyk per scansioni enterprise del codice

• Strumenti personalizzati: integrarsi con sistemi e workflow proprietari aziendali

• Estensioni IDE: aggiungere comandi personalizzati e aiuti alla navigazione

Installa plugin da un registry o sviluppali internamente per la tua organizzazione, quindi configura a quali eventi rispondono. Insieme, hook e plugin creano una piattaforma estensibile che adatta Claude Code alla tua infrastruttura esistente.

Altre funzionalità avanzate

Nel 2026 Claude Code ha aggiunto diverse altre funzionalità importanti che ampliano come e dove puoi usarlo:

• Plan mode: un workflow design-first in cui Claude crea un piano di implementazione dettagliato prima di scrivere qualsiasi codice. Lo uso per qualsiasi attività non banale.
• Auto mode: un classificatore di permessi che consente a Claude di lavorare con meno interruzioni, utile per compiti lunghi in cui non vuoi approvare ogni scrittura di file.
• Routines: agent in cloud pianificati che si attivano su una schedule cron, un evento GitHub (come apertura di una PR) o una chiamata webhook. La tua macchina non deve essere accesa.
• Integrazione IDE: Claude Code ha estensioni ufficiali per VS Code, Cursor e gli IDE JetBrains con diff inline, checkpoint e supporto multi-sessione.
• Controllo remoto e Channels: esegui sessioni di Claude Code e interagisci con esse dal telefono o da altri dispositivi.

Considerazioni finali

In questo tutorial ho usato Claude Code per rifattorizzare, documentare e fare debug di un file nella SDK Python di Supabase. Abbiamo migliorato la leggibilità del codice, aggiunto documentazione strutturata e risolto problemi di import.

Claude Code si evolve attivamente con funzionalità come plan mode, auto mode e Routines, quindi vale la pena sperimentarlo nei tuoi progetti per capire come si adatta al tuo workflow.

Per fare il passo successivo, ti invito a leggere il nostro tutorial sulle best practice di Claude Code, che ti insegna a sfruttare al meglio la finestra di contesto di Claude. Se vuoi costruire un progetto da zero, ti consiglio il nostro tutorial sul Development guidato da specifiche con Claude Code.