L’architettura di diffox: 17 agenti specializzati, quattro fasi

Come funziona una review

Il modo più rapido per esaminare una modifica è chiedere a un modello: «C’è un bug qui?». diffox non fa così. Fa leggere la stessa modifica a diversi agenti specializzati: uno guarda gli errori di logica, uno la concorrenza, uno se un test verifica davvero qualcosa. Ogni agente ha un compito ristretto e ben definito. Poi vengono altri due passi. Delle verifiche legano ogni rilievo al file stesso, non alla parola del modello, e una selezione decide che cosa viene pubblicato.

Quanto rende questa struttura l’abbiamo misurato nel primo articolo: nel benchmark di Martian, su 50 pull request, diffox ultra ha individuato 119 dei 158 bug noti e diffox 106. Quanto costa lo trovi nel secondo articolo. Ecco le quattro fasi, in ordine.

Che cosa vedono gli agenti e quali entrano in gioco

Una review parte senza che tu la chieda: quando viene aperta una pull request e a ogni nuovo push. diffox pubblica prima sulla pull request un commento che avvisa che la review è iniziata; quando finisce, lo stesso commento mostra il risultato. Prima che gli agenti specializzati vedano la modifica si decidono due cose: che cosa mettere loro davanti e quali chiamare.

Ognuna delle quattro parti risponde a una domanda diversa. Il diff dice che cosa è cambiato. I file, prima e dopo, mostrano dove si inserisce la modifica. Il titolo, la descrizione e i messaggi di commit dicono che cosa si voleva fare. E AGENTS.md o CLAUDE.md, se il tuo repository ne ha uno, dice quali regole segue il tuo team.

Il file delle regole viene letto dal branch in cui la pull request verrà unita, non dal branch della pull request stessa. Così una pull request non può cambiare le regole della propria review: una modifica al file delle regole vale solo dopo essere stata unita. I file di lock, il codice di terze parti come vendor/ e node_modules/ e i file minificati non vengono esaminati.

Poi viene l’assegnazione. diffox stabilisce il tipo di modifica (correzione di bug, nuova funzionalità, refactoring, migrazione, test…) e ne valuta il rischio: quanti file tocca, se incide su altri file, se arriva con dei test. Alcuni agenti leggono ogni modifica; altri si attivano solo quando compare il loro argomento. Se nessuna riga è stata cancellata, l’agente che cerca il comportamento rimosso non ha nulla da fare. Se nessun test è stato toccato, vale lo stesso per l’agente che cerca i test vuoti.

Quando arriva un nuovo push sulla stessa pull request, diffox legge solo la modifica nuova.

Ogni agente specializzato cerca una sola cosa

Nella seconda fase gli agenti specializzati leggono la modifica. Il team ha 17 agenti, divisi in due tipi a seconda di ciò che cercano.

12 agenti cercano bug: codice che dà un risultato sbagliato quando viene eseguito. 5 cercano contraddizioni: punti in cui il codice non corrisponde al commento, al test o al documento che lo accompagna. Ogni agente ha le proprie istruzioni; tutti leggono la stessa modifica e lo stesso contesto.

Per contare, un rilievo deve dire tre cose: che cosa afferma, che cosa va storto e in quale situazione, e il codice su cui si basa l’affermazione, citato alla lettera. Un rilievo di contraddizione porta due citazioni: il codice e il testo che lo contraddice. Se ne manca una, il rilievo non conta.

Gli agenti non danno numeri di riga. I modelli linguistici non sono affidabili nel contare le righe: per questo diffox chiede al modello la citazione invece del numero di riga, e trova la riga da sé cercando la citazione nel file. Così, che un rilievo finisca sotto la riga giusta non dipende da ciò che dice il modello.

Accanto agli agenti specializzati lavorano rilevatori basati su regole. Non usano alcun modello e cercano con regole esatte: una credenziale finita nel codice, un metodo definito due volte nella stessa classe, un ramo che non può mai essere raggiunto.

Il team al completo e che cosa cerca ogni agente:

Il commento di un rilievo porta il simbolo e il nome dell’agente che l’ha trovato: ➗ Logic Agent, per esempio.

Come si verifica ogni rilievo sul codice

Un modello linguistico può scrivere qualcosa di convincente e sbagliato: cita una riga che non è nel file, contesta codice che questa pull request non ha toccato, ripete lo stesso problema tre volte con tre frasi diverse. Il compito della terza fase è legare ogni rilievo al file stesso e non alla parola del modello.

Queste verifiche sono normale codice, non una chiamata a un modello: lo stesso input dà sempre la stessa risposta.

• Anchor Verifier. La citazione del rilievo viene cercata nel file. Una citazione che non si trova non ha una riga da indicare. Se la riga trovata non è in ciò che questa pull request ha modificato, il rilievo è fuori ambito.
• Second Witness. I rilievi che fanno la stessa obiezione nello stesso punto vengono uniti in uno solo, così lo stesso problema non ti viene segnalato due volte. E quando più fonti indicano lo stesso punto, questo gioca a favore del rilievo.
• Verbatim Matcher. Anche la seconda citazione di un rilievo di contraddizione viene cercata parola per parola: nella modifica, nei file, nella descrizione della pull request, nei messaggi di commit e nel tuo file delle regole. Se il modello sostiene che un commento dice qualcosa che non dice, qui si vede.

C’è un’altra verifica: un rilievo che dice che un valore può essere vuoto viene confutato quando il tipo del valore, o un controllo qualche riga più su, lo esclude già.

