Code Review con Claude Code: intercetta i bug prima che arrivino in produzione

Che cos’è Claude Code Review?

Claude Code Review è un sistema di code review multi-agente che esamina una PR nel contesto del repository e segnala potenziali bug, problemi di sicurezza e regressioni. GitHub Code Review esegue quegli agenti su una PR di GitHub, mentre la /code-review locale ti offre una revisione del tuo diff corrente direttamente da Claude Code.

La parola chiave qui è contesto. Una revisione tradizionale del diff chiede a qualcuno di ispezionare le righe modificate. Gli agenti di revisione di Claude esaminano quelle modifiche nel contesto del repository. Il flusso di lavoro GitHub impiega più agenti specializzati in parallelo, seguiti da verifica, deduplicazione e classificazione della gravità.

Per esempio, una modifica di 10 righe a una trasformazione pandas può dipendere dallo schema creato da un modello dbt a monte, dal livello di dettaglio di una tabella Snowflake e da assunzioni incorporate in una dashboard a valle.

Claude non approva né blocca una PR. GitHub Code Review riporta una conclusione del check neutra, quindi le tue regole di protezione dei branch restano invariate a meno che tu non costruisca una tua logica CI sull’output del check.

Tre superfici di revisione

Attualmente ci sono 3 modi principali per rivedere il codice con Claude Code.

Il comando /code-review locale esamina i commit del tuo branch. Puoi anche passargli un file, branch, numero di PR o intervallo di riferimenti Git specifico.

GitHub Code Review è progettata attorno alla PR stessa. A seconda della configurazione del repo, può eseguire la revisione una volta alla creazione della PR, dopo ogni push o solo quando qualcuno richiede una revisione con @claude review.

/code-review ultra è l’opzione più pesante. Anthropic chiama la funzionalità ultrareview e /ultrareview funziona come alias quando la funzionalità è disponibile per il tuo account. Esegue una flotta di agenti revisori in un sandbox remoto, con ogni bug segnalato riprodotto e verificato prima di comparire nei riscontri. Al momento è un’anteprima di ricerca e una revisione tipica richiede circa 5–10 minuti.

Cosa segnala Claude e cosa salta

Claude Code Review si concentra prima di tutto sulla correttezza. La documentazione di Anthropic distingue specificamente i bug che impattano la produzione dalle preferenze di formattazione e dalla copertura di test mancante.

I riscontri usano 3 livelli di gravità:

Questa distinzione è utile perché i data scientist hanno spesso opinioni molto diverse su cosa meriti tempo di revisione. Un suggerimento di naming tra revenue_df e weekly_revenue non è nella stessa categoria del raddoppio dei ricavi perché una join molti-a-molti è finita in una trasformazione.

Come configuri la code review in Claude Code?

La configurazione di Claude Code Review richiede passaggi diversi a seconda che tu voglia una revisione locale o una revisione del codice su PR GitHub. La /code-review locale non richiede la GitHub App e può essere eseguita prima ancora di aprire una PR. 

La GitHub Code Review richiede che un Owner o Primary Owner dell’organizzazione configuri la Claude GitHub App e selezioni i repository. Durante le PR review, conviene creare un file specializzato chiamato REVIEW.md che contiene regole specifiche solo per la revisione.

CLAUDE.md vs. REVIEW.md

CLAUDE.md e REVIEW.md hanno scopi diversi, e mescolarli è un modo facile per ottenere revisioni rumorose.

CLAUDE.md contiene istruzioni generali di progetto che Claude usa in vari compiti. Anche la code review legge quelle istruzioni e le violazioni introdotte di recente vengono segnalate come nits.  REVIEW.md, invece, è specifico per il comportamento di revisione e dice agli agenti di review cosa il tuo team vuole segnalare, saltare o trattare come Importante.

Per un repo dati in Python, terrei CLAUDE.md focalizzato su elementi come la struttura del repo, come eseguire pytest, se le trasformazioni usano pandas o polars e dove vivono i modelli SQL. 

