Prompt per la code review: 6 regole e un template

Perché quasi tutti i prompt per la code review generano rumore

La maggior parte dei prompt per la code review è un elenco di temi: «Esamina questo codice; guarda bug, vulnerabilità di sicurezza, prestazioni e leggibilità.» Il modello prende l’elenco alla lettera e sotto ogni voce scrive qualcosa. Il risultato è un commento lungo, gentile e in gran parte inutile. L’autore della pull request o lo legge tutto e ne scarta quasi tutto, o non lo legge affatto.

A cambiare davvero la risposta è la richiesta di prove: il modello scrive ciò che sa mostrare e tace ciò che non sa mostrare. In diffox, quando dividiamo una pull request tra 17 agenti specializzati, le istruzioni di ogni agente partono proprio da questa richiesta (come funziona lo raccontiamo in un articolo a parte). Le sei regole qui sotto vengono da quell’esperienza e dalla documentazione degli strumenti stessi.

Le sei regole

1. Chiedi una prova. Ogni rilievo deve indicare un input o uno stato concreto che produce il risultato sbagliato: «Con la lista vuota la media divide per zero.» Se il modello non sa costruire uno scenario così, deve tacere. Questa sola frase taglia gran parte dei commenti del tipo «si potrebbe fare attenzione anche a questo».
2. Chiedi una citazione letterale, non un numero di riga. I modelli non sono affidabili nel contare le righe; una citazione invece si può cercare e trovare nel file. Anche la documentazione di Anthropic consiglia la stessa tecnica: se il modello non trova una citazione che sostenga un’affermazione, deve ritirarla (fonte).
3. Limita l’ambito a questa modifica. La review serve per i problemi causati dalle righe che la pull request aggiunge o modifica. Se attribuisci all’autore di oggi ogni difetto del codice vecchio, il commento non lo legge più nessuno.
4. Lascia fuori le questioni di gusto e ciò che i tuoi strumenti controllano già. Formattazione, preferenze sui nomi, una riga di commento mancante non sono rilievi di review; non far riscrivere al modello ciò che segnalano già il linter e il type checker. La documentazione di Codex dice lo stesso: i controlli di formattazione e di lint si lasciano alla CI.
5. Definisci la gravità. Che cosa vuol dire «bloccante» e che cosa «minore» lo scrivi tu: un risultato sbagliato, una perdita di dati, una falla di sicurezza sono bloccanti; ciò che emerge solo in un percorso raro, o si riduce a un nome fuorviante, è minore. Senza una definizione ogni rilievo diventa «importante».
6. Fissa il formato della risposta. Ogni rilievo ha gli stessi campi: file, citazione, scenario, risultato sbagliato, gravità, correzione in una riga. Se non ci sono rilievi, il modello lo dice in una riga e si ferma, invece di riempire di parole una review vuota.

Le sei regole hanno una cosa in comune: descrivono un controllo che il modello può fare. «Fai attenzione» non si può controllare; «la citazione è nel file?» sì.

Copia questo template e adattalo al tuo repository

Il prompt qui sotto riunisce le sei regole in un solo testo. È scritto in inglese, perché tutti e quattro gli strumenti seguono senza problemi istruzioni in inglese; la lingua dei commenti la decide l’ultima riga. I punti da cambiare sono due: la definizione della gravità («Severity») e l’elenco «Do not report».

You are reviewing a pull request. Report only defects that this
change introduces or exposes.

A finding is valid only if you can state all three:
1. the code, quoted word for word from the changed lines;
2. a concrete input or state that reaches that code;
3. the wrong result that follows, and what the right one would be.
If you cannot state all three, do not report it.

Do not report: style, formatting, naming taste, missing comments,
anything a linter or a type checker already reports, or code this
change did not touch.

Severity:
- blocking: wrong result, data loss, security hole, or a crash on
  an ordinary path
- minor: wrong only on a rare path, or a name, comment or test that
  says something the code does not do

For each finding give: file, the quoted code, the scenario, the
wrong result, severity, and a one-line fix.
If you find nothing, write "No findings" and stop.
Write the findings in Italian.