Quali rilievi vengono pubblicati

Dopo le verifiche resta un elenco di candidati. La quarta fase decide quali vengono pubblicati sulla pull request.

Attention Ranker risponde a una sola domanda per ogni candidato: quanto è probabile che questo rilievo sia un bug reale? Nel punteggio contano la gravità e il tipo del rilievo, l’esito della verifica delle evidenze e se altri rilievi indicano lo stesso punto. Tra i rilievi che cadono su righe vicine viene pubblicato solo il più solido.

Sulla pull request vedi solo ciò che va corretto: i rilievi critici e gli avvisi. I suggerimenti aspettano nella pagina Rilievi, senza che tu debba impostare nulla.

Abbiamo misurato i numeri qui sotto sullo stesso benchmark con tre impostazioni di sensibilità. Quell’impostazione era una soglia su un punteggio. Alta ha individuato più bug. Media e Bassa alzavano la soglia: diffox pubblicava meno rilievi ed era più sicuro di quelli che pubblicava.

Benchmark di Martian: 50 pull request, 158 bug noti, Claude Opus 4.5 come giudice. Sensibilità alta: la nostra esecuzione pubblica, 7 ottobre 2026. Media e bassa: la nostra misurazione interna sulle stesse 50 pull request, media di 5 esecuzioni per diffox ultra e 2 per diffox.

Ciò che non viene pubblicato sulla pull request non va perso: resta 30 giorni nella tua pagina Rilievi della console, e da lì puoi pubblicare qualsiasi rilievo.

La pubblicazione ha due parti: un commento di riepilogo sulla pull request e, per ogni rilievo, un commento proprio sotto la riga a cui si riferisce. Un rilievo che si può correggere include una correzione suggerita che GitHub applica con un clic; il commit viene fatto a tuo nome. Titoli e correzioni suggerite vengono generati dopo la selezione, solo per i rilievi che verranno pubblicati. La review arriva nella lingua del tuo team. L’ultima riga del riepilogo riporta il prezzo di quella review, la durata e il commit letto.

Lo stato di diffox su una pull request non diventa mai rosso: la decisione sul merge spetta al tuo team. Con ogni 👍 e 👎 sui suoi commenti, diffox conosce meglio te e il tuo repository, e le sue review si adattano sempre di più al tuo team.

Cosa fa di diverso diffox ultra

diffox ultra passa per le stesse quattro fasi; la differenza è nella seconda e nella quarta. Due modelli distinti leggono la modifica, e ciascuno fa la propria review dall’inizio alla fine. Le due review girano in parallelo e vengono pubblicate come una sola. Nella fase di selezione interviene anche un terzo modello, un piccolo modello decisionale: non scrive testo e risponde sì o no a domande su ogni rilievo. La selezione dà un punteggio ai rilievi di entrambe le review tenendo conto di queste risposte. Se i due modelli indicano lo stesso punto, questo gioca a favore del rilievo. Dopo la selezione, il modello decisionale trova i rilievi che risalgono alla stessa causa e li riduce a uno.

Il risultato è nei primi due articoli: diffox ultra ha individuato 119 dei 158 bug noti e diffox 106; una review di diffox ultra costa in media $1,64, una di diffox $0,41.

Domande frequenti

Perché diffox usa agenti specializzati?

«C’è un bug qui?» è una domanda ampia, e lo è anche la risposta. Ogni agente specializzato cerca una sola cosa e deve documentare ciò che trova con una citazione del codice. Così è chiaro da quale agente arriva ogni rilievo.

Posso dare a diffox le mie regole di review?

Sì. Le regole che scrivi in AGENTS.md o CLAUDE.md, nella radice del tuo repository, vengono lette a ogni review, e un agente dedicato cerca le righe che le violano. Le regole vengono lette dal branch in cui la pull request verrà unita: se una pull request modifica il file delle regole, la modifica vale dopo che è stata unita.

A cosa servono 👍 e 👎?

Con ogni reazione, diffox conosce meglio te e il tuo repository: impara che cosa conta per te e che cosa è rumore. Le sue review si adattano sempre di più al tuo team.

diffox blocca un merge?

No. Lo stato di diffox su una pull request non diventa mai rosso e non è un controllo obbligatorio; il tuo team fa il merge quando vuole.

A ogni push viene riesaminata tutta la pull request?

No. diffox esamina automaticamente ogni push ma legge solo la modifica nuova. Dopo i primi 5 push esamina quando lo chiedi tu; puoi cambiare questo numero dalla console.

Perché i suggerimenti non vengono pubblicati sulla pull request?

Nelle nostre misure, pubblicare anche i suggerimenti aggiungeva commenti alla pull request e abbassava la quota di bug reali tra questi. Per questo sulla pull request arrivano i rilievi critici e gli avvisi. I suggerimenti non vanno persi: aspettano 30 giorni nella pagina Rilievi, e da lì pubblichi quelli che vuoi.

diffox conserva il mio codice?

No. diffox non conserva una copia del codice che esamina; la copia del repository viene eliminata al termine dell’esame. Quali servizi vengono usati è indicato nella nostra pagina sulla privacy.

Il seguito: il modello decisionale

Il quarto articolo descrive il modello decisionale che diffox ultra usava allora nella quarta fase e la regola che abbiamo ricavato dalle nostre misure: Come usiamo Jev per due compiti nella code review con IA.