Personalizza Code Review

Regola ciò che Code Review segnala nelle tue pull request con REVIEW.md e CLAUDE.md: ricalibra la gravità, salta percorsi, aggiungi controlli e scopri quale copia viene applicata.

Puoi cambiare ciò che Code Review segnala nel tuo repository eseguendo il commit di istruzioni al suo interno. È così che riduci il volume dei nit, interrompi i commenti sui file generati o aggiungi una regola a cui il tuo team tiene. Inseriscile in uno di questi due file:

• CLAUDE.md: istruzioni di progetto che Claude Code legge per ogni attività, revisioni incluse. Code Review le legge come contesto di progetto e segnala le modifiche che le violano.
• REVIEW.md: istruzioni solo per le revisioni. Usalo per indicare cosa il tuo team vuole che venga segnalato, con quale gravità e cosa saltare.

Aggiungi REVIEW.md alla root del tuo repository ed esegui il merge. Poi proteggi il tuo branch predefinito.

[!NOTE]

Per cambiare quanto sono approfondite le revisioni o quando vengono eseguite, chiedi a un Owner di modificare il livello di revisione o l'impostazione Review runs.

Usa CLAUDE.md per le regole valide per l'intero progetto

Code Review legge i file CLAUDE.md del tuo repository come contesto di progetto. Una modifica che viola una delle loro regole diventa un rilevamento al livello di gravità adatto al problema.

Una revisione legge il CLAUDE.md nella root del tuo repository e i file CLAUDE.md nelle directory padre di ciascun file modificato. Il CLAUDE.md di una sottodirectory viene letto quando la pull request modifica un file in quel percorso.

Usa REVIEW.md per le regole specifiche della revisione

REVIEW.md è un file nella root del tuo repository che adatta Code Review al tuo repository. Su un branch protetto, puoi anche aggiungere un REVIEW.md nella maggior parte delle sottodirectory per aggiungere controlli sulle modifiche in quella sottodirectory, in aggiunta al file root.

Gli agenti che individuano i problemi e gli agenti che li verificano ricevono il suo contenuto come istruzioni di revisione del tuo repository, insieme alle indicazioni di revisione predefinite di Code Review. Il passaggio che scrive la revisione finale lo consulta prima di stabilire la gravità e scrivere il riepilogo.

Questo layout di esempio ha un file root e un file in una sottodirectory:

your-repo/
├── REVIEW.md            # Root file
├── services/
│   └── billing/
│       └── REVIEW.md    # Adds checks for changes under services/billing/
└── src/

Prima di fare affidamento su un file in una sottodirectory, proteggi il tuo branch predefinito e verifica cosa legge una revisione per la tua configurazione dei branch.

[!NOTE]

Il servizio Code Review e il comando /code-review locale sono due strumenti separati e leggono file diversi. Il servizio legge sia CLAUDE.md sia REVIEW.md. Il comando /code-review, che esegui all'interno di una sessione di Claude Code sulla tua macchina, legge i tuoi file CLAUDE.md e non REVIEW.md. Inserisci in CLAUDE.md le indicazioni che vuoi applicare in entrambi i contesti e riserva REVIEW.md alle regole specifiche della revisione delle pull request.

Quando un REVIEW.md in una sottodirectory non si applica

Code Review non applica un REVIEW.md all'interno o al di sotto di una sottodirectory con uno di questi nomi, qualunque sia il contenuto della sottodirectory. Il nome di una sottodirectory corrisponde solo se è identico per intero, con qualsiasi combinazione di maiuscole e minuscole e a qualsiasi profondità, quindi Tests corrisponde e integration-tests no:

• Test: test, tests, __tests__, testdata, fixtures, __fixtures__, golden, corpus, snapshots, __snapshots__
• Esempi: example, examples, sample, samples, demo, demos
• Codice generato: generated
• Codice di terze parti: vendor, third_party, third-party, thirdparty, node_modules, bower_components, external, extern, deps, godeps, pods, carthage, site-packages, contrib

Inserisci i controlli per queste sottodirectory nel REVIEW.md root, oppure nel REVIEW.md di una sottodirectory padre quando né quella sottodirectory padre né nessuna directory al di sopra di essa compare nell'elenco.

