Tutorial su Claude Code: configurazione, 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 con comandi in linguaggio naturale. Si integra nel tuo ambiente di sviluppo con una configurazione minima, così puoi concentrarti sullo scrivere e migliorare il codice.

Ecco alcune funzionalità chiave di Claude Code:

• Editing e refactoring: modifica, ottimizza e migliora la tua codebase con suggerimenti potenziati dall’AI.
• Bug fixing: identifica e risolve errori, dipendenze mancanti e colli di bottiglia prestazionali.
• Comprensione del codice: fai domande sull’architettura, la logica e le dipendenze del tuo codice.
• Testing e linting automatizzati: esegui e correggi test falliti, lancia i 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 cloud pianificati che si avviano su trigger senza che il tuo computer sia acceso).

Ecco alcuni profili ideali per questo servizio:

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

Claude Code ora usa di default Claude Opus 4.7 nei piani Max e Team Premium. Gli utenti Pro partono con Sonnet 4.6 ma possono passare ai modelli Opus per i task più impegnativi. 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 standalone usando il Claude Agents SDK.

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

Se stai confrontando Claude Code con l’agente da terminale di xAI, il nostro confronto Grok Build vs. Claude Code mette alla prova entrambi sullo stesso task.

Iniziamo con il 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 semplicemente eseguendo 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 il processo di installazione nativa 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 con un abbonamento a pagamento o con fatturazione via API.

Successivamente riceverai un link di login che porta a un codice di verifica da inserire nel terminale in cui gira Claude Code. Poi hai finito, e uno workspace dedicato “Claude Code” viene creato automaticamente per il tracciamento 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.

Cominciamo clonando la repository e configurando l’ambiente di sviluppo.

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

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

2. Quindi, crea un ambiente virtuale e installa le dipendenze richieste eseguendo i seguenti comandi nel terminale, uno alla volta

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 la tua repository è pronta per essere esplorata. 

Passo 3: Identificare le aree su cui contribuire

Un ottimo modo per contribuire è esplorare la scheda Issues su GitHub. Nella repository di Supabase ho individuato un’issue in client.py relativa 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 e commenti inline significativi per chiarire lo scopo dei vari componenti.
• Identificare e correggere bug analizzando issue e altri potenziali errori.

Passo 4: Sperimentare con Claude Code

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

cd supabase
claude

Claude Code ora ha accesso a ogni file e cartella all’interno della cartella Supabase-py. Adesso, facciamo qualche prova.

Refactoring del codice

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

Prompt: Fai refactoring del codice nel file client.py presente nella cartella Supabase.

Claude chiederà conferma prima di procedere. Premi Invio per approvare le modifiche. Una volta terminato, Claude Code aggiornerà il file, mostrerà le modifiche nel terminale e fornirà un riepilogo delle modifiche effettuate.

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 import per chiarezza e rimosso alias ridondanti per coerenza.
• Maggiore leggibilità: sono stati aggiunti commenti di sezione per classificare gli import e rimossa la duplicazione nella lista __all__ per una struttura più pulita.
• Opzioni del client semplificate: sono state anche ridotte più righe combinando import simili in un’unica istruzione.

Ecco un confronto affiancato tra codice originale e refactor.

Documentare il codice

Oltre al refactoring, Claude Code può generare, aggiornare e standardizzare la documentazione del codice in un intero 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 errori, implementazioni del client, servizi di storage).
• Commenti inline per descrivere tipi di errore, funzioni del client e componenti importanti.

Ecco un confronto affiancato tra codice refactor 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 chiedendo a Claude:

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

Correggere i bug

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

Ecco come usare Claude Code per il debugging:

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

Claude Code ha predisposto quanto segue per risolvere i problemi legati agli import nel file client.py: 

• Commenti type ignore: aggiunto il commento # type: ignore per sopprimere avvisi di IDE e type-checking su import non risolti.
• Categorizzazione coerente degli errori: Claude Code ha garantito che gli import degli errori da autenticazione, database, storage e funzioni siano chiaramente raggruppati.
• Leggibilità del codice mantenuta: 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 di refactoring e debugging, puoi estendere le capacità di Claude Code personalizzandone il comportamento. Hooks e Plugin ti permettono di automatizzare attività ripetitive e integrare sistemi esterni.

Hook di Claude Code

Gli hook di Claude Code sono trigger automatici 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 altrimenti Claude 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 l’hook si attiva?

Ad 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 è accaduto, abilitando decisioni intelligenti basate su tipi di file o percorsi. Possono inviare output alla trascrizione di Claude o inviare messaggi d’errore direttamente a Claude per bloccare le operazioni.

Casi d’uso comuni per gli hook includono:

• Formattazione del codice: esegui automaticamente linters e formatter dopo la scrittura del codice

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

• Sicurezza: blocca modifiche a file sensibili come config di produzione o API key

• Documentazione: genera automaticamente la documentazione delle API quando cambiano i sorgenti

• Automazione Git: crea commit intelligenti e valida le policy di protezione dei branch

• Notifiche: avvisa il tuo team su Slack quando cambiano file importanti

• Compliance: applica header di licenza o standard di coding prima di consentire modifiche

Configura gli hook con il comando /hooks in Claude Code oppure 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 task specifici), server MCP (integrazioni standardizzate degli strumenti) 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, oppure connettersi alla tua infrastruttura di testing interna. I plugin rispondono agli stessi eventi degli hook ma inviano dati a servizi esterni ed elaborano le risposte per influenzare il flusso di lavoro di Claude.

Ecco alcuni task in cui i plugin di Claude Code sono particolarmente utili:

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

• Project management: crea o aggiorna automaticamente issue in Jira, GitHub o Linear

• Comunicazione del team: pubblica aggiornamenti su Slack o Teams quando avvengono modifiche

• Code review: crea automaticamente pull request e gestisci le review su GitHub/GitLab

• Analisi esterne: chiama SonarQube, CodeClimate o Snyk per scanning del codice a livello enterprise

• Strumenti personalizzati: integra sistemi e workflow proprietari dell’azienda

• Estensioni IDE: aggiungi comandi personalizzati e aiuti alla navigazione

Installa plugin da un registro o sviluppali internamente per la tua organizzazione, quindi configura gli eventi a cui devono rispondere. 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 ogni task non banale.
• Auto mode: un classificatore dei permessi che permette a Claude di lavorare con meno interruzioni, utile per task più lunghi in cui non vuoi approvare ogni scrittura su file.
• Routines: agent cloud pianificati che si attivano con una schedulazione 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 IDE JetBrains con diff inline, checkpoint e supporto multi-sessione.
• Controllo remoto e Channels: esegui sessioni di Claude Code e interagisci con esse dal tuo telefono o da altri dispositivi.

Considerazioni finali

In questo tutorial ho usato Claude Code per fare refactoring, 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 è in continua evoluzione 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 creare un progetto da zero, ti consiglio il nostro tutorial su Spec-Driven Development con Claude Code.