Metterei le regole di revisione in REVIEW.md. Alcuni esempi di possibili regole:

• “Controlla ogni nuova trasformazione per un test corrispondente.”
• “Non loggare mai le credenziali."
• “Salta i file generati.”

Un piccolo  REVIEW.md potrebbe essere così:

# Review instructions

## Important findings

Report as Important:
- Incorrect joins or filters that can change dataset grain
- Missing tenant or customer scoping
- Secrets or credentials written to logs
- Silent changes to revenue or customer metrics

## Do not report
- Formatting already enforced by Ruff
- Generated files
- *.lock files

## Always check
- New transformations have tests
- Joins use the intended keys
- Datetime operations specify timezone assumptions
- Missing values are handled explicitly

Ti consiglio di mantenere REVIEW.md focalizzato, perché istruzioni lunghe possono diluire le regole importanti. L’implementazione attuale legge anche il file come istruzioni in chiaro, quindi dovresti inserire direttamente le regole invece di usare la scorciatoia @. 

A proposito, quando sviluppi in locale, /code-review non legge  REVIEW.md. Segue CLAUDE.md, mentre la pipeline di GitHub Code Review usa  REVIEW.md per istruzioni specifiche di revisione.

Se vuoi le stesse regole di review in locale e su GitHub, metti le regole generali in CLAUDE.md e ripeti dove serve le regole specifiche di review in REVIEW.md.

Per approfondire, ti consiglio di leggere la nostra guida per scrivere il miglior file CLAUDE.md.

GitHub App e modalità di trigger

GitHub Code Review viene configurata da un Owner o Primary Owner dell’organizzazione tramite le impostazioni amministrative di Claude. L’admin deve installare la Claude GitHub App, concederle l’accesso ai repo, selezionare i repo da rivedere e assegnare un comportamento di revisione a ciascun repo.

Esistono 3 diverse modalità di trigger:

Un’eccezione a tutte e 3: Claude non revisiona mai automaticamente una pull request da un fork. Qualcuno deve commentare @claude review su di essa.

A luglio 2026, i comandi manuali sono cambiati: 

• @claude review avvia una singola revisione e non iscrive la PR ai push futuri. 

• @claude review always avvia una revisione e iscrive la PR alle revisioni attivate dai push futuri.

• @claude review once si comporta come il comando semplice.

Se hai imparato Claude Code Review all’inizio del 2026, guide più vecchie potrebbero dire che @claude review iscrive la PR alle revisioni future, ma questo comportamento è cambiato a luglio 2026 e resta valido a settembre 2026.

Gli utenti Pro e Max che non hanno accesso alla GitHub Code Review dell’organizzazione possono saltare del tutto l’App e usare /code-review in locale, con /code-review ultra per una revisione più profonda.

Come si revisiona un diff in locale con /code-review?

Il comando /code-review locale revisiona il tuo branch corrente prima che tu apra una PR. Io parto sempre da qui perché intercetta i problemi mentre sto ancora lavorando e può evitare che fallisca la CI.

Il caso da rivedere

Immaginiamo di avere un repo e-commerce con una tabella ordini contenente order_id, customer_id, order_date, status e revenue, e creiamo weekly_revenue.py per calcolare i ricavi settimanali:

orders = load_orders()
customers = load_customers()

# Derive the reporting week from the order date
orders["week"] = orders["order_date"].dt.to_period("W").dt.start_time

weekly_revenue = (
    orders
    .merge(customers, on="customer_id", how="inner")
    .groupby("week", as_index=False)["revenue"]
    .sum()
)

A prima vista non sembra strano. La merge() è esplicita, il raggruppamento è leggibile e i ricavi sono aggregati dopo la join.

