Debug assistito dall'IA
In questa pagina
Trova e correggi i bug più velocemente
Il debug rimane un’arte: comprendi il sintomo, risali alla causa radice e correggilo senza rompere qualcos’altro. Codex ti aiuta in tutti e tre i passaggi, ma in modo disomogeneo. Nel primo passo, non aggiunge quasi nulla, poiché sei tu a osservare il sintomo e a sapere come dovrebbe comportarsi il sistema. Nel secondo, eccelle, perché tracciare un flusso di dati attraverso dieci file è un lavoro di lettura sistematica, esattamente ciò che una macchina fa meglio di un umano stanco. Nel terzo, fornisce una verifica immediata tramite i test.
Debug partendo da un errore
Il caso più semplice: passi l’errore così com’è, senza riformularlo o riassumerlo.
"Il test src/api/routes/orders.test.ts fallisce con:
TypeError: Cannot read properties of undefined
(reading 'id')
at createOrder (src/services/order.service.ts:42)
Trova la causa e correggi il bug."
L’agente esegue quindi una catena di sei operazioni: legge il file di test per comprendere lo scenario, apre order.service.ts alla riga 42, traccia il flusso di dati per individuare dove è stato introdotto l’undefined, identifica la causa radice (parametro mancante, errore di tipizzazione o altro), propone e applica la correzione, quindi riesegue il test per verificare. La terza operazione è quella che ti sarebbe costata venti minuti di lettura silenziosa.
Debug di comportamenti inaspettati
Spesso non c’è alcun errore: il programma fa semplicemente qualcosa di sbagliato in silenzio. Questi sono i bug più costosi e quelli in cui il modo in cui formuli la tua richiesta conta di più.
"La rotta POST /api/orders crea l'ordine nel
database, ma il totale è sempre 0. I prezzi dei prodotti sono
corretti nella tabella products. Trova perché il calcolo del
totale fallisce."
Questa istruzione funziona perché definisce l’ambito: cosa funziona, cosa non funziona e un’ipotesi già scartata, dato che i prezzi nel database sono corretti. Codex traccia quindi il flusso dalla richiesta HTTP all’inserimento, isola il punto in cui il calcolo devia e propone una correzione. Senza la frase sulla tabella products, molto probabilmente inizierebbe controllando esattamente ciò che hai già verificato tu stesso.
Analisi dei log di produzione
Puoi anche partire dalle tracce di produzione, semplicemente incollando l’estratto rilevante.
"Ecco un estratto dai log di produzione. L'applicazione
restituisce intermittentemente un 500 su /api/checkout:
[2026-04-01 14:23:01] ERROR: Connection pool exhausted
[2026-04-01 14:23:01] WARN: Query timeout after 30s
[2026-04-01 14:23:02] ERROR: Transaction rollback
Analizza il codice della rotta checkout e identifica la perdita
di connessioni."
Codex collega le tre righe (pool esaurito, timeout della query, transazione annullata), conclude che esiste una perdita di connessioni al database e cerca quindi nel codice i punti in cui una connessione viene aperta ma non chiusa correttamente. Questo è tipicamente un bug che nessun test rivela, poiché si manifesta solo sotto carico e scompare non appena provi a riprodurlo localmente.
Debug per bisezione
Quando il problema è diffuso piuttosto che circoscritto, chiedi un’indagine metodica invece di una correzione rapida.
"La compilazione TypeScript fallisce con 23 errori di tipo dall'
ultimo aggiornamento delle dipendenze. Analizza ogni errore, identifica se
si tratta di un cambiamento API in una dipendenza e correggi il codice per renderlo
compatibile con le nuove versioni."
Il valore di questa formulazione è che forza una diagnosi errore per errore. Senza l’istruzione di identificare l’origine, la tentazione per un agente, come per uno sviluppatore a fine giornata, è aggiungere any finché il compilatore non tace, trasformando ventitré errori visibili in ventitré bug futuri.
Pattern di debug efficaci
Il materiale che fornisci condiziona tutto il resto. Ogni tipo di sintomo richiede prove specifiche da includere; ometterle è come chiedere una diagnosi senza un esame.
| Sintomo | Istruzione per Codex |
|---|---|
| Test fallito | Fornisci il messaggio di errore completo + il file di test |
| Errore di tipo | Fornisci l’output di tsc --noEmit |
| Errore runtime | Fornisci lo stack trace + i passaggi per riprodurre |
| Comportamento errato | Descrivi il risultato atteso rispetto a quello osservato |
| Problema di prestazioni | Fornisci le metriche (tempo di risposta, query lente) |
Prevenire i bug futuri
Un bug corretto è gestito solo a metà se nulla ne impedisce la ricomparsa altrove. Quindi, segui sistematicamente la correzione con un’attività di consolidamento, formulata sulla base di ciò che hai appena appreso.
"Il bug derivava da un userId nullo non controllato. Aggiungi
guardie di tipo in tutte le funzioni in src/services/ che ricevono un
userId. Aggiungi anche un test di regressione per questo caso."
Questo secondo compito generalizza la lezione laddove la correzione rimaneva locale: le guardie coprono tutti i servizi e il test di regressione garantisce che questo caso specifico rimanga monitorato dopo che avrai lasciato il progetto. È questa mossa che distingue un team che corregge i bug da un team che riduce il proprio backlog.
Punti chiave
- Fornisci a Codex il massimo contesto: messaggi di errore, stack trace, log
- Codex traccia il flusso di dati per trovare la causa radice
- Verifica la sua correzione rieseguendo i test automaticamente
- Dopo la correzione, chiedi protezioni e test di regressione
- Più precise sono le tue istruzioni, più veloce sarà il debug