I restanti file REVIEW.md delle sottodirectory nei percorsi modificati da una pull request condividono un limite di 150.000 byte, senza contare il file root. Se il check run segnala che alcuni di essi non sono rientrati, accorcia i file per rispettare quel limite.

Esempio di REVIEW.md

Questo REVIEW.md ricalibra la gravità per un servizio backend, limita i nit, salta i file generati e aggiunge controlli specifici del repository.

# Review instructions

## What Important means here

Reserve Important for findings that would break behavior, leak data,
or block a rollback: incorrect logic, unscoped database queries, PII
in logs or error messages, and migrations that aren't backward
compatible. Style, naming, and refactoring suggestions are Nit at
most.

## Cap the nits

Report at most five Nits per review.

## Do not report

- Anything CI already enforces: lint, formatting, type errors
- Generated files under `src/gen/` and any `*.lock` file
- Test-only code that intentionally violates production rules

## Always check

- New API routes have an integration test
- Log lines don't include email addresses, user IDs, or request bodies
- Database queries are scoped to the caller's tenant

Scegli cosa scrivere in REVIEW.md

REVIEW.md è Markdown in formato libero che cambia ciò che una revisione individua e riporta. Non cambia il formato della revisione. Trova il problema che stai riscontrando, quindi aggiungi un'istruzione come quella mostrata. L'esempio usa le prime quattro.

• Vengono contrassegnate come Important le cose sbagliate: ridefinisci cosa significa 🔴 Important per il tuo repository. La calibrazione predefinita è pensata per il codice di produzione, e un repository di documentazione, un repository di configurazione o un prototipo potrebbero richiedere una definizione molto più ristretta. Indica quali classi di rilevamenti sono Important e quali sono al massimo Nit. Puoi anche alzare la gravità, ad esempio trattando qualsiasi violazione di CLAUDE.md come Important.
• Troppi nit: limita quanti commenti 🟡 Nit pubblica una singola revisione. Un limite come "riporta al massimo cinque nit" mantiene le revisioni utilizzabili.
• Commenti sui file generati o su ciò che la CI controlla già: elenca i percorsi e le categorie di rilevamenti per cui Claude deve saltare le segnalazioni. I candidati comuni sono il codice generato, i lockfile e le dipendenze vendorizzate, oltre a tutto ciò che la tua CI già applica, come il linting o il controllo ortografico. Per i percorsi che meritano una certa revisione ma non un esame completo, imposta invece una soglia più alta: "in scripts/, segnala solo se quasi certo e grave."
• Una regola del team non viene controllata: aggiungi le regole che vuoi vengano segnalate in ogni pull request, come "le nuove route API devono avere un test di integrazione."
• Rilevamenti che si rivelano errati: richiedi prove prima che una classe di rilevamenti venga pubblicata. Ad esempio, "le affermazioni sul comportamento richiedono una citazione file:line nel sorgente, non un'inferenza basata sui nomi" riduce i falsi positivi che altrimenti costerebbero all'autore un ulteriore scambio.

Alcune di queste istruzioni richiedono il file root su un branch predefinito protetto.

Limita REVIEW.md alle istruzioni che cambiano il comportamento della revisione e lascia il contesto generale del progetto in CLAUDE.md.

Includere altri file in REVIEW.md

Puoi suddividere le istruzioni di revisione in più file e importarli nel tuo REVIEW.md root. Usa questa possibilità quando REVIEW.md diventa lungo o quando conservi già le regole di revisione in un altro file.

Per includere un file, aggiungi al REVIEW.md root una riga che contenga solo @ e il nome del file. Code Review inserisce il contenuto del file al posto di quella riga, così si applica come parte di REVIEW.md. In questo esempio, il file root fornisce una propria istruzione e poi include due file di regole:

# Review instructions

Report at most five Nits per review.

@review-security.md
@review-api.md

Salva i file inclusi nella root del repository, accanto a REVIEW.md:

your-repo/
├── REVIEW.md
├── review-security.md
└── review-api.md

Code Review include i file quando legge REVIEW.md da un branch protetto, quindi verifica quale branch legge una revisione per il tuo repository:

• Branch protetto: Code Review inserisce il file incluso al posto della sua riga @
• Branch predefinito non protetto: la riga @ rimane in REVIEW.md come testo semplice. Se la pull request modifica il file indicato dalla riga, la riga viene omessa.

Quando una revisione non applica un file incluso, verifica ciascuno di questi punti:

• Posizione: sposta il file nella root del repository. Fatta eccezione per un file di skill, un percorso verso una sottodirectory come @docs/review-rules.md non viene incluso.
• Nome: fai corrispondere esattamente il nome del file, maiuscole e minuscole comprese, e usa un nome senza spazi. Una riga il cui nome non corrisponde a nessun file accanto a REVIEW.md rimane in REVIEW.md come testo semplice, e il check run non la segnala come inclusione saltata.
• Un solo livello: elenca ogni file nel REVIEW.md root. Una riga @ in un file incluso o in un REVIEW.md di una sottodirectory rimane come testo semplice (i file di skill sono diversi), e un link Markdown a un altro file non è un'inclusione.
• Limiti: includi al massimo otto file diversi e mantieni REVIEW.md e i file che include sotto i 150.000 byte complessivi. Un file che raggiungerebbe il limite di byte viene saltato per intero, non troncato. Il check run riporta quante righe di inclusione ha saltato per ciascuno dei due limiti.
• Link: mantieni i link Markdown a un massimo di 64 tra REVIEW.md e i file che include. I link a indirizzi http, https o mailto e ad ancore # non contano, e nemmeno i link in un file di skill. Oltre quel limite, la revisione salta l'intero REVIEW.md root, non solo i file inclusi. Il check run allora indica che le istruzioni non sono state applicate.
• Copia unita: esegui il merge del file incluso nel branch da cui viene letto REVIEW.md. La revisione legge entrambi dallo stesso commit, mai dalle modifiche della pull request stessa.

Includere un file di skill

Per fare in modo che le revisioni seguano le indicazioni che conservi in una skill, includi il SKILL.md della skill nel tuo REVIEW.md root. Code Review non esegue le skill.

Aggiungi @ e il percorso di SKILL.md, nella forma .claude/skills/<folder>/SKILL.md, su una riga a sé:

# Review instructions

Report at most five Nits per review.

@.claude/skills/api-review/SKILL.md

Treat any change under `migrations/` as Important.

Proteggi il branch da cui viene letto REVIEW.md, perché Code Review include un file di skill solo quando legge REVIEW.md da un branch protetto. Il file di skill conta ai fini dei limiti di otto file e 150.000 byte, e ha un proprio limite di 30.000 byte.

Scrivere una riga di skill che Code Review include

Usa un nome di cartella senza spazi. Una riga con uno spazio nel percorso rimane in REVIEW.md come testo semplice, e il check run non la segnala come inclusione saltata.

Se la riga @ per una skill viola una delle regole seguenti, Code Review non include la skill da quella riga:

• Percorso: scrivi il percorso come .claude/skills/<folder>/SKILL.md a partire dalla root del repository, con la cartella della skill direttamente sotto skills/. A differenza di un nome di file nella root, un percorso in questa forma che non corrisponde a nessun file viene saltato e conteggiato.
• Origine: copia le indicazioni da qualsiasi altro file sotto .claude/, o da una skill integrata, personale o di un plugin, in un file accanto a REVIEW.md. Non puoi includerli direttamente.
• File: esegui il commit di SKILL.md come normale file di testo. Code Review non segue un collegamento simbolico, che il collegamento sia il file stesso o una cartella nel suo percorso.
• Dimensione: mantieni SKILL.md entro 30.000 byte, frontmatter incluso
• Numero: scrivi al massimo otto righe di skill. Una riga ripetuta conta di nuovo ai fini delle otto.
• Blocchi in REVIEW.md: tieni la riga @ fuori dai code fence. Chiudi ogni commento HTML e ogni blocco <pre>, <script>, <style> o <textarea> sopra di essa.