Il problema è che la tabella dei clienti contiene record storici multipli per alcuni clienti. Un cliente con 2 record ora produce 2 righe dopo la join, raddoppiando i ricavi attribuiti a quel cliente. Questo è esattamente il tipo di bug che è facile perdere quando leggi la trasformazione in locale senza controllare il livello di dettaglio della tabella.

Definisci l’ambito del diff

Dalla tua sessione Claude Code, esegui /code-review.

Il comando revisiona i commit del branch corrente rispetto al branch upstream, insieme alle modifiche non committate. Puoi anche mirare a un file, branch, PR o intervallo specifico, come main...feature/weekly-revenue.

Per esempio:

/code-review weekly_revenue.py

oppure:

/code-review main...feature/weekly-revenue

Puoi anche passare un livello di impegno, come /code-review high. A low e medium la revisione riporta solo i riscontri di cui è più sicura, mentre da high a max amplia la copertura al costo di più possibili falsi positivi. 

Usa i flag per guidare la revisione

Quando ti senti a tuo agio con il flusso di lavoro, due flag diventano utili: 

• --fix applica i riscontri al tuo working tree dopo la revisione.

• --comment li pubblica come commenti inline.

Claude esegue la revisione come subagente in background, quindi puoi continuare a lavorare mentre elabora la modifica. I riscontri tornano nella tua sessione al termine della revisione.

La revisione potrebbe riportare qualcosa di simile:

🔴 Important
weekly_revenue.py:9

The merge on customer_id can duplicate order rows because
customers contains multiple records per customer. This can
inflate revenue when a customer has more than one matching
customer record.

Verify that customer_id is unique in customers or join against
the intended current-record subset before aggregating revenue.

La revisione ha trovato una modalità di errore concreta e mi dà qualcosa che posso verificare rispetto allo schema reale, invece di chiedermi di fidarmi del giudizio di Claude.

Leggi i riscontri

Darei comunque un passaggio manuale a tutto prima di eseguire /code-review --fix. Per prima cosa, cerca il codice che costruisce customers, ispeziona i suoi vincoli di unicità e guarda i test attorno a weekly_revenue.py.

Se customers.customer_id è davvero univoco, il riscontro di Claude è un falso positivo. Se la tabella contiene una riga per cliente per data di validità, il riscontro è reale e la trasformazione va cambiata.

Il punto chiave è che il revisore di Claude guarda al comportamento del codice, mentre io resto responsabile di sapere cosa rappresentano i dati.

Puoi chiedere a Claude di indagare dopo la revisione:

Investigate the customer_id join finding.
Check how the customers table is built and determine whether
customer_id is unique at the point of this merge. Do not modify
the code yet.

Questo secondo passaggio è spesso più utile che chiedere a Claude di correggere alla cieca il commento. Trasforma la revisione in una breve indagine anziché in un esercizio di generazione di codice.

Come esegui Claude Code Review su una PR GitHub?

GitHub Code Review mette i riscontri di Claude direttamente sulla PR, così i revisori possono vedere il problema accanto al codice modificato. 

L’ordine conta perché la revisione si allega a una PR già esistente:

1. Esegui il push del branch weekly-revenue su GitHub con git push.

2. Apri la pull request. Claude può rivedere solo una PR aperta, quindi prima non succede nulla.

3. Se il repo è impostato su trigger automatico, la revisione parte automaticamente. Se è impostato su Manuale, pubblica @claude review come commento di PR di livello superiore per avviarne una.

Tre requisiti fanno spesso inciampare. Il comando deve essere un commento di livello superiore della PR e non una risposta a un commento inline, e ti servono permessi di scrittura, manutenzione o amministrazione sul repo. Il comando deve anche iniziare il commento, con once o always sulla stessa riga se aggiunti.

Attiva la revisione

La scelta che incide davvero sui costi è tra i due comandi manuali, non tra manuale e automatico.

@claude review esegue una revisione e lascia la PR non iscritta. @claude review always esegue una revisione e iscrive la PR, quindi ogni push successivo ne avvia una nuova.

