Code review automatica su PR con Claude Code: comandi custom e regole di progetto

Claude Code può fare un primo passaggio sistematico su ogni pull request prima del reviewer umano, non per sostituire la revisione, ma per filtrare problemi ovvi e liberare attenzione per quelli che contano. È l’utilizzo con il ritorno più immediato nei team piccoli, ed è quello che configuriamo per primo quando integriamo Claude Code in un flusso esistente in Snowinch. Parte dalla guida pratica al cluster Claude Code; qui entriamo nel dettaglio operativo sulla review.

Il problema della code review in team piccoli

In un team di 3–5 persone, la code review è spesso il collo di bottiglia più sottovalutato. Chi fa review è lo stesso che sta sviluppando qualcos’altro, l’attenzione è divisa, i problemi ovvi passano perché ci si concentra sulla logica di business, e i commenti si accumulano in modo non uniforme a seconda di chi fa la review quel giorno.

Il risultato è review di qualità variabile, non per mancanza di competenza ma per mancanza di tempo e contesto costante. Claude Code non risolve il problema della review umana, risolve il problema del rumore: i tipi non gestiti, i console.log dimenticati, le funzioni che violano le convenzioni del progetto, i casi limite non coperti. Quegli errori non dovrebbero arrivare al reviewer umano.

La configurazione che fa la differenza: CLAUDE.md

Il file CLAUDE.md nella root del progetto è il documento che trasforma Claude Code da assistente generico ad assistente contestuale. Senza di esso, la review è basata su convenzioni generali. Con esso, è basata sulle regole specifiche del tuo progetto.

Per la code review, le sezioni più importanti da includere:

# Convenzioni di progetto

## Architettura
- I controller non contengono logica di business: delegano ai service layer
- Le query al database passano sempre attraverso il repository layer, mai direttamente dai controller
- I tipi nullable vanno gestiti esplicitamente, no optional chaining senza fallback dichiarato

## Pattern proibiti
- Niente `any` esplicito in TypeScript, usa `unknown` e narrowing
- Niente `console.log` in produzione, usa il logger interno (`src/lib/logger`)
- Niente side-effect nelle funzioni pure, separare sempre query da mutation

## Naming
- I file di test seguono il pattern `*.test.ts` nella stessa directory del file testato
- Le variabili di ambiente vengono lette solo da `src/config/env.ts`, mai direttamente da `process.env`

## Aree critiche
- `src/billing/`, ogni modifica richiede attenzione particolare ai casi di concorrenza
- `src/auth/`, le modifiche ai middleware di autenticazione vanno verificate contro tutti i ruoli

L’esempio sopra è strutturale, adatta path e regole al tuo codebase. Questo file va trattato come documentazione viva: si aggiorna ogni volta che il team prende una decisione architetturale rilevante. Se una convenzione non è scritta qui, Claude Code non può applicarla.

Comandi custom per la review

Claude Code supporta comandi custom definiti nella directory .claude/commands/ del progetto. Sono file Markdown che definiscono istruzioni specifiche per un task ricorrente, la review di una PR è il caso d’uso ideale.

<!-- .claude/commands/review-pr.md -->
# Review PR

Analizza le modifiche nella staging area o nel diff fornito e produci una review strutturata.

## Cosa verificare

1. **Violazioni delle convenzioni** definite in CLAUDE.md, segnala ogni deviazione con il file e la riga
2. **Tipi non gestiti**, variabili nullable senza fallback, cast espliciti senza verifica
3. **Casi limite mancanti**, input vuoti, array vuoti, valori zero, concorrenza
4. **Side-effect non dichiarati**, funzioni che modificano stato esterno senza che sia evidente dalla firma
5. **Sicurezza di base**, input utente non sanitizzato, query costruite con concatenazione di stringhe

## Cosa non segnalare

- Preferenze stilistiche non coperte da CLAUDE.md
- Suggerimenti architetturali che richiederebbero refactoring significativo, aprire issue separata
- Problemi già presenti nel codice pre-esistente non toccato da questa PR

## Formato output

Per ogni problema trovato:
- File e riga
- Descrizione del problema
- Suggerimento concreto di fix (non generico)

Se non ci sono problemi, dillo esplicitamente, non inventare commenti per sembrare utile.

Il comando si invoca dalla sessione Claude Code con /review-pr. Puoi passargli il diff direttamente o lasciarlo leggere i file modificati nella working directory.

Workflow pratico

Il flusso che funziona in team piccoli senza introdurre overhead:

Prima del push: il dev invoca la review localmente sul branch prima di aprire la PR. Corregge i problemi ovvi, poi apre la PR.

# Nella working directory con le modifiche staged
claude /review-pr

Come check opzionale in CI: puoi integrare Claude Code in CI passandogli il diff della PR tramite la CLI. Non è un gate obbligatorio, è un commento automatico sulla PR che il reviewer umano può leggere prima di iniziare la propria review.

L’integrazione CI dipende dalla piattaforma e dalla versione della CLI disponibile, verifica la documentazione ufficiale di Claude Code per le opzioni di automazione aggiornate: docs.anthropic.com/claude-code.

Come primo step della review umana: il reviewer legge prima il report di Claude Code, verifica i problemi segnalati, poi fa la propria review concentrandosi sulla logica di business e sulle decisioni architetturali. I problemi meccanici sono già stati filtrati.

Cosa Claude Code trova bene e cosa no

Trova bene: violazioni di convenzioni esplicite, tipi non gestiti, pattern proibiti definiti nel CLAUDE.md, casi limite evidenti, codice duplicato che viola il DRY in modo esplicito.

Trova meno bene: problemi di concorrenza sottili che richiedono ragionamento sull’ordine di esecuzione, bug che emergono solo con combinazioni specifiche di stato, problemi architetturali che richiedono contesto di dominio non documentato nel codice.

La regola pratica: se il problema si può descrivere come una regola esplicita («non usare any», «i controller non contengono logica di business»), Claude Code lo trova. Se richiede intuizione sul dominio o ragionamento su scenari non documentati, non è affidabile.

Il rischio da evitare

Trattare l’output della review come definitivo senza leggerlo. Succede quando il team inizia a fidarsi ciecamente dello strumento, i falsi negativi (problemi non segnalati) passano inosservati perché si assume che se Claude Code non li ha trovati, non esistono.

La review automatica filtra il rumore, non garantisce la correttezza. Il reviewer umano resta responsabile, con meno rumore da gestire, ma con la stessa responsabilità di giudizio.

Sintesi operativa

• Il file CLAUDE.md è la configurazione fondamentale: senza regole esplicite di progetto, la review è generica e di scarso valore.
• I comandi custom in .claude/commands/review-pr.md definiscono cosa verificare, cosa ignorare e il formato dell’output, riducono la variabilità tra sessioni.
• Il workflow più sostenibile: review locale prima del push, non come gate CI obbligatorio.
• Claude Code trova violazioni di regole esplicite, non sostituisce il giudizio su logica di business e architettura.
• Leggere sempre l’output prima di agire su di esso: i falsi negativi esistono e non sono segnalati.