Codex per la code review: far rivedere le PR all'IA senza lasciarle cambiare tutto

Arriva una PR da 800 righe con titolo fix e una description che dice solo “sistemate alcune cose”. Guardi il diff, non capisci dove sia il rischio principale e non vuoi leggere ogni file modificato riga per riga. Qualcuno scrive nel PR comment: @codex review for auth bypass and PII logging. Dopo qualche minuto compare un inline comment che punta a logger.info(user.email).

Ora devi decidere: lasci che Codex faccia il fix, lo correggi tu, oppure chiedi prima al team di business se quel log è conforme? Questa guida chiarisce condizioni di attivazione, scrittura delle Review guidelines, significato di P0/P1, flusso di trattamento e confine della conferma umana.

@codex review non è una formula magica

@codex review non è l’interruttore che lascia l’IA modificare automaticamente il codice. È solo una richiesta a Codex: leggere il PR diff e pubblicare review comments in base alle tue regole. Se parte, che cosa controlla e come gestisci il risultato dipendono da prerequisiti e giudizio umano.

Trigger e impostazioni di GitHub Cloud

Per usare Codex per la code review, il repository deve avere Codex Cloud configurato e tu devi poter accedere ai code review settings. Ci sono due modi per avviarlo: scrivere @codex review in un commento della PR, oppure attivare Automatic reviews nei settings, così Codex pubblica una review quando una nuova PR viene opened for review.

Dopo l’avvio, Codex legge il PR diff, segue la repository guidance, cioè le Review guidelines in AGENTS.md, e pubblica inline comments come una normale GitHub code review. @codex review non equivale ad approval. Automatic reviews non significa approvazione automatica. Modifiche sensibili come auth, payment e data migration richiedono ancora conferma umana.

Puoi combinare trigger di PR e workflow CI con branch protection rules, così l’AI review resta solo uno dei controlli. Per configurare i trigger PR, vedi l’articolo precedente sui trigger PR di GitHub Actions.

Concentrarsi su P0/P1, non su un diario infinito

Di default Codex segnala solo problemi con priorità P0/P1. P0 indica un problema bloccante: security regressions, auth bypass, data loss. P1 indica un problema da correggere: performance, concurrency, logging sensitive data.

KiloClaw - OpenClaw gestito per enterprise: orchestrazione agenti IA e routing intelligente

Inizia →Pubbl.

Questo focus evita l’esplosione dei review comments, mantiene alto il segnale e riduce il rumore di scarso valore. Puoi sovrascrivere la regola di default nella sezione Review guidelines di AGENTS.md. Per esempio, puoi chiedere di guardare solo auth bypass, PII logging e concurrency, ignorando code style, lasciato a Prettier, e minor performance fuori dagli hot path. La sezione successiva mostra come scrivere Review guidelines concrete.

Le Review guidelines stanno in AGENTS.md, non in ogni PR comment

Le Review guidelines decidono focus e priorità di Codex review. Dovrebbero stare nel file AGENTS.md del repository, non essere ripetute in ogni PR comment.

Lettura a livelli di AGENTS.md e scrittura delle Review guidelines

Codex legge AGENTS.md prima di iniziare. La lettura parte dal Git root e scende fino alla directory di lavoro corrente; le istruzioni più vicine sono più specifiche. Per esempio, un AGENTS.md dentro auth/ può sovrascrivere le regole di progetto e concentrarsi solo sui rischi legati ad auth.

Una tipica sezione Review guidelines:

## Review guidelines

Concentrati solo su questi rischi:
1. Security regressions(auth bypass、path traversal)
2. PII logging(user.email、phone number)
3. Concurrency issues(race condition、deadlock)

Non concentrarti su:
- Code style(automatizzato con Prettier)
- Minor performance(non hot path)

Il vantaggio: tutte le PR condividono la stessa base di regole, non devi ripeterle ogni volta nei commenti e l’AGENTS.md vicino ai changed file può essere più specifico.

Attenzione al limite di lunghezza: i file di istruzioni sono vincolati da project_doc_max_bytes, che di default è 32 KiB. Un file troppo lungo può essere troncato. La scrittura completa di AGENTS.md, con Project rules, Review guidelines e Coding style, merita un altro articolo della guida pratica a Codex. Qui restiamo su struttura e priorità delle Review guidelines.

Usa il Codex app review pane per capire il diff prima di decidere

Il review pane di Codex app non mostra solo suggerimenti dell’IA. Riflette lo stato completo del Git repository. Di default si concentra su uncommitted changes, ma puoi passare anche a all branch changes o last turn changes.

Inline comments e PR context

Gli inline comments nel review pane sono collegati direttamente alle righe del diff. Puoi usare quel feedback preciso per decidere il passo successivo: far correggere Codex, modificare tu il codice o segnare il finding come false positive. Dopo /review, il risultato appare come inline comments nel review pane.

Se Codex ha GitHub access e il progetto corrente è su una PR branch, l’app può mostrare PR context: reviewer feedback, changed files e PR description. Serve però GitHub CLI installato e autenticato con gh auth login. Se manca, i PR details potrebbero non comparire e vedrai solo il diff locale.

Controllare la granularità: stage/revert per file o hunk, non tutto il commit

Il review pane supporta stage, unstage e revert a livello di entire diff, file o hunk. Non conviene fare revert di un intero commit appena vedi un finding, soprattutto se la modifica coinvolge più file. La gestione per hunk permette di tenere le parti sicure e annullare solo quelle rischiose.

Gestire i review findings: dopo @codex fix guarda diff, CI e test

Quando compare un P0/P1, non passare subito tutto a @codex fix. Prima devi capire se il finding è reale, se la correzione è sensata e se la modifica tocca un confine sensibile che richiede conferma del team.

🔥 Non sprecare mesi su prodotti senza domanda! Valida i punti di forza del tuo SaaS con Adsterra e un piccolo budget →

Testa ora →Pubbl.

Tabella di triage dei review findings

Flusso eseguibile per trattare i findings

Conferma se il finding è reale: guarda la riga del diff indicata dall’inline comment e verifica che il problema esista davvero.

Definisci il confine del fix: auth, payment e data migration sono modifiche sensibili e richiedono conferma umana. style e minor perf possono essere ignorati o lasciati alla toolchain.

Scegli il trattamento:

• Far correggere Codex: nel PR comment scrivi @codex fix the P1 issue; Codex avvia una cloud task basata sul PR context
• Correggere tu: modifica il codice manualmente, esegui i test locali e poi fai push
• Chiedere test: apri una follow-up issue o spiega il bisogno nel commento
• Segnare false positive: spiega il motivo nel commento, così eviti segnalazioni ripetute

Controlla diff e CI: anche se @codex fix può fare push sul PR branch, devi comunque guardare diff, risultato CI e copertura dei test. Un fix di Codex non è merge automatico, non equivale a CI passata e non sostituisce l’approval di un reviewer umano.

Conferma le modifiche sensibili con persone reali: auth bypass, payment flow e data migration toccano confini di sicurezza. Serve il via libera di un reviewer del team. Non saltare questo passaggio.

Cose da non fare

• Non fare push/merge automatico: @codex fix chiede all’IA di cambiare codice, non concede permesso di merge
• Non saltare la CI: anche se Codex corregge il problema, la CI deve girare per verificare che altri test non siano rotti
• Non ignorare i reviewer umani: l’AI review è un secondo controllo, non il sostituto del reviewer del team
• Non dare a Codex permessi eccessivi: main branch push, force push e write access su directory sensibili vanno limitati

I confini di sicurezza e il controllo dei permessi per modifiche sensibili saranno trattati in un successivo articolo della serie Codex su permessi e Secrets. Per le best practice CI, vedi la guida precedente alla pipeline CI con GitHub Actions.

Commit message e PR description: lascia scrivere l’IA, ma non inventare standard

@codex generate commit message o @codex generate PR description può chiedere a Codex di generare testo da diff e PR context. Rivedi l’output prima di usarlo, non committarlo alla cieca. Il commit message dovrebbe seguire Conventional Commits, non uno standard inventato al momento.

Conventional Commits e template di commit message

Il formato Conventional Commits è <type>[optional scope]: <description>. I type comuni includono fix per una versione PATCH, feat per una versione MINOR, e un footer BREAKING CHANGE o ! per una modifica breaking.

Esempio:

Vultr - Cloud server NVMe ad alte prestazioni, 32 location globali, deploy Docker con un clic

Vedi prezzi →Pubbl.

fix(auth): prevent bypass in login flow

- Add session validation before auth redirect
- Reject expired tokens within 5 minutes

Refs: #123

Conventional Commits è utile perché è uno standard ampiamente adottato. Toolchain come semantic-release, auto-changelog e commitlint usano questo formato per generare changelog e capire il version bump. Inventare una regola propria rompe queste automazioni e aumenta il costo di collaborazione.

Template di PR description

Una PR description dovrebbe contenere almeno cinque parti:

1. Contesto: perché esiste questa modifica (feedback utente, problema di performance, rischio di sicurezza)
2. Ambito della modifica: quali moduli sono coinvolti (auth, payment, logging)
3. Test: scenari verificati (test locali, copertura CI, verifica manuale)
4. Rischi: condizioni limite note (concorrenza, comportamento sotto alto traffico)
5. Rollback: come tornare indietro rapidamente (revert commit, feature flag, config toggle)

Dopo che Codex ha generato il testo, controlla che queste cinque parti siano complete, che la descrizione sia accurata e che non manchino rischi o rollback. Non committare direttamente il testo generato, soprattutto quando la modifica tocca un confine sensibile.

Per guidare commit message e PR description, puoi scrivere un’istruzione specifica nel PR comment, per esempio @codex generate commit message following Conventional Commits, così l’IA segue il formato standard.

Riepilogo

Codex review è un secondo controllo ad alto segnale, non un permesso di merge. @codex review chiede all’IA di leggere il diff e pubblicare inline comments; Automatic reviews automatizza solo il trigger, non approval o merge.

Flusso essenziale:

1. Nelle Review guidelines di AGENTS.md, concentrati su 1 o 2 rischi, come auth bypass, PII logging o concurrency. Non cercare di coprire tutto
2. P0/P1 è il focus di default, per evitare che i review comments esplodano. P0 va corretto; P1 richiede una decisione sul trattamento
3. Dopo un finding, guarda la riga del diff indicata dall’inline comment e conferma se il problema è reale. Modifiche sensibili come auth, payment o data migration richiedono conferma umana
4. Dopo @codex fix, controlla comunque diff, risultato CI, copertura dei test e giudizio umano. Non fare push/merge automatico, non saltare la CI e non ignorare il reviewer del team
5. Usa Conventional Commits per i commit message. Non inventare formati: la toolchain dipende dallo standard per generare changelog e decidere le versioni

Azioni consigliate:

• Aggiungi AGENTS.md al repository e scrivi una breve sezione Review guidelines focalizzata su 1 o 2 rischi
• Prova @codex review nella prossima PR e verifica se gli inline comments seguono le tue regole
• Per modifiche sensibili, leggi prima i prossimi articoli della serie Codex su permessi, secrets e analisi dei fallimenti, poi decidi se usare @codex fix

Articoli correlati

• Trigger PR di GitHub Actions: configurare PR trigger e branch protection rules
• Best practice per pipeline CI con GitHub Actions: controlli CI e responsabilità dei reviewer umani
• Confronto tra AI coding assistant: Claude Code vs Cursor vs Copilot: scegliere strumenti di AI coding