Questo è il comportamento dopo luglio 2026 e a settembre 2026. Prima di quell’aggiornamento, il comando semplice @claude review iscriveva la PR alle revisioni future, quindi se stai seguendo un tutorial vecchio verifica prima questo aspetto.

La revisione spesso richiede circa 20 minuti, anche se Anthropic afferma che costi e durata dipendono da dimensione e complessità della PR. Ogni revisione viene anche fatturata separatamente tramite crediti di utilizzo invece di consumare l’utilizzo incluso nel piano Team o Enterprise. Se vuoi saperne di più sulla struttura dei costi, ti consiglio di leggere la nostra guida ai limiti di utilizzo di Claude Code.

Leggi i commenti inline e il check run

Quando la revisione termina, Claude pubblica commenti inline sulle righe pertinenti. Il check run di GitHub include anche un riepilogo della gravità, utile quando una PR ha più riscontri su weekly_revenue.py, modelli SQL e file di test.

Per esempio:

Il comento inline è dove indagherei il problema reale. Il check run è dove coglierei il quadro complessivo della revisione.

Nota: cliccare 👍 o 👎 non avvia un’altra revisione, e rispondere a un commento inline non fa rispondere Claude. Per ottenere un’altra revisione, correggi il codice e fai push, oppure pubblica @claude review come nuovo commento di PR di livello superiore.

La revisione inoltre non blocca il merge di per sé. Il check fornisce una conclusione neutra, anche se l’output include informazioni di gravità leggibili dalla macchina che un team può consumare tramite gh e jq se vuole costruire un proprio gate di merge.

Come gestisci i commenti di revisione di Claude?

L’idea è mantenere l’umano nel loop durante il ciclo di revisione. Ciò significa che ogni revisione di Claude richiede di decidere se ciascun riscontro è un bug reale, un miglioramento non bloccante o un falso positivo. Questo perché un revisore del codice può ispezionare il comportamento dell’implementazione senza conoscere ogni assunzione di business dietro a un dataset o a una metrica.

Uso una semplice decisione a 3 vie:

Quell’ultima categoria è importante. Un revisore che segnala 30 riscontri non è necessariamente migliore di uno che ne segnala 5. Un falso positivo su una merge di pandas può costare più tempo della modifica originale.

Fix, skip o push back

Se il bug delle righe clienti duplicate è reale, potrei chiedere a Claude di ispezionare il modello a monte e poi applicare la seguente correzione:

The customer_id finding is valid. Inspect the existing customer
model and update weekly_revenue.py to join only the current
customer record. Add a regression test for a customer with
multiple historical records, then run the relevant tests.

Claude può quindi ispezionare il repo, modificare il codice Python, aggiungere il test ed eseguire la suite di test.

Se vuoi lavorare dai commenti di revisione su GitHub, Claude Code può anche interagire con il repo tramite la CLI di GitHub (gh). L’aspetto importante è che sceglierei le correzioni specifiche che ritieni valide, invece di dargli l’intera revisione da “sistemare tutto”.

Questo mantiene gli sviluppatori nel loop di revisione:

1. Claude trova un possibile problema.
2. Io verifico il problema rispetto al codice e alle assunzioni sui dati.
3. Claude applica la correzione richiesta.
4. I test vengono eseguiti.
5. Claude rivede di nuovo il diff risultante.

Questo ciclo è molto più sicuro che trattare il primo output della revisione come una coda di refactoring automatizzata.

Di cosa ha ancora bisogno umano una data PR?

La modalità di errore che Claude non può coprire è il codice che gira correttamente ma fa comunque la cosa sbagliata. Tre versioni ricorrenti:

• Assunzioni fuori dal diff. Claude legge il tuo repo, non il tuo data warehouse, il tuo servizio di config o il contratto di un altro team. Una join può usare le chiavi giuste e comunque cambiare il livello di dettaglio del risultato, perché il numero di righe per chiave è una proprietà della tabella a monte, non del codice davanti a te.

