Casi di fallimento con Codex: perché l'IA rompe il codice e come validare le modifiche

git diff --stat mostra all’improvviso 18 file, anche se il task dato a Codex era solo “sistema lo stato di un pulsante”. La CI è verde. Però apri il diff e trovi un’altra storia: coverageThreshold è stato abbassato, un flaky test è finito in skip e un helper validateEmail() è stato generato nonostante nel repository esista già emailSchema.

Codex non ha rotto il codice di proposito. Il confine del task era troppo ampio e il processo di validazione troppo debole. Qui non discutiamo in astratto se l’IA sia affidabile. Costruiamo una tabella di pattern di fallimento, gate di validazione, flusso di rollback e checklist di review per trattare il fallimento come una lacuna di processo.

Tabella dei pattern di fallimento: come l’IA rompe il codice

Uno studio arXiv su 33k agent-authored PR su GitHub ha osservato che le PR non mergiate tendono a essere più grandi, toccare più file e fallire più spesso la validazione CI/CD del progetto. Questo non significa che gli AI agent siano semplicemente poco intelligenti. Contano anche decomposizione del task, criteri di accettazione e coinvolgimento dei reviewer.

Questi sono 9 pattern comuni, con segnale e prima reazione:

Pattern	Come si presenta	Segnale	Prima reazione
Diff troppo grande	Lo scope della modifica supera molto la richiesta	git diff --stat mostra molti più file di quelli descritti, per esempio 10+ file per un “fix pulsante”	Guarda prima la file list. Separa modifiche attese da modifiche fuori scope; dividi o reverti l’extra
Test falsamente verdi	I test passano ma la logica resta sbagliata	Il diff abbassa coverageThreshold, mette un flaky test in skip o indebolisce le assertion	Controlla se la configurazione dei test è cambiata; richiedi un test di regressione che fallisca prima della modifica
Directory sbagliata	Cambiano config CI o file non correlati	.github/workflows/, Makefile o package.json scripts cambiano senza relazione con il task	Verifica se AGENTS.md vieta modifiche a CI/config; reverti e scrivi la regola
Codice duplicato	Esiste già un helper o una utility	Il diff aggiunge un helper, ma il repo ha già la stessa funzione o schema	Cerca l’implementazione esistente; se c’è, reverti il duplicato e chiedi a Codex di usare quella
PR troppo grande	Una PR grande senza plan	Il PR body dice solo “fix issue”, senza implementation plan, comandi di verifica o note di rollback	Chiedi PR più piccole, ognuna reviewable, verificabile e reversibile
CI indebolita	La config CI cambia per far passare i check	La CI fallisce, ma il patch cambia solo test/CI config e non codice di business	Trattalo come blocker; reverti la modifica alla CI e richiedi un fix nel codice di business
Bug di business nascosto	La logica sembra corretta ma viola un vincolo di business	Il diff rimuove un permission check o una validation non coperta dai test	Segui un critical path, controlla gli effetti collaterali e richiedi approval esplicito
Untrusted input	Input esterno usato senza validazione	Codex usa direttamente dati o path forniti dall’utente senza sanitization o validation	Verifica l’input validation; se manca, richiedi validation test
Grande modifica senza plan	L’implementazione parte prima del plan	Codex modifica codice prima di elencare file da toccare, file vietati e comandi di verifica	Richiedi prima /plan o goal/context/constraints/done criteria espliciti

Questi pattern raramente arrivano da soli. Una PR con diff troppo grande può mescolare directory sbagliata, codice duplicato e test falsamente verdi. La checklist di GitHub per agent PR review cita anche CI gaming, punti ciechi nel riuso del codice, problemi di correctness nascosti e PR grandi senza plan come segnali rossi.

La prima reazione è semplice: non partire chiedendo se la CI è verde. Parti dallo scope del diff e dalla granularità di rollback.

Flusso di suddivisione dei task: il lavoro grande non è vietato a Codex

Le best practice di OpenAI consigliano di pianificare prima di implementare quando un task è complesso o ambiguo. Codex lavora meglio quando può verificare il proprio lavoro, e i task piccoli e focalizzati sono più facili da testare e rivedere.

Ma “dividere più piccolo” non è uno slogan. La granularità giusta è il punto in cui ogni passaggio può essere validato e revertito separatamente.

Ciclo in sette passaggi: da scope a update rules

Usa questo ciclo per le modifiche di Codex:

scope -> plan -> patch -> verify -> review -> merge/rollback -> update rules

Ogni passaggio ha domande e una condizione di ritorno.

1. scope

Domande:

