Claude Code 2.1: una guida con esempi pratici

Claude Code è uno strumento di coding agentico sviluppato da Anthropic che gira direttamente nel tuo terminale e può operare anche tramite un’interfaccia web connessa. Invece di lavorare su prompt isolati, Claude Code comprende l’intera repository, sa ragionare tra i file, modificare il codice ed eseguire tool. 

Rispetto alle versioni precedenti, incentrate soprattutto sull’assistenza interattiva al codice, Claude Code 2.1 offre supporto aggiuntivo per agenti, hook e skill riutilizzabili che possono influenzare attivamente come e quando avvengono le modifiche al codice.

Claude Code è pensato per gli sviluppatori che vogliono un’assistenza IA integrata direttamente nei flussi di lavoro reali, senza dover passare continuamente dall’editor a un’interfaccia di chat. Sebbene sia ancora in anteprima di ricerca, dimostra già una forte utilità pratica nei flussi di sviluppo reali. 

Se vuoi saperne di più sui modelli Claude, ti consiglio il corso Introduction to Claude Models. Puoi anche dare un’occhiata al nostro tutorial su Claude Cowork.  

Cosa c’è di nuovo in Claude Code 2.1?

Claude Code 2.1 si basa sull’esperienza core nel terminale introducendo una serie di upgrade che rendono i flussi guidati da agenti più flessibili. Questi cambiamenti estendono il modo in cui Claude Code ragiona su una codebase e come gli sviluppatori interagiscono con essa durante attività di sviluppo reali.

Alcune delle aggiunte più notevoli in Claude Code 2.1 includono:

• Hook per agent e skill nel frontmatter, che permettono agli sviluppatori di imporre controlli e vincoli prima che vengano applicate modifiche al codice.
• Supporto alle skill ampliato con contesto forked, hot reload e definizioni di skill personalizzate, rendendo i flussi riutilizzabili più flessibili e potenti.
• Invocazione di skill con slash (/) per un accesso rapido alle azioni usate di frequente durante le sessioni interattive.
• Gli agent in Claude Code 2.1 non interrompono più il ragionamento quando un’invocazione di tool viene negata, permettendo ai flussi di continuare senza interruzioni.
• Il tool supporta risposte controllate per lingua, particolarmente utili per documentazione multilingue, revisioni e collaborazione in team.
• Permessi wildcard per i tool, come Bash(*-h*), offrono controlli di automazione più granulari.
• La CLI ora supporta Shift+Enter per input su più righe, migliorando l’esperienza di scrittura interattiva senza richiedere configurazioni aggiuntive.

In questa guida, ci concentriamo su una serie di esperimenti pratici che mostrano come queste nuove funzionalità si applicano a progetti reali.

Configurazione dell’esperienza web cloud-based di Claude Code

Claude Code 2.1 è disponibile come esperienza web eseguita interamente nel cloud. Questa modalità è particolarmente utile per flussi collaborativi, revisioni di pull request e automazione a livello di repository senza richiedere un setup locale.

Passo 1: Accedi e apri Claude Code

Per iniziare, vai su https://claude.ai/code, e atterrerai sull’interfaccia di Claude Code (Research Preview). 

Passo 2: Collega Claude Code a GitHub

Per lavorare con repository reali, Claude Code ha bisogno dell’accesso a GitHub. Clicca su Connect to GitHub, che installerà la Claude GitHub App. 

Durante l’autorizzazione, GitHub chiederà il permesso di connettersi alle repository per:

• Verificare la tua identità GitHub
• Visualizzare a quali repository Claude può accedere
• Agire per tuo conto (ad esempio, creare branch o commit)

Puoi scegliere tra:

• Tutte le repository, oppure
• Solo alcune repository selezionate (consigliato per un controllo più stretto)

I permessi tipici includono:

• Accesso in lettura ai metadati della repository e ai check
• Accesso in lettura e scrittura a codice, issue, pull request e workflow

Clicca su Install & Authorize; potrai modificare o revocare l’accesso in seguito direttamente dalle impostazioni delle app su GitHub. Questo passaggio è necessario perché Claude Code possa leggere le repository, aprire pull request e pushare commit quando lavori nell’ambiente web.