• Definizioni note solo al tuo team. Se i ricavi vadano conteggiati al livello ordine, cliente o settimana è una decisione di business. Claude può dirti che un groupby() sommerà volentieri qualsiasi riga riceva. Non può dirti quale numero approva il tuo team finance.

• Assunzioni su tempo e tipi. 2026-08-27 significa un giorno UTC, un giorno lavorativo locale o una data di reporting impostata da un modello a monte? La coercizione silenziosa ha la stessa forma: operazioni tra colonne object, interi nullable, datetime con fuso e stringhe possono restituire qualcosa di plausibile cambiando silenziosamente il comportamento dei confronti.

Il leakage dei dati è l’esempio più netto della prima categoria. Una trasformazione di feature può unire un training set a una tabella con informazioni esistenti solo dopo la data di previsione. La join è valida, il conteggio righe è quello atteso e il modello è compromesso.

Quindi tratto Claude come un revisore del comportamento dell’implementazione, non il proprietario della definizione.

Quando usare Code Review vs Ultrareview?

Usa /code-review per un feedback rapido in locale ed /code-review ultra per un passaggio pre-merge più approfondito. Entrambe rivedono il codice, ma /code-review è pensata per l’iterazione, mentre l’ultra esegue più agenti remoti e verifica in modo indipendente i bug segnalati.

Anthropic descrive attualmente l’ultra review come un’anteprima di ricerca. Gli abbonati Pro e Max ricevono 3 esecuzioni gratuite una tantum che non si rinnovano; in seguito una revisione costa tipicamente 5–25 $, a seconda della dimensione della modifica. Gli utenti Team ed Enterprise non ricevono tali esecuzioni gratuite e la funzionalità non è disponibile su Amazon Bedrock, Google Cloud Agent Platform, Microsoft Foundry e per le organizzazioni con Zero Data Retention abilitato.

La differenza importante è la verifica. /code-review ultra invia lo stato del repo a un sandbox remoto ed esegue una flotta di agenti revisori, con i bug segnalati riprodotti in modo indipendente prima di essere restituiti come riscontri.

Non la eseguirei a ogni commit. Se sto cambiando il nome di una variabile in un notebook Python o aggiustando la formattazione di un modello dbt, una /code-review locale basta. Se sto cambiando la logica di generazione delle feature per un modello in produzione, riscrivendo una trasformazione dei ricavi o modificando un’aggregazione a livello cliente, ha più senso un passaggio di revisione extra.

C’è anche un dettaglio di naming utile. Il comando documentato è /code-review ultra e /ultrareview è un alias che funziona quando ultrareview è disponibile per il tuo account. Guide più vecchie presentano spesso /ultrareview come comando principale, ma la documentazione di Anthropic tratta ora la revisione cloud profonda come parte della famiglia di comandi /code-review, e /code-review ultra torna a una revisione locale quando la funzionalità cloud non è disponibile.

Esegui l’ultra review sulla stessa PR

Dal repo, esegui:

/code-review ultra

Per rivedere direttamente una PR GitHub:

/code-review ultra <pr#>

Senza argomenti, /code-review ultra confronta il tuo branch corrente con il branch predefinito e include modifiche non committate e in stage. Una revisione del branch si ferma intorno a 500 file modificati e 8.000 righe cambiate per impostazione predefinita, sebbene Anthropic noti che questi numeri possono cambiare. Se il tuo diff è troppo grande, fai push del branch e rivedilo come PR.

Con un numero di PR, l’ambiente remoto clona la PR da GitHub e nulla viene caricato dalla tua macchina.

Prima di iniziare, Claude mostra l’ambito della revisione, le esecuzioni gratuite rimanenti e il costo stimato. Dopo la conferma, la revisione gira in background, così puoi continuare a usare Claude Code mentre gli agenti remoti lavorano.