• Il task è abbastanza concreto da essere scritto come goal + context + constraints + done criteria?
• Attraversa più sottosistemi, come auth, payment e notification?
• Può influire su configurazione CI, database schema o dipendenze esterne?

Ritorno: se attraversa più sottosistemi o tocca CI/config, dividilo prima in task separati.

2. plan

Domande:

• Codex ha prima elencato file previsti, file o directory da non toccare e comandi di verifica?
• Il plan include rischi e condizioni di uscita?
• Il plan descrive il percorso di rollback?

Ritorno: se non c’è plan o mancano questi elementi, richiedi un nuovo /plan.

3. patch

Domande:

• git diff --stat coincide con lo scope dei file nel plan?
• Codex ha modificato file fuori scope, come CI/config o file non correlati?
• Ha generato codice duplicato, per esempio un helper già esistente?

Ritorno: se diff e plan non coincidono o compare un segnale rosso, torna al passo 2.

4. verify

Domande:

• Sono stati aggiunti test per il core path?
• Il test fallirebbe prima della modifica?
• I CI status checks sono required e non skipped?
• lint o pre-commit sono passati?

Ritorno: se non è stato aggiunto un test rilevante o se la modifica fa passare i test indebolendo la configurazione, torna al passo 3.

5. review

Domande:

• Lo scope del diff coincide con il task?
• Qualcuno ha tracciato un critical path?
• Un reviewer umano ha approved esplicitamente, invece di fidarsi del report dell’IA?
• La branch protection richiede required reviews, required status checks e conversation resolution?

Ritorno: se il reviewer chiede modifiche o trova un segnale rosso, torna al passo 3.

6. merge/rollback

Domande:

• La modifica soddisfa la checklist di prove della sezione successiva?
• Può essere revertita separatamente a livello di hunk o file?
• Il lavoro era isolato in un worktree, così da scartare un tentativo fallito e portare quello riuscito in PR?

Ritorno: se mancano prove o la modifica non è reversibile separatamente, rollback e ritorno al passo 1.

7. update rules

Domande:

• Il fallimento deriva da una regola mancante in AGENTS.md, come “non modificare la config CI” o “dividere task con più di cinque file”?
• Area vietata, criteri di accettazione o rollback dovrebbero essere scritti in AGENTS.md?

Azione: se il fallimento deriva da una regola mancante, scrivila in AGENTS.md.

I task grandi restano possibili con Codex

I refactoring grandi non sono vietati. Devono solo essere divisi finché ogni passaggio è rollbackable da solo. Anche l’esperienza del refactoring con IA su 10.000 righe mostra la stessa cosa: piccoli passi e rete di sicurezza dei test sono fondamentali.

Verifica la granularità così:

• Ogni patch può essere revertita separatamente a livello di hunk o file?
• Ogni verify può dimostrare che il comportamento pre-change falliva?
• Ogni merge ha reviewer approve esplicito e status checks?

Se la risposta è no, il task è ancora troppo grande.

Codex review pane in pratica: validare non significa solo testare

Quando rivedi una modifica di Codex, la prima cosa non è il risultato dei test. È lo scope del diff e la granularità di rollback. Il review pane dell’app Codex offre tre view e operazioni a livello di hunk/file.

Tre view del diff

Il review pane riflette lo stato Git del repository, non solo le modifiche di Codex. Può mostrare modifiche di Codex, dell’utente e altre uncommitted changes.

View	Cosa mostra	Quando usarla
uncommitted changes	Tutte le modifiche non committate, per default	Rivedere lo scope del task Codex corrente
all branch changes	Tutte le modifiche del branch corrente rispetto al base branch	Rivedere l’intera catena di task, anche su più turn
last turn changes	Le modifiche dell’ultimo turn di Codex	Isolare ciò che Codex ha appena fatto e trovare rapidamente modifiche fuori scope

Inizia con uncommitted changes per confermare lo scope. Poi guarda all branch changes per eventuali residui di lavori precedenti. Infine usa last turn changes per verificare se Codex ha seguito il plan.

Inline comments e operazioni hunk/file

Il review pane supporta inline comments su righe specifiche del diff. Quei commenti possono diventare contesto per una correzione successiva di Codex.

Livelli di operazione:

• entire diff: stage/unstage/revert di tutto il diff
• file: stage/unstage/revert di un singolo file
• hunk: stage/unstage/revert di un blocco di codice, la più piccola unità utile

Se trovi una modifica fuori scope, come una cancellazione della config CI, reverti prima quel hunk o file invece di buttare via tutto il diff.

Caricamento del PR context

