Come rivedere il diff di Claude Code prima del commit

Claude Code termina il task e riassume: quattro file modificati, test verdi, nessun problema rimasto. Il riepilogo è utile per orientarti, ma non è l'oggetto che entrerà nel repository. Quell'oggetto è il diff.

Rivedere il diff significa decidere se ogni variazione appartiene all'incarico, se cambia il comportamento nel modo atteso e se il progetto resta utilizzabile e manutenibile. Puoi farlo da terminale, nella vista di Claude Code Desktop o sul web; il metodo resta lo stesso.

La documentazione di Git distingue i confronti tra working tree, area preparata e commit. Questa distinzione è importante: ciò che vedi nel progetto e ciò che stai per includere nel commit possono essere due insiemi diversi.

Il numero di righe non dice se il delta è corretto

Un indicatore +120 -40 misura dimensione testuale, non pertinenza. Cento righe possono essere un file generato atteso; una sola riga può allargare un permesso o cambiare una condizione critica.

Non usare la dimensione come verdetto. Usala per scegliere come leggere: un delta ampio richiede prima una vista per file e categorie; uno piccolo può essere esaminato riga per riga, senza saltare la prova del comportamento.

Chiedi a Claude di spiegare il motivo di ogni file, ma verifica la risposta sul diff. Se compare un file che il riepilogo non cita, è il diff ad avere ragione sullo stato del disco.

Fissa la baseline prima della lettura

Prima di attribuire tutte le modifiche alla sessione, controlla lo stato iniziale o almeno ricostruisci ciò che era già presente. Un working tree sporco può contenere lavoro tuo, di un collega o di un altro processo.

Da terminale, una sequenza minima è:

git status --short
git diff --stat
git diff

git status mostra anche file non tracciati, mentre git diff non li presenta come contenuto finché non entrano nell'index. La documentazione di git-status separa infatti differenze tra HEAD e index, tra index e working tree e percorsi non tracciati.

Annota commit di partenza, branch e modifiche preesistenti. Senza questa ricevuta potresti approvare o scartare lavoro che non appartiene a Claude.

Primo passaggio: controlla il perimetro

Nel primo passaggio non giudicare ancora l'algoritmo. Chiedi soltanto: il delta tocca ciò che l'incarico autorizzava?

Controlla:

• file aggiunti, modificati, rinominati o rimossi;

• dipendenze e lockfile;

• configurazioni, migrazioni e permessi;

• file generati o di build;

• documentazione che avrebbe dovuto cambiare e non compare;

• modifiche puramente stilistiche fuori dal percorso interessato.

Classifica ogni file come atteso, da spiegare o fuori scope. Un file fuori scope non diventa accettabile perché il test passa. Chiedi di separarlo o di motivare una nuova decisione prima di proseguire.

La matrice di approvazione di un workflow AI aiuta a distinguere un delta locale reversibile da un cambiamento che richiede un'autorità diversa.

Secondo passaggio: ricostruisci il comportamento

Ora leggi gli hunk come una storia causa-effetto. Per ogni variazione chiedi quale input incontra, quale ramo modifica e quale uscita diventa diversa.

Non leggere soltanto le righe verdi. Il contesto e le righe rimosse spiegano quale garanzia potrebbe essere scomparsa. Controlla condizioni, valori predefiniti, gestione degli errori, ordinamento e conversioni dei tipi.

Collega il comportamento al requisito. Se l'incarico chiedeva di impedire un invio doppio, il delta deve mostrare dove viene riconosciuto il duplicato e la prova deve esercitare proprio quel caso. Una nuova variabile chiamata isDuplicate non dimostra che il flusso la usi nel punto giusto.

Chiedi a Claude una contro-lettura: “Indicami tre input per cui questo diff potrebbe comportarsi diversamente da quanto previsto”. Gli esempi non sostituiscono i test, ma aiutano a trovare il confine da verificare.

Terzo passaggio: verifica operatività e manutenzione

Un comportamento corretto nel test locale può lasciare il progetto difficile da distribuire o mantenere. Nel terzo passaggio controlla ciò che circonda l'esecuzione.

Verifica:

• comandi di build, lint e test pertinenti;

• gestione di errori e log senza dati sensibili;

• compatibilità con configurazioni e dati esistenti;

• aggiornamento di documentazione ed esempi;

• assenza di segreti, percorsi personali o file temporanei;

• possibilità di annullare il cambiamento.

La checklist di verifica degli output AI completa la lettura tecnica quando il delta produce anche testo, dati o interfacce destinate alle persone.

Collega ogni file a motivo, rischio e prova

Una matrice compatta impedisce che alcuni file restino “di contorno”.

Se non sai compilare il motivo, il file non è pronto. Se il rischio non ha una prova e può causare un danno rilevante, il commit deve aspettare oppure ridurre il perimetro.

Questa matrice non richiede un documento lungo. Può stare nel riepilogo della sessione o nella descrizione del commit candidato, purché sia coerente con il diff effettivo.

Usa l'interfaccia senza delegarle il giudizio

Claude Code Desktop offre una vista diff per file, commenti sulle righe e una funzione di revisione prima del commit, secondo la guida Desktop. Sul web puoi aprire il diff, commentare punti specifici e iterare prima di creare una pull request, come mostra il quickstart web.

Usa questi strumenti per rendere preciso il feedback: “in questa riga la gestione dell'errore nasconde il codice originale” è più verificabile di “rivedi gli errori”. Dopo la correzione, riapri il diff e controlla il nuovo stato: il commento risolto non prova che il delta sia quello atteso.

La revisione assistita può trovare problemi ad alto segnale, ma non conosce automaticamente priorità, autorizzazioni e accordi non presenti nel repository. Il giudizio sul perimetro resta tuo o del revisore responsabile.

Rivedi separatamente ciò che stai preparando

Dopo aver scelto i file da includere, guarda l'insieme preparato per il commit. La documentazione Git indica che git diff --cached confronta l'index con HEAD: è quindi la vista di ciò che verrebbe confermato nello stato corrente.

Esegui:

git diff --cached --stat
git diff --cached

Confronta questo delta con la matrice. Controlla che non manchino test o documentazione e che non siano entrati file esclusi. Se prepari soltanto parte di un file, rileggi con attenzione il contesto: due hunk separati possono dipendere l'uno dall'altro.

Questo articolo si ferma qui. Creare il commit, fare push o aprire una PR sono azioni successive, con destinatari e conseguenze proprie.

Chiudi con una ricevuta di accettazione

Prima del commit salva una ricevuta breve:

• baseline e branch;

• file inclusi ed esclusi;

• requisito coperto;

• prove eseguite e relativo esito;

• rischi residui;

• revisore o decisione necessaria dopo il commit.

Non scrivere “diff verificato” senza dire come. Un controllo sintattico, un test di unità e una prova visuale osservano proprietà diverse. La ricevuta deve nominare il segnale reale.

Nel programma su Claude Cowork e Code di MAIKER HUB puoi portare una modifica concreta fino a questa soglia: perimetro leggibile, comportamento collegato al requisito e prove associate a ogni rischio importante.