Il template è volutamente corto. La documentazione di Claude Code dice che la lunghezza ha un costo: un file di istruzioni lungo diluisce le regole che contano di più. Quando aggiungi le tue regole, chiediti se ogni riga nuova cambia davvero un rilievo.

Quale file legge ogni strumento?

Dove scrivere il prompt dipende dallo strumento. La tabella qui sotto viene dalla documentazione di ciascuno dei quattro strumenti, letta il 15 ottobre 2026.

Fonte: la documentazione di ciascuno strumento, 15 ottobre 2026.

Due dettagli sfuggono spesso. In Claude Code REVIEW.md lo legge solo la Code Review su GitHub; il comando /code-review nel terminale non lo legge. Copilot invece legge le istruzioni dal branch head della pull request: una pull request che modifica il file delle istruzioni cambia anche le regole della propria review.

In Claude Code, per trasformare il tuo prompt in un comando scrivi una skill: metti il template nel file .claude/skills/revisione/SKILL.md e aggiungi in cima la riga !`git diff main...HEAD`. Questa riga esegue il comando e ne inserisce l’output nel prompt; quando scrivi /revisione, il modello trova il diff già pronto (documentazione delle skill).

Come scrivere le regole del tuo repository

Il template copre la parte generale; il valore vero sta nelle regole del tuo repository. Sono le cose che ripeti a ogni review: quale dato non può attraversare quale livello, quale effetto collaterale è pericoloso, quale contratto non si può rompere.

Una buona regola ha tre parti, e la documentazione di Codex le elenca tutte e tre: il comportamento da segnalare, perché conta, e la strada sicura o l’eccezione. La terza è quella che si dimentica più spesso: se non dici al modello qual è la strada giusta, segnalerà come errore anche il comportamento atteso.

• Debole: «Fai attenzione alle query sul database.»
• Forte: «Ogni query deve essere limitata al tenant del chiamante. Strada sicura: l’helper scoped(). Eccezione: i report per gli amministratori.»

Puoi chiedere prove anche a livello di repository. L’esempio della documentazione di Claude Code: un’affermazione sul comportamento deve indicare file e riga nel sorgente, non essere dedotta dai nomi. Questa sola regola riduce i falsi allarmi che fanno fare all’autore un giro a vuoto.

Quando un prompt non basta

Se a un solo prompt chiedi insieme sicurezza, concorrenza, test e rispetto delle regole, il modello divide l’attenzione e trova un po’ di ciascuna cosa. Sulle modifiche grandi funziona dividere il lavoro: ogni prompt cerca una sola cosa, con la stessa richiesta di prove.

Il secondo passo è controllare ciò che dice il modello. Un modello può scrivere cose convincenti ma sbagliate: cita una riga che nel file non c’è, o contesta codice che la modifica non ha toccato. Poiché chiedi una citazione, puoi controllarlo con un programma: la citazione è davvero in quel file, e appartiene alle righe modificate? Anche la documentazione della Code Review di Claude Code descrive lo stesso schema: ogni agente guarda una classe di problemi diversa, poi un passo di verifica elimina i falsi allarmi.

In diffox questi due passi li fa il prodotto stesso: ognuno dei 17 agenti specializzati del team cerca una sola cosa e mostra ciò che ha trovato con una citazione letterale del codice; la citazione la verifica il codice, non un modello. Anche le frasi che esprimono un obbligo nel file di regole nella radice del tuo repository (AGENTS.md o CLAUDE.md) vengono date agli agenti come regole di review.

Prova la regola su una pull request vera

Se un prompt è buono non lo capisci leggendolo. Il consiglio della documentazione di Codex è il più pratico: apri una pull request rappresentativa, chiedi una review, correggi le regole in base ai rilievi che arrivano, e restringi o elimina le istruzioni che producono rumore.

• Provala su una modifica che contiene una violazione che la regola deve individuare: la individua?
• Provala su una modifica che usa la strada sicura: tace?
• Provala su una modifica che non c’entra con il tema: tace anche lì?

Se fai esaminare due volte la stessa pull request puoi ottenere due risultati diversi; non prendere un singolo tentativo come risultato. Confronta i risultati prima e dopo aver aggiunto una regola, sempre sulle stesse poche pull request.