Per il nostro esempio weekly_revenue.py, confronterei i riscontri invece di dare per scontato che la revisione più profonda sia per forza corretta.

Se /code-review segnala la join sui clienti e l’ultra review riproduce in modo indipendente la stessa duplicazione dei ricavi, la mia fiducia in quel riscontro aumenta. Se l’ultra review lo ignora perché la tabella a monte garantisce l’unicità, ispezionerei le evidenze di entrambe le revisioni e la definizione reale del modello prima di cambiare il codice.

Questa è una proprietà utile di più revisori: il disaccordo ti dà qualcosa da indagare.

C’è anche una considerazione di costo. GitHub Code Review attualmente costa in media 15–25 $ per revisione, mentre l’ultra review costa in genere 5–25 $ dopo le esecuzioni gratuite per Pro e Max. I costi di GitHub Code Review sono separati dall’utilizzo incluso nel piano, e Anthropic fornisce controlli di spesa per le organizzazioni.

Se lavori da solo, /code-review locale più un occasionale /code-review ultra è un flusso di lavoro iniziale ragionevole. Se sei in un piano Team o Enterprise e vuoi che ogni PR abbia una revisione automatizzata, ha più senso GitHub Code Review.

Un flusso di lavoro pratico per Claude Code Review

Il flusso di lavoro utile non è “esegui Claude prima di ogni merge”. È una sequenza in cui ogni revisione avviene in un punto diverso dello sviluppo, perché ognuna costa diversamente e intercetta una classe diversa di problemi.

Ecco il processo che userei per una modifica in produzione:

Write code
	   ↓
Run tests and data checks
	   ↓
/code-review
	   ↓
Fix verified findings
	   ↓
Open GitHub PR
	   ↓
GitHub Code Review
	   ↓
Human triage
	   ↓
/code-review ultra for higher-risk changes
	   ↓
Final tests
	   ↓
Human merge

La revisione locale intercetta i problemi quando sono economici da correggere. La revisione su GitHub fornisce al team un registro condiviso dei riscontri, mentre l’ultra review offre un secondo parere a maggior sforzo prima di un merge rilevante.

Controlli aggiuntivi per data scientist

Per il lavoro sui dati, aggiungerei 4 controlli attorno a Claude invece di aspettarmi che il modello svolga l’intera revisione:

• Controlla i conteggi righe e il livello di dettaglio del dataset prima e dopo join importanti
• Esegui test unitari o di integrazione attorno a trasformazioni e logica delle feature.
• Controlla il leakage durante la costruzione delle feature di machine learning.
• Valida le metriche di business rispetto a una query o dashboard di riferimento.

Claude può partecipare a tutte e 4 le attività, ma il risultato atteso dovrebbe derivare da codice, test o dati, non dalla spiegazione di Claude.

Considerazioni finali

Claude Code Review funziona meglio quando lo tratto come un altro ingegnere nel thread di revisione, non come un timbro di approvazione automatizzato.

Il comando /code-review locale ti dà una revisione rapida prima che esista la PR. GitHub Code Review porta i riscontri multi-agente nella PR per le organizzazioni Team ed Enterprise, mentre /code-review ultra ti offre una revisione remota più profonda quando la modifica merita un ulteriore passaggio.

Partirei in piccolo. Inserisci /code-review nel tuo normale flusso di lavoro sul branch, scrivi un breve REVIEW.md per le revisioni su GitHub e prova /code-review ultra sulle modifiche in cui un merge sbagliato ti costerebbe davvero qualcosa.

Per i concetti di modello sottostanti, il nostro corso Introduzione ai modelli Claude fornisce il contesto più ampio, mentre GitHub Foundations e Concetti GitHub intermedi coprono il workflow Git e GitHub su cui si innesta Code Review. Per ulteriore ispirazione su come fare triage dei repo GitHub con Claude, consiglio anche la nostra guida al connettore di Claude Code.