Quando Code Review salta una riga di skill per aver violato la regola File, Dimensione, Numero o Blocchi, il messaggio sulle righe di inclusione saltate del check run la conteggia. Il messaggio compare solo quando la revisione applica REVIEW.md da un branch protetto.

Verificare cosa riceve una revisione da una skill

Quando la skill è inclusa, una revisione riceve il corpo di SKILL.md e nient'altro dalla skill, quindi verifica la skill rispetto all'elenco seguente.

• Frontmatter: ripeti nel corpo tutto ciò che serve a una revisione dal frontmatter, ad esempio le condizioni che description indica per l'uso della skill
• Comandi iniettati: scrivi esplicitamente ciò che un comando ! fornirebbe. Code Review non esegue il comando e sostituisce con un segnaposto l'intera riga o l'intero blocco che lo contiene.
• Sostituzioni: sostituisci $ARGUMENTS e le altre sostituzioni con testo fisso, perché una revisione non passa argomenti e le lascia come sono scritte
• File di supporto: copia in SKILL.md ciò che serve a una revisione, perché Code Review non carica script, file collegati o riferimenti @file
• Esclusioni e limiti sui Nit: scrivi le istruzioni che escludono rilevamenti o limitano i Nit in REVIEW.md o in un file accanto a esso, non nella skill. Code Review non accetta il testo di una skill come motivo per nessuna delle due cose.
• Link a file del repository: indica a parole a cosa punta un link o un riferimento @file. La revisione vede il percorso come testo semplice o come segnaposto.

Se modifichi i comandi !, $ARGUMENTS o i link della skill, cambi anche il suo funzionamento in Claude Code. Se il tuo team fa affidamento su questi elementi, copia le indicazioni in un file accanto a REVIEW.md e includi quel file al posto della skill.

Caratteri che Code Review modifica nel testo delle skill

Code Review modifica alcuni caratteri nel testo della skill, quindi i tuoi esempi di codice arrivano a una revisione nella forma seguente.

In SKILL.md:       Use `items[0]`, never `List<String>`.
The review reads:  Use ˋitems(0)ˋ, never ˋList< String>ˋ.

In SKILL.md:       Run `ps | grep api` and ask @alice.
The review reads:  Run ˋps ¦ grep apiˋ and ask @ alice.

Quando una regola dipende da uno di questi caratteri, indicala anche a parole.

Da quale branch viene letto REVIEW.md

Code Review legge REVIEW.md dal branch di base della pull request o dal branch predefinito, mai dalle modifiche della pull request stessa. Per cambiare il comportamento della revisione, esegui prima il merge della modifica a REVIEW.md.

Mantieni REVIEW.md sul tuo branch predefinito e proteggi quel branch. Quando una revisione legge la copia su un branch predefinito protetto, la prima riga della tabella seguente, rispetta queste istruzioni del file root:

• Abbassare la gravità di un rilevamento
• Escludere percorsi, file o classi di problemi
• Limitare i commenti nit

Scrivi le esclusioni e i limiti sui Nit in REVIEW.md o in un file accanto a esso, non in una skill inclusa.

Cosa conta come protezione del branch

Code Review considera come protezione queste impostazioni:

• Branch predefinito: una regola classica di protezione del branch o un ruleset
• Qualsiasi altro branch: solo un ruleset

Un ruleset conta quando limita gli aggiornamenti o richiede pull request con almeno un'approvazione. Se richiede pull request, deve anche annullare quell'approvazione a ogni nuovo push oppure richiedere che l'approvazione arrivi dopo l'ultimo push.

Cosa legge una revisione per ciascuna configurazione dei branch

Trova la situazione del tuo repository nella prima colonna della tabella seguente.

Se il check run menziona REVIEW.md, consulta Il check run menziona REVIEW.md.

Risorse correlate

• Code Review: cos'è il servizio e come viene eseguita una revisione
• Leggere e richiedere revisioni su una pull request: cosa significa ciascun livello di gravità e come appaiono i rilevamenti
• Configurare Code Review: il livello di revisione e quando vengono eseguite le revisioni, impostati da un Owner
• Revisione locale con /code-review: il comando /code-review, i suoi argomenti e i livelli di sforzo
• Memoria: come funzionano i file CLAUDE.md in Claude Code