Passo 3: Crea un ambiente cloud

Prima di iniziare la tua prima sessione, Claude Code ti chiede di creare un ambiente cloud. Questo ambiente controlla l’accesso alla rete e i limiti di esecuzione di Claude.

Le opzioni disponibili includono:

• Nessuno: Nessun accesso a internet, utile soprattutto per la massima sicurezza.
• Trusted (consigliato): Fornisce accesso a sorgenti di pacchetti verificate.
• Completo: Fornisce accesso illimitato a internet.

Per la maggior parte dei casi d’uso, l’opzione Trusted offre il miglior equilibrio tra sicurezza e flessibilità.

Passo 4: Avvia una sessione web

Dopo aver completato il setup, verrai portato all’editor web di Claude Code, come nello screenshot qui sotto.

Da qui puoi:

• Selezionare una repository e un branch
• Eseguire refactor e review
• Creare nuovi branch e commit
• Riprendere sessioni precedenti (se presenti)
• Passare tra repository senza cambiare ambiente

Configurazione dell’esperienza CLI basata su terminale di Claude Code

La CLI è il modo più diretto per lavorare con Claude Code 2.1. È ideale per lo sviluppo locale, refactor passo dopo passo e situazioni in cui vuoi un controllo granulare su ciò che Claude fa nella tua repository.

Passo 1: Installazione

Claude Code può essere installato direttamente dal terminale con un installer specifico per piattaforma.

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

Al termine dell’installazione, dovresti vedere un messaggio di conferma con la versione di Claude Code e il percorso di installazione. Per opzioni di setup aggiuntive, fai riferimento alla guida ufficiale di configurazione.

Passo 2: Primi passi

Dopo l’installazione, vai alla root del tuo progetto e avvia Claude Code:

cd your-project-directory
Claude Code

All’avvio, Claude Code scansiona immediatamente la repository e costruisce una comprensione iniziale della codebase. 

Questo contesto iniziale permette a Claude Code di ragionare in modo più efficace nei passaggi successivi.

Sperimentare con Claude Code 2.1

Per questa demo, ho utilizzato uno dei miei progetti da GPT 5.2. Ecco una rapida panoramica del progetto.

Una volta che Claude Code ha accesso a ogni file e cartella all’interno della cartella, possiamo iniziare a sperimentare.

Refactor usando skill con contesto forked 

Come parte della valutazione di Claude Code 2.1, ho eseguito un refactor a livello di repository per migliorare la pipeline. Questo esperimento evidenzia le skill con contesto forked, in cui Claude può ragionare su più file invece di apportare modifiche isolate a singoli file.

Prompt:

Refactor the CSV parsing and slide generation logic across the repository.
Improve readability, split responsibilities, and avoid duplicated logic.

Per prima cosa, Claude genera un piano di refactoring dettagliato, includendo la struttura dei moduli proposta, i punti di duplicazione e una sequenza di implementazione, quindi chiede l’approvazione prima di cambiare qualsiasi cosa. 

Una volta approvato, Claude applica il refactor in modo incrementale, mostrando diff e avanzamento man mano che procede.

Usando Claude Code, ho ottenuto i seguenti miglioramenti:

• Suddivisione delle responsabilità tra moduli: Claude ha separato il caricamento CSV, le trasformazioni, la costruzione Excel, la generazione PowerPoint e la pianificazione LLM (sostanzialmente tutti i moduli) in componenti dedicati.
• Riduzione della logica duplicata: Ha centralizzato le utility ripetute (come il rilevamento delle colonne e la formattazione) e spostato le costanti condivise in un layer di configurazione comune.
• Miglior manutentibilità: Claude ha anche ridotto la dimensione di app.py mantenendo coerente il comportamento esterno dell’applicazione.

Ecco un confronto della struttura del progetto e dell’output del refactoring prima e dopo le modifiche.

Prima:

Dopo:

Infine, ho provato lo stesso refactor in Claude Code Web. La differenza chiave è nel workflow:

• CLI procede passo dopo passo con approvazioni esplicite.
• Web può pushare il refactor direttamente in un nuovo branch, comodo per collaborazione e workflow basati su PR.

Infine, Claude ha fatto il refactor e pushato il codice in un branch.

Hook di validazione pre-edit

Le pipeline dati spesso falliscono per un motivo semplice: lo schema CSV di input non corrisponde a quanto si aspetta il codice. In Claude Code 2.1, puoi ridurre questa classe di errori usando i pre-edit hook. Questa nuova funzionalità consente a un agent di eseguire controlli di validazione prima che Claude possa modificare il codice.

In questo esempio, ho chiesto a Claude Code di creare un agent che validi la struttura del CSV prima di applicare qualsiasi modifica.

Prompt:

Create a Claude Code agent that validates the CSV schema before modifying any code. The agent should reject edits if the CSV schema is unclear.

Per prima cosa, Claude Code ha generato un agent di validazione dello schema CSV e lo ha collegato al workflow in modo che possa agire da gatekeeper. L’output della CLI mostra che Claude non ha creato un singolo script, ma ha assemblato un piccolo sistema di validazione che include:

• Un modulo core di validazione dello schema che controlla colonne richieste, valori mancanti e coerenza di base.
• Un hook di gatekeeping pre-edit che esegue la validazione automaticamente prima di procedere con le modifiche.
• Infine, una suite di test e alcuni esempi d’uso per verificare il validator su casi CSV validi/non validi.

In pratica, il workflow diventa semplice:

• Claude esegue automaticamente i controlli dello schema prima di apportare qualsiasi modifica al codice, imponendo una precondizione.
• Se lo schema è poco chiaro o non valido, l’agent blocca duramente le modifiche e restituisce messaggi di errore utilizzabili per guidare la correzione.
• Una volta superata la validazione, Claude procede con le modifiche, mantenendo i cambiamenti guidati da guardrail e prevedibili.

L’output web mostra un risultato simile, ma con una differenza chiave. Claude Code Web può pushare le modifiche direttamente in un nuovo branch, includendo il modulo di validazione, l’integrazione dell’hook, la documentazione e i test. 

In generale, Claude Code 2.1 applica guardrail prima che avvengano le modifiche incorporando hook direttamente in agent e skill. Questo rende gli hook particolarmente preziosi nei progetti data-heavy, dove la correttezza dell’input è spesso una fonte di bug maggiore rispetto al codice stesso.

Skill slash-command per attività ripetute

Claude Code 2.1 ha introdotto skill riutilizzabili richiamabili con slash, workflow autonomi che possono essere invocati in modo interattivo all’interno di una sessione Claude o eseguiti direttamente dalla riga di comando. 

In questo esempio, creiamo una skill riutilizzabile /generate-slides che converte un file CSV in una presentazione PowerPoint professionale.

Prompt:

Create a reusable skill called /generate-slides that converts a CSV into a PPT.

Suggerimento: usa /statusline per configurare una status line personalizzata che appare sotto il prompt di input (utile per mostrare repo, branch o modalità).

Claude Code genera una definizione di skill completa in .claude/skills/, inclusi documentazione, logica di validazione e un entry point Python eseguibile.

• Creazione della skill: Claude scrive una skill generate-slides completamente documentata, descrivendone scopo, input, passaggi di validazione e flusso di esecuzione.
• Validazione dello schema: la skill valida lo schema del CSV prima di qualsiasi elaborazione, garantendo qualità dei dati e messaggi di errore chiari.
• Esecuzione: la skill può essere eseguita direttamente dal terminale, comportandosi come un tool da riga di comando standalone.
• Gestione degli errori: file mancanti, schemi non validi o API key assenti generano errori chiari e utilizzabili.
• Automazione: un singolo comando genera artefatti Excel, grafici e un deck PowerPoint.

Puoi testare la skill in locale con:

python .claude/skills/generate-slides.py --csv-file kpis.csv

Nota: assicurati di aggiungere la tua API key prima di eseguire. 

Le skill richiamabili con slash trasformano Claude Code in un motore di workflow, non solo in un assistente. Invece di ripetere il prompt per lo stesso task, lo definisci una volta e lo riusi tra progetti, sessioni e ambienti. Puoi osservare la struttura della repository aggiornata qui sotto, che riflette l’aggiunta della nuova skill.

Questo esempio dimostra come:

• Le skill possono essere invocate in modo interattivo dalla CLI.
• Le skill generate da Claude si integrano pulitamente nelle codebase esistenti.

Sub-agent asincroni e background

Uno dei maggiori punti di attrito negli strumenti di coding con IA è il "tempo di attesa": fissare un cursore lampeggiante mentre l’IA pensa o esegue una lunga suite di test. Claude Code 2.1 risolve questo problema con i Sub-agent asincroni.

Ora puoi spostare in background task di lunga durata—come un refactor complesso, un’esecuzione di test o una revisione della documentazione—usando Ctrl+B. Questo libera subito il terminale, permettendoti di:

• Continuare a interrogare la codebase.
• Accodare un secondo task in parallelo.
• Rivedere manualmente i file mentre Claude lavora.

Per esempio, mentre Claude sta facendo il refactor del modulo app.py (che potrebbe richiedere minuti per pianificare ed eseguire), puoi premere Ctrl+B e chiedere subito: "Mentre quello gira, spiega la logica di autenticazione in auth.py."

Quando il task in background termina, Claude ti avvisa e puoi reintegrare il contesto nel tuo flusso principale. Questo trasforma di fatto Claude Code da un’interfaccia di chat single-thread a un partner di sviluppo multi-thread, rispecchiando il modo di lavorare dei senior engineer.

Output controllato per lingua 

Claude Code 2.1 può essere configurato per rispondere in una lingua specifica, utile per team multilingue, documentazione localizzata e walkthrough del codice non in inglese. In questo esempio, abbiamo chiesto a Claude di spiegare l’intera pipeline di generazione delle slide in giapponese.

Prompt:

Explain the slide generation logic in Japanese.

Claude ha risposto in giapponese e ha prodotto una spiegazione strutturata del flusso end-to-end. Come mostrato nell’output, non si è limitato a tradurre un riassunto, ma ha anche mappato la pipeline in fasi chiare e fatto riferimento ai moduli rilevanti coinvolti in ogni passaggio. L’output della CLI mostra:

• Giapponese end-to-end: la risposta rimane in giapponese dall’inizio alla fine, inclusi titoli e punti elenco.
• Flusso passo dopo passo: Claude scompone la pipeline in fasi distinte (validazione CSV, elaborazione dati, workbook Excel, pianificazione LLM e creazione delle slide).
• Riferimenti consapevoli della codebase: indica i file e le directory rilevanti spiegando il ruolo di ciascun componente.
• Formattazione in stile documentazione: l’output sembra documentazione interna, facile da riusare in un README o in una guida di onboarding.

Nota: ho testato questo comportamento solo nella CLI per questo esempio, ma la stessa capacità di controllo della lingua fa parte di Claude Code 2.1 nel suo complesso.

Sulla carta è una piccola funzionalità, ma in pratica è un grande vantaggio di produttività quando documentazione e review devono avvenire in lingue diverse dall’inglese.

Comandi di Claude Code 2.1

Ecco alcuni comandi da provare con Claude Code.

Conclusione

In questa guida abbiamo esplorato Claude Code 2.1 eseguendo esperimenti pratici sia su workflow CLI che web. Abbiamo usato Claude Code per rifattorizzare una repository esistente con skill a contesto forked, imporre garanzie sui dati con hook di validazione pre-edit, creare skill riutilizzabili richiamabili con slash e generare spiegazioni controllate per lingua direttamente dalla codebase.

Questi esempi mostrano come Claude Code 2.1 vada oltre la semplice modifica assistita dall’IA verso flussi di sviluppo più guidati da agent. Sebbene Claude Code 2.1 sia ancora in anteprima di ricerca, dimostra già un forte valore pratico in progetti reali.