Tutorial su Claude Code: configurazione, refactoring e debug nella pratica

Che cos’è Claude Code?

Claude Code è uno strumento che opera direttamente nel tuo terminale, comprende la tua codebase e ti aiuta nelle attività di sviluppo con comandi in linguaggio naturale. Si integra con il 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 basati sull’IA.
• Correzione bug: 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.
• Test e linting automatici: esegui e correggi test in errore, lancia 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 a livello enterprise, Claude Code offre un’automazione intelligente che si adatta al tuo stile di coding e ai requisiti del progetto. Gli aggiornamenti recenti hanno introdotto 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 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 attività di code review e 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 i compiti 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 IA stand-alone usando il Claude Agents SDK.

Anthropic ha anche introdotto Cowork per un aiuto in stile agente 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 progetto pratico.

Passo 1: Configurare Claude Code

Per iniziare con Claude Code, ti servono 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 uno dei seguenti comandi nel terminale, a seconda del 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 nativo indicato sopra. Se in precedenza 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 basata su API.

Poi riceverai un link di login che conduce a un codice di verifica da inserire nel terminale in cui gira Claude Code. Fatto questo, verrà creato automaticamente un workspace dedicato “Claude Code” per il tracciamento dell’utilizzo e la gestione dei costi.

Ora Claude Code è pronto all’uso.

Passo 2: Configura 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 costruito su PostgreSQL. Supabase offre una suite di strumenti, tra cui autenticazione, sottoscrizioni in tempo reale, storage e API generate automaticamente.

Cominciamo 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 richieste eseguendo nel terminale, una alla volta, le seguenti istruzioni

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 repository è pronto per essere esplorato. 

Passo 3: Identificare le 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 assenza 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 delle diverse 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. Ora 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 che si trova 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.

Con 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 alcuni 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 un’organizzazione più pulita.
• Opzioni del client semplificate: sono stati anche ridotti più righi combinando import simili in un’unica istruzione.

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

Documentazione del codice

Oltre al refactoring, Claude Code può generare, aggiornare e standardizzare la documentazione del codice in tutto un progetto. Può identificare le 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 dei 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 chiedendo 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 le correzioni. Che si tratti di import mancanti, errori in runtime o problemi logici, restringe il campo e propone correzioni mirate.

Ecco come usare Claude Code per il debug:

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 la correzione:  implementa i suggerimenti di Claude e verifica che il problema sia risolto.

Claude Code ha adottato le seguenti misure per risolvere i problemi relativi 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.
• 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.

Ti consiglio anche di consultare i tutorial ufficiali di Anthropic e la nostra guida alle best practice di Claude Code.

Funzionalità avanzate di Claude Code

Quando avrai preso confidenza con le basi del refactoring e del debugging, potrai estendere le capacità di Claude Code personalizzandone il comportamento. Hook 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 di Claude Code. Automatizzano attività ripetitive come formattazione del codice, esecuzione dei test e controlli di sicurezza che Claude potrebbe altrimenti 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?

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

Casi d’uso comuni per gli hook includono:

• Formattazione del codice: eseguire automaticamente linter e formatter dopo le scritture di codice

• Testing: eseguire suite di test dopo le modifiche per intercettare bug in anticipo

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

• Documentazione: generare automaticamente documentazione API quando cambiano i file sorgente

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

• Notifiche: avvisare il tuo 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 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 compiti specifici), server MCP (integrazioni standardizzate di 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 test interna. I plugin rispondono agli stessi eventi degli hook ma inviano i dati a servizi esterni ed elaborano le risposte per influenzare il workflow di Claude.

Ecco alcuni compiti per cui i plugin di Claude Code sono ideali:

• 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 si verificano modifiche

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

• Analisi esterne: chiama SonarQube, CodeClimate o Snyk per scansioni enterprise del codice

• Strumenti personalizzati: integra sistemi e workflow proprietari della tua azienda

• Estensioni IDE: aggiungi comandi personalizzati e strumenti di navigazione

Installa i plugin da un registry oppure sviluppali internamente per la tua organizzazione, quindi configura gli eventi a cui rispondono. Insieme, hook e plugin creano una piattaforma estendibile 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 attività lunghe in cui non vuoi approvare ogni scrittura di file.
• Routines: agent 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 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 fare refactoring, documentare e fare debug di un file nella SDK Python di Supabase. Abbiamo migliorato la leggibilità del codice, aggiunto una 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 come sfruttare al meglio la finestra di contesto di Claude. Se vuoi costruire un progetto da zero, ti consiglio il nostro tutorial su Spec-Driven Development con Claude Code.