Siamo onesti su qualcosa che la maggior parte di noi non dice ad alta voce: rivediamo a malapena il codice generato dall'IA.

Il diff è di 600 righe. L'agente ha toccato 14 file. Apri la pull request, scorri le modifiche, strizzi gli occhi su un paio di funzioni e fai merge. Forse fai girare i test prima. Forse no. Il codice sembra ragionevole. L'agente ha detto che ha finito. Si shippa.

Questa non è pigrizia. È un problema strutturale. La code review tradizionale è stata progettata per un mondo in cui un umano scriveva il codice e poteva spiegare il suo ragionamento quando richiesto. Dove i diff erano di 50-200 righe perché è quanto una persona scrive in una sessione concentrata. Dove la descrizione della PR diceva "Ho scelto l'approccio X per via di Y" e potevi fidarti di quel contesto.

Gli agenti IA non funzionano così. Claude Code può produrre 500 righe di codice funzionante in due minuti. La descrizione della PR spesso è solo "implementare feature X." Il diff ti dice cosa è cambiato ma niente sul perché. Nessun registro di quali alternative l'agente ha considerato. Nessuna spiegazione di quali compromessi ha fatto. Nessuna prova che abbia effettivamente testato qualcosa. Stai revisionando l'output di una scatola nera, e lo strumento di review ti mostra solo l'output.

Questo articolo analizza perché la review basata sui diff fallisce per l'output degli agenti, qual è il livello realmente mancante, e un pattern concreto che rende il codice generato dall'IA revisionabile senza triplicare il tempo di review.

Il gap della review

Gli sviluppatori sono onesti su questo in privato. Nei thread della community, il pattern si ripete: "Per lo più scorro i diff degli agenti." "Verifico che i test passino e faccio merge." "Se sembra più o meno giusto, approvo."

Questo è un comportamento razionale date le limitazioni. Quando un collega umano invia una PR, hai contesto: sai su cosa stava lavorando, hai visto il ticket, forse avete discusso l'approccio allo standup. Il diff è supplementare. La vera review è avvenuta attraverso il contesto condiviso.

Con un agente, non hai niente di tutto questo. L'agente ha preso un task, è rimasto in silenzio per tre minuti e ha prodotto un diff. L'unico contesto è la descrizione di una riga che l'agente ha lasciato sulla PR. Revisionare quel diff da zero, senza contesto sull'intento o il ragionamento, richiede 5-10x più tempo che revisionare una PR umana della stessa dimensione. Quindi le persone non lo fanno. Controllano a campione alcune aree critiche e approvano.

Il risultato è prevedibile. Passano bug che sarebbero stati individuati con il contesto. Il drift architetturale si accumula mentre gli agenti prendono piccole decisioni che si compongono. La qualità del codice degrada in modi sottili: non rotto, ma neanche del tutto corretto. Gestione degli errori incoerente in un file. Una query al database che funziona ma scala male. Una nuova funzione utility che duplica una esistente perché l'agente non sapeva che esistesse.

Nessuno di questi fallimenti è visibile in una review del diff. Sono visibili solo quando capisci cosa l'agente stava cercando di fare e puoi confrontare il suo intento con la sua esecuzione.

Perché i diff non bastano

Un diff è un registro di modifiche testuali. Stop. Per la code review umana, i diff funzionano perché il revisore può inferire l'intento dal riconoscimento di pattern e dal contesto condiviso. Vedi un collega aggiungere un blocco try/catch e sai che sta gestendo il caso di errore dal bug report della settimana scorsa. Lo vedi rinominare una funzione e sai che sta seguendo la convenzione di naming su cui il team si è accordato.

Con codice generato da agente, non puoi inferire l'intento perché non facevi parte del processo di ragionamento. Ecco cosa un diff di 500 righe di un agente ti dice effettivamente:

Quali file sono stati modificati
Quali righe sono state aggiunte, cambiate o rimosse
La struttura sintattica del nuovo codice

Ecco cosa non ti dice:

Perché è stato scelto questo approccio. L'agente potrebbe aver considerato tre implementazioni diverse. Ne ha scelta una. Non sai perché. Forse quella scelta è ottimale. Forse è la prima cosa che ha provato e funzionava abbastanza bene. Dal diff non puoi saperlo.

Quali alternative sono state scartate. Se l'agente ha scelto una strategia di polling invece di subscription WebSocket, è stata una decisione architetturale deliberata o un incidente? Un diff non lo dice.

Se l'implementazione corrisponde alla spec. Dovresti aprire la spec in una finestra e il diff in un'altra e incrociare manualmente ogni criterio di accettazione. La maggior parte delle persone non lo fa.

Cosa è stato testato e come. Il diff potrebbe includere nuovi file di test. Ma l'agente li ha eseguiti? Sono passati? Coprono i casi limite della spec? Dovresti fare checkout del branch e eseguirli tu stesso per saperlo.

Se l'agente è rimasto nello scope. Forse il task era "fixare il bug di login" e l'agente ha anche refactorizzato il middleware di auth, rinominato due funzioni utility e aggiornato lo schema di configurazione. Tutti questi cambiamenti sembrano corretti in isolamento. Ma non sono stati richiesti, non sono stati specificati e non sono stati testati rispetto ai criteri di accettazione originali.

Questo non è un problema di un particolare strumento di diff. L'interfaccia di review di GitHub, le merge request di GitLab, Gerrit, git diff nel terminale. Tutti ti mostrano la stessa cosa: cosa è cambiato. Per l'output degli agenti, "cosa è cambiato" è la domanda meno importante. La domanda importante è: questo cambiamento fa quello che doveva fare, e nient'altro?

Il livello mancante: narrativa di implementazione

Ciò di cui i revisori hanno realmente bisogno è la traccia del ragionamento dell'agente. Non il diff. La storia dell'implementazione: cosa l'agente ha pianificato di fare, cosa ha effettivamente fatto e come ha verificato il risultato. Chiamalo narrativa di implementazione.

Una buona narrativa di implementazione risponde a cinque domande:

Qual era il piano? Prima di scrivere codice, cosa intendeva fare l'agente? Quali file, quale approccio, quale ordine di operazioni?
Cosa è successo durante l'implementazione? Il piano è sopravvissuto al contatto con la codebase? Ci sono state sorprese, pivot o cambiamenti di scope?
Qual è stato il risultato finale? Non il diff. Un riassunto in linguaggio chiaro di cosa è cambiato e perché.
Come è stato verificato? Passi specifici che l'agente ha intrapreso per confermare che l'implementazione funziona. Non "i test passano" ma "ho eseguito il criterio di accettazione #3 facendo X e ho osservato Y."
Cosa dovrebbe controllare il revisore? La raccomandazione dell'agente stesso su cosa merita attenzione umana. Forse c'è una decisione di design che potrebbe andare in entrambe le direzioni, o un compromesso di performance che merita un secondo parere.

Niente di tutto questo esiste in un workflow PR standard. Il campo descrizione della PR è testo libero che nessuno impone. Le PR degli agenti hanno descrizioni minime di default perché all'agente è stato detto di implementare, non di documentare il suo ragionamento.

Il gap non è il tooling. È il processo. L'infrastruttura di review esiste. Ciò che manca è un registro strutturato dell'intento dell'agente che il revisore possa verificare rispetto al diff.

Il pattern plan-comment-done

Ecco un pattern che chiude il gap senza aggiungere overhead significativo. Ha tre parti: l'agente commenta un piano prima di scrivere codice, implementa, e commenta un report done strutturato quando ha finito.

Passo 1: Il commento del piano

Prima che l'agente apra qualsiasi file, scrive cosa intende fare. Passi numerati, file che toccherà e l'approccio che prenderà.

PLAN: Fix WebSocket reconnection dropping messages during
server restart.

1. Add a message buffer to hooks/use-websocket.ts that queues
   outbound messages while the connection is in CONNECTING state
2. On successful reconnection, flush the buffer in order
3. Add a 30-second timeout: if reconnection hasn't succeeded,
   surface an error to the user via the toast system
4. Update the existing reconnection test to verify buffer
   behavior

Files: hooks/use-websocket.ts, components/connection-status.tsx

Test: Unit test for buffer queueing/flushing, manual test by
killing the WS server mid-operation and verifying no messages
are lost on reconnect.

Questo richiede all'agente circa 30 secondi. Il revisore lo legge in meno di 2 minuti. In quei 2 minuti, individui problemi che richiederebbero 20 minuti per trovare in una review del diff:

Lo scope è corretto? (Il piano dice 2 file. Se il diff tocca 6, qualcosa è deviato.)
L'approccio è solido? (Un buffer di messaggi con flush-on-reconnect è ragionevole. Se l'agente avesse proposto di ricaricare tutto lo stato dal server, vorresti discuterne prima.)
Mancano dei passi? (Cosa succede ai messaggi inviati durante la finestra di timeout? Devono essere scartati o ritentati?)

Il piano è un checkpoint leggero. Revisionalo, approvalo, e l'agente procede con una comprensione condivisa dell'intento.

Passo 2: Implementazione

L'agente scrive il codice. Niente cambia qui. Ma poiché il piano esiste, l'agente ha una roadmap da seguire invece di prendere decisioni ad hoc lungo il percorso.

Passo 3: Il commento done

Quando l'agente finisce, pubblica un report di completamento strutturato. Non "fatto." Non "implementata la feature." Un resoconto dettagliato di cosa ha effettivamente fatto.

DONE: WebSocket reconnection now buffers outbound messages
during CONNECTING state and flushes on successful reconnect.

Changes:
- hooks/use-websocket.ts: Added messageBuffer ref, queue
  messages when readyState !== OPEN, flush in FIFO order on
  'open' event. Added 30s reconnection timeout.
- components/connection-status.tsx: Shows "Reconnecting..."
  badge during buffer state, switches to error toast after
  timeout.

QA Verification:
1. Start dev server and WebSocket server
2. Open app, verify connection dot is green
3. Kill WebSocket server process
4. Trigger an action that sends a WS message (e.g., update
   a bead status)
5. Restart WebSocket server within 30 seconds
6. Verify: the buffered message is delivered, bead status
   updates in the UI
7. Repeat step 3, but wait >30 seconds before restart
8. Verify: error toast appears after timeout

Acceptance criteria:
- [x] Messages sent during reconnection are not lost (step 6)
- [x] Timeout surfaces user-visible error (step 8)
- [x] No behavior change when connection is stable (step 2)

Commit: f4e2a1b

Ora il revisore ha tutto ciò di cui ha bisogno. Legge il piano (cosa era inteso), legge il commento done (cosa è stato effettivamente costruito e come è stato verificato), e poi guarda il diff con il contesto completo. La review del diff passa da "cos'è tutto questo?" a "lasciami confermare che corrisponde a ciò che l'agente ha detto di aver fatto."

Checklist di review per l'output degli agenti

Anche con la narrativa di implementazione, hai bisogno di un approccio sistematico. Ecco una checklist che uso quando revisiono l'output di Claude Code. Richiede 5-10 minuti per review e individua le categorie di bug che i diff da soli mancano.

Allineamento con la spec:

L'implementazione affronta ogni criterio di accettazione della spec?
Ci sono cambiamenti che vanno oltre ciò che la spec richiedeva?
Il commento done mappa ogni criterio a un passo di verifica?

Contenimento dello scope:

L'agente ha modificato solo i file elencati nel suo piano?
Se ha toccato file aggiuntivi, c'è una ragione dichiarata?
Ci sono cambiamenti di "pulizia" (rinominazioni, riformattazioni, refactoring) che non facevano parte del task?

Copertura dei test:

Esistono nuovi test per i nuovi comportamenti?
I test testano effettivamente la cosa giusta? (Gli agenti a volte scrivono test che passano banalmente perché testano il mock, non l'implementazione.)
L'agente ha affermato di aver eseguito i test? C'è evidenza?

Coerenza architetturale:

I cambiamenti seguono i pattern esistenti nella codebase?
Ci sono nuove astrazioni che duplicano quelle esistenti?
La strategia di gestione degli errori corrisponde al resto del progetto?

Consapevolezza delle dipendenze:

Se l'agente ha aggiunto dipendenze, sono giustificate?
I cambiamenti rompono funzionalità esistenti? (Controlla i file che importano i moduli modificati.)
Se il task ha dipendenze da altri task, quelle dipendenze sono risolte?

Questa checklist funziona con qualsiasi strumento di code review. Stampala su un post-it, mettila nel tuo template PR, o integrala nella tua CLAUDE.md così che l'agente sappia a quale standard sarà misurato. Il punto non sono gli elementi specifici. È avere un protocollo strutturato invece di "mi sembra ok."

Beads come superficie di review

Il pattern plan-comment-done ha bisogno di un posto dove vivere. Se piani e commenti done sono sparsi tra messaggi Slack, descrizioni PR e output del terminale, perdi la connessione tra spec, piano, implementazione e verifica.

Questo è il problema che beads risolve. Beads è un issue tracker Git-nativo e open-source dove ogni "bead" porta l'intero ciclo di vita di un task: la spec come descrizione, i piani dell'agente come commenti, i report done come commenti e i risultati QA come commenti. Tutto allegato a una singola entità, ricercabile e permanente.

Ecco come appare il workflow di review con il CLI bd:

Creare il task con la spec:

bd create --title "Fix WebSocket reconnection message loss" \
  --description "## Problem
Messages sent during WebSocket reconnection are silently
dropped...

## Acceptance Criteria
1. Messages queued during CONNECTING state are delivered
   on reconnect
2. 30-second timeout surfaces error to user
3. No behavior change when connection is stable" \
  --type bug --priority p1

L'agente reclama il lavoro e pubblica un piano:

bd update bb-f4e2 --claim --actor eng1
bd comments add bb-f4e2 --author eng1 "PLAN: Add message
buffer to WebSocket hook...

1. Queue outbound messages when readyState !== OPEN
2. Flush buffer in FIFO order on 'open' event
3. Add 30s timeout with error toast
4. Update reconnection test

Files: hooks/use-websocket.ts, components/connection-status.tsx"

Revisioni il piano in 2 minuti:

bd show bb-f4e2  # Leggere spec + commento del piano

Se il piano sembra corretto, l'agente procede. Se no, commenti con correzioni prima che venga scritto qualsiasi codice.

L'agente completa e pubblica un report done:

bd comments add bb-f4e2 --author eng1 "DONE: WebSocket
reconnection now buffers outbound messages...

QA Verification:
1. Kill WS server, trigger action, restart within 30s...

Acceptance criteria:
- [x] Buffered messages delivered on reconnect
- [x] Timeout error visible
- [x] No regression on stable connection

Commit: f4e2a1b"

bd update bb-f4e2 --status ready_for_qa

QA verifica indipendentemente:

bd show bb-f4e2  # Leggere i passi di verifica dal commento done
# Eseguire ogni passo
bd comments add bb-f4e2 --author qa1 "QA PASS: All 3 criteria
verified. Buffer flushes correctly, timeout fires at 30s,
stable connections unaffected."

L'intera traccia di review è in un posto. Sei mesi dopo, quando qualcuno chiede "perché il WebSocket bufferizza i messaggi durante la riconnessione?", la risposta è nel bead: la spec spiega il problema, il piano spiega l'approccio, il commento done spiega cosa è stato costruito, e il commento QA conferma che funziona.

Quando la review da terminale raggiunge il suo limite

Eseguire bd show su un task ti dà tutto. Ma quando stai revisionando l'output di più agenti attraverso diversi workstream paralleli, il workflow CLI scala linearmente: un bd show per task, un bd list per vedere cosa è pronto per la review, un bd show per piano che devi approvare.

Qui si inserisce Beadbox. Beadbox è una dashboard in tempo reale che ti mostra ogni task nel tuo workspace con il suo stato attuale, ultimo commento e posizione nella pipeline di review. Vedi quali agenti hanno pubblicato piani che necessitano della tua approvazione. Quali hanno pubblicato report done pronti per la tua review. Quali sono ancora in corso. Tutto si aggiorna dal vivo mentre gli agenti scrivono commenti e cambiano stati attraverso il CLI bd.

Non hai bisogno di Beadbox per usare il pattern plan-comment-done. Il CLI gestisce l'intero workflow. Ma quando hai cinque agenti che producono output revisionabile simultaneamente, poter vedere la coda di review a colpo d'occhio invece di interrogare ogni task individualmente cambia la velocità con cui avanzi nella pipeline.

Beadbox è gratuito durante la beta, e il CLI beads su cui gira è open-source.

Il problema della review non si risolverà da solo

Il codice generato dall'IA aumenta più velocemente della nostra capacità di revisionarlo. Gli strumenti che abbiamo sono stati costruiti per una scala e un workflow diversi. GitHub PR, diff IDE, persino analisi statica sofisticata: nessuno di essi affronta il problema fondamentale, ovvero che revisionare codice senza conoscere l'intento dell'autore è drammaticamente più difficile che revisionarlo conoscendolo.

La soluzione non sono strumenti di diff migliori. È intento strutturato: un registro di cosa l'agente ha pianificato di fare, cosa ha effettivamente fatto e come ha verificato il risultato. Il pattern plan-comment-done ti dà quel registro senza aggiungere overhead significativo. L'agente spende 30 secondi a scrivere un piano. Tu spendi 2 minuti a revisionarlo. L'agente spende 60 secondi a scrivere un report done. Tu revisioni il diff con contesto completo invece che da zero.

Cinque principi da portare con sé:

Richiedi piani prima del codice. Un commento di piano da 30 secondi risparmia sessioni di review da 20 minuti. Se il piano è sbagliato, correggilo prima che il codice esista.
Pretendi report done strutturati. "Fatto" non è un report done. Passi di verifica, mappatura dei criteri di accettazione e hash dei commit sono un report done.
Revisiona rispetto alla spec, non al diff. Il diff mostra cosa è cambiato. La spec dice cosa avrebbe dovuto cambiare. Incrocia i riferimenti.
Imponi limiti di scope. Se l'agente ha toccato file fuori dal suo piano, è un segnale d'allarme. Cambiamenti non pianificati sono cambiamenti non revisionati.
Tratta la review come un protocollo, non un giudizio. Una checklist individua più bug dell'intuizione. "Mi sembra ok" non è una review.

Gli agenti continueranno ad accelerare. I diff continueranno a crescere. La domanda è se il tuo processo di review scala con loro, o se stai ancora strizzando gli occhi su diff da 600 righe sperando per il meglio.

Se stai costruendo workflow come questi, metti una stella a Beadbox su GitHub.

La code review dell'IA è rotta. Ecco cosa manca.