Su una PR branch, se GitHub access o gh auth login è disponibile, il review pane può caricare PR context, review comments e changed files. Così passi da “leggere il diff locale” a “leggere PR diff più commenti dei reviewer”.

Promemoria sui fatti variabili: dettagli di UI e slash command possono cambiare. Riapri la pagina ufficiale prima della pubblicazione se questo comportamento esatto è importante.

Il principio centrale della review

Validare non significa solo guardare i test:

1. Prima controlla se lo scope del diff coincide con il plan
2. Poi controlla se la granularità di rollback è abbastanza piccola, per esempio hunk o file
3. Infine controlla se sono stati aggiunti test e se coprono il critical path

Se i primi due controlli falliscono, i test passati non provano che il codice sia corretto.

Checklist delle prove: i test passati non bastano

GitHub Docs spiega che i required status checks devono essere successful, skipped o neutral prima del merge in una protected branch. In GitHub Actions, un check skipped può essere trattato come success e quindi non bloccare il merge.

Per questo “CI verde” non significa “codice buono”. Servono più prove, non un solo segnale.

Usa questa checklist.

Prove a livello di codice

• Lo scope del diff coincide con il task, senza modifiche fuori scope
• Non è stato aggiunto codice duplicato; il progetto è stato cercato per equivalenti esistenti
• CI/config non è stata modificata, a meno che il task lo consentisse esplicitamente

Prove a livello di test

• Sono stati aggiunti test per il core path
• I test fallirebbero prima della modifica, non solo dopo
• La configurazione dei test non è stata indebolita: niente coverage threshold abbassata, skip o assertion più debole

Prove a livello di CI

• lint e pre-commit sono passati
• I CI status checks sono required e non skipped
• La configurazione CI non è stata modificata solo per far passare il check

Prove a livello di PR

• Il PR body include implementation plan, comandi di verifica e note di rollback
• Un reviewer umano ha approved esplicitamente, invece di fidarsi del report dell’IA
• La branch protection copre required reviews, required status checks e conversation resolution

Prove a livello di rollback

• Ogni patch può essere revertita separatamente a livello di hunk o file
• Il task è stato isolato in un worktree, così un tentativo fallito può essere scartato e uno riuscito può andare in PR

Branch protection e status checks

Le protected branches di GitHub possono richiedere:

• required reviews: un numero definito di approvals prima del merge
• required status checks: checks pass, skipped o neutral prima di entrare nel protected branch
• conversation resolution: tutte le conversazioni devono essere resolved prima del merge

Sono merge gate esterni all’IA. Non vengono sostituiti dal fatto che l’IA dica di aver finito.

Ordine della review

Usa questo ordine:

1. Controlla prima lo scope del diff, inclusi file list e dimensione del diff
2. Poi controlla se CI o configurazione dei test è cambiata
3. Poi controlla se sono stati aggiunti test e se coprono il core path
4. Infine controlla se un reviewer ha approved esplicitamente

Non invertire l’ordine. Se inizi dai test, è facile perdere modifiche fuori scope e CI indebolita.

Rollback e retrospettiva: cosa fare dopo una modifica sbagliata

Quando la review trova una modifica fuori scope o un test falsamente verde, la prima mossa è rollback, non chiedere a Codex di continuare a correggere lo stesso diff confuso.

Granularità di rollback: da hunk a branch

Scegli il livello di rollback in base a portata e causa del fallimento:

Granularità	Quando usarla	Operazione
Revert a livello di hunk	Un blocco di codice contiene una modifica fuori scope, come una cancellazione CI	Seleziona quel hunk nel review pane -> revert
Revert a livello di file	Un file intero contiene codice duplicato o modifiche fuori scope	Seleziona quel file nel review pane -> revert
Scartare il branch	La direzione del task è sbagliata e molti file vanno buttati	git checkout main -> elimina il branch

Preferisci la granularità utile più piccola. Scarta un branch solo quando più hunks o file sono sbagliati.

Isolamento con worktree: i tentativi falliti si possono buttare

L’articolo Codex Worktree di questa serie usa i worktree per isolare task paralleli. Un tentativo fallito si può buttare; uno riuscito può andare in PR.

Se un task rompe codice dentro il suo worktree, elimina quel worktree e mantieni pulito il workspace principale. È più sicuro che fare revert ripetuti sullo stesso branch.

Dopo il rollback: scrivere in AGENTS.md

Dopo il rollback, decidi se il fallimento deriva da una regola mancante. Se sì, scrivila in AGENTS.md.

Poniti queste domande:

• Mancava una convenzione di progetto, come “non modificare la config CI” o “dividere task sopra cinque file”?
• Mancavano criteri di accettazione, come “i test devono dimostrare il fallimento pre-change”?
• Mancava una regola di rollback, come “ogni patch deve essere revertibile separatamente”?

Se sì, scrivi la regola nel punto giusto di AGENTS.md, come nella sezione successiva.

Dopo la retrospettiva: trasformare flussi ripetuti in skill

Decidi se un fallimento merita uno skill con queste domande:

• Il fallimento deriva da un limite di Codex, come una restrizione di business capita male?
• Deriva da un workflow complesso in più passaggi, come coordinamento multi-agent?
• Deriva da un flusso di review che ripeti spesso, come controllare ogni volta diff scope, CI config e test aggiunti?

Se sì, trasformalo in skill, come descritto nell’articolo Codex Skills/plugins di questa serie.

Dove mettere le regole in AGENTS.md

Prima di ogni run o session, Codex costruisce una instruction chain e legge gli AGENTS.md globali e di progetto. A livello di progetto, legge dal Git root fino alla directory corrente. Il file più vicino è più specifico.

Quindi AGENTS.md può stare alla root del repository, in un submodule o in una directory di funzionalità. Codex dovrebbe preferire la regola più specifica quando i path si sovrappongono.

Posizioni e contenuti comuni di AGENTS.md

La guida introduttiva a Codex di questa serie copre un template AGENTS.md tipico:

Posizione	Contenuto tipico	Esempio
repo root	repo layout, build/test/lint commands, engineering conventions	Project structure: src/frontend, src/backend, src/shared; build: npm run build; test: npm test; lint: npm run lint
src/frontend	frontend-specific conventions e PR expectations	frontend usa solo React hooks, non class components; le PR devono includere Storybook stories
src/backend	backend-specific conventions e do-not rules	backend non accede direttamente al database; usare ORM; niente SQL nei controller
src/shared	shared utility conventions	shared contiene solo pure functions, senza side effects

Dove scrivere le lezioni dei fallimenti

Dopo un fallimento, posiziona la regola in base alla causa:

Causa del fallimento	Dove scriverla	Esempio
Config CI eliminata per errore	repo root -> PR expectations -> do-not rules	Non modificare .github/workflows/, Makefile o package.json scripts senza approvazione esplicita
Più di cinque file modificati	repo root -> PR expectations -> do-not rules	Le modifiche che toccano più di cinque file devono essere divise; ogni task dovrebbe toccare al massimo tre file
Test falsamente verdi	repo root -> what done means	I test devono coprire il core path e dimostrare che il comportamento pre-change fallisce, non solo che quello nuovo passa
Codice duplicato	repo root -> engineering conventions	Prima di aggiungere un helper sotto src/lib, cercare un equivalente esistente; se esiste, usarlo
Grande modifica senza plan	repo root -> PR expectations	Le modifiche che toccano più di tre file richiedono prima /plan, con file da modificare, file vietati e comandi di verifica
Untrusted input	src/backend -> engineering conventions	Tutti gli input utente devono essere validati; non usare direttamente dati o path forniti dall’utente
Bug di business nascosto	src/backend -> engineering conventions	Dopo modifiche a permission checks o validation, seguire un critical path e controllare gli effetti collaterali

Scoperta delle regole: vince il file più vicino

La documentazione OpenAI AGENTS.md descrive le istruzioni di progetto come una catena dal Git root alla directory corrente, dove i file più vicini sono più specifici.

In pratica:

• AGENTS.md alla repo root contiene regole generali, come build/test/lint commands e “non modificare la CI”
• AGENTS.md in un submodule contiene regole specifiche, come solo hooks nel frontend o SQL vietato nel backend
• AGENTS.md nella directory di una funzionalità contiene le regole più specifiche, come i vincoli di business di una API

Quando scrivi una lezione:

• Le convenzioni globali come “non modificare la CI” vanno alla repo root
• Le convenzioni di submodule come regole frontend vanno sotto src/frontend
• I vincoli specifici di funzionalità come una regola API vanno sotto src/backend/api/xxx

Il limite di AGENTS.md

AGENTS.md riduce modifiche fuori scope ed errori accidentali, ma non dimostra la correttezza del codice. Codex può seguire AGENTS.md e produrre comunque logica sbagliata.

L’ultimo gate resta l’approvazione esplicita di un reviewer umano, non la semplice esistenza di un file di regole.

Checklist di review umana per PR IA

Il consiglio di GitHub per rivedere agent-generated PRs parte da file list e dimensione del diff, poi controlla se CI/test config è cambiata, cerca helper duplicati, segue un critical path e chiede un test che dimostri il fallimento pre-change.

Usa questa checklist di segnali rossi.

Segnali rossi a livello di codice

• La file list e la dimensione del diff superano molto la descrizione del task
• CI/test config è cambiata, come .github/workflows/, Makefile o package.json scripts
• Un nuovo helper duplica un helper esistente
• Il PR body dice solo “fix issue”, senza implementation plan, comandi di verifica o rollback
• La PR è troppo grande, per esempio più di 10 file

Segnali rossi a livello di test

• Non è stato aggiunto alcun test
• Il test verifica solo il comportamento post-change e non prova che quello precedente fallisse
• La configurazione dei test è stata indebolita: coverage threshold ridotta, flaky test in skip o assertion più debole

Segnali rossi a livello di CI

• La CI falliva, ma il patch ha cambiato solo tests o CI config invece del codice di business
• I CI status checks sono skipped o neutral, non passing
• La configurazione CI è stata cambiata per far passare il check

Segnali rossi a livello di PR

• PR body vuoto
• Nessun implementation plan
• Nessun reviewer approval, solo report dell’IA
• Conversations unresolved

Blocker e segnali di suddivisione

Tipo	Segnale rosso	Risposta
Blocker	La CI falliva, ma è cambiata solo test/CI config	Request changes, revert della modifica CI e richiesta di fix nel codice di business
Blocker	Test falsamente verdi, come coverageThreshold ridotta o skip	Request changes, revert della test config e richiesta di nuovo test
Blocker	Untrusted input senza validation	Request changes e richiesta di validation tests
Segnale di suddivisione	PR grande, per esempio più di 10 file	Request changes e divisione in PR più piccole
Segnale di suddivisione	PR body vuoto senza implementation plan	Request changes e aggiunta di plan, comandi di verifica e rollback

Il principio centrale del reviewer

Il reviewer non giudica in astratto se l’IA sia affidabile. Controlla:

1. se lo scope del diff coincide con la descrizione del task
2. se CI/test config è cambiata
3. se sono stati aggiunti test e coprono il core path
4. se sono stati controllati effetti collaterali nascosti seguendo un critical path

Non invertire l’ordine. Iniziare dai test rende facile perdere CI indebolita e modifiche fuori scope.

Conclusione

Quando Codex rompe il codice, la causa di solito non è che sia “inaffidabile” in astratto. Il confine del task era troppo ampio e il processo di accettazione troppo morbido. La checklist pratica è:

• Tabella dei pattern di fallimento: riconoscere i modi comuni in cui le modifiche Codex vanno male
• Ciclo in sette passaggi: da scope a update rules come flusso completo di accettazione
• Review pane in pratica: non fermarsi ai test; controllare prima diff scope e granularità di rollback
• Checklist delle prove: i test passati non bastano; controllare anche diff scope, test aggiunti, stato CI, review umana e branch protection
• Rollback e retrospettiva: revert a livello di hunk/file, isolamento con worktree e scrittura in AGENTS.md o in uno skill
• Posizioni di AGENTS.md: mettere le regole in repo root, submodule o directory di funzionalità in base allo scope
• Segnali rossi di review umana: partire da file list e diff size, poi CI/test config, test aggiunti e reviewer approval

Trasforma questa lista in uno strumento reale di review. Ogni volta che rivedi una modifica Codex, percorri gli elementi. Se lo stesso flusso di review si ripete, valuta di trasformarlo in uno skill, come nell’articolo Codex Skills/plugins.

Il fallimento non è una sorpresa. È una lacuna di processo.

Prossimi passi e letture consigliate

Articoli pubblicati

• Refactoring IA di 10.000 righe: retrospettiva reale e rete di sicurezza dei test — lezioni pratiche su piccoli passi e test safety net
• Guida al refactoring con Cursor — principi di review validi anche per altri strumenti di coding IA
• GitHub Actions CI workflow — basi degli status checks
• GitHub Actions workflow — basi del PR workflow
• Workflow agent Codex Cloud — esecuzione remota, accettazione delle PR e cicli per task lunghi

Stessa serie: guida pratica a Codex

• Guida completa per iniziare con Codex — CLI, IDE, Cloud e desktop
• Sicurezza e permessi di Codex — sandbox e approval riducono il rischio
• Code review con Codex — review come gate di accettazione
• Task di automazione con Codex — le patch generate da exec richiedono comunque review umana
• Codex Worktree in pratica — isolare task paralleli
• Codex Skills/plugins — trasformare workflow di review in skill
• Sviluppo guidato dai test con Codex — TDD + Codex
• Ottimizzazione dei costi di Codex
• Codex nei flussi enterprise