Una review che collega intento, prova e contenimento giudica il comportamento di una modifica, non chi ne ha prodotto il diff.
La pull request è verde, il diff è breve e il test d’integrazione passa. Poi qualcuno domanda che cosa succeda se il servizio remoto completa la richiesta ma la risposta si perde durante il timeout. Se nessuno sa rispondere, il problema non è l’origine del codice: è che la modifica ha introdotto un comportamento che il team non sa ancora verificare.
Per chi guida un team, questa è la distinzione utile quando si usa l’IA per proporre patch, test o alternative: non separare il codice digitato da una persona da quello suggerito da uno strumento, ma distinguere ciò che è spiegabile, verificabile e contenibile da ciò che sembra soltanto plausibile. Un revisore non deve fare archeologia tra catch, convenzioni locali e chiamate esterne per indovinare l’invariante di una PR.
La forma della review cambia di conseguenza. Non chiedi all’autore di difendere la paternità del diff; gli chiedi quale comportamento introduce, quale comportamento deve restare impossibile e quale evidenza permetterà al team di accorgersi di aver sbagliato. È una disciplina utile anche per il codice scritto interamente a mano.
Il sintomo: diff piccolo, responsabilità grande
Una patch proposta dall’IA può essere perfettamente coerente con il repository: usa il client già presente, copia lo stile della funzione vicina, gestisce un errore e aggiunge un test sul caso felice. La coerenza locale, però, non dimostra che il comportamento sia corretto oltre il file modificato.
Il problema appare quando il cambio attraversa un confine: una coda, un database, un servizio remoto, uno schema condiviso o un job che verrà rieseguito. Il diff rende visibili istruzioni aggiunte e rimosse; non rende visibile da solo la regola che le tiene insieme. Se quella regola resta implicita, il revisore deve ricostruirla dall’implementazione e l’on-call dovrà farlo di nuovo quando il sistema si comporterà in modo inatteso.
Una modifica è piccola soltanto se chi la presenta sa spiegare il suo effetto oltre le righe che cambia. La misura utile non è la dimensione del diff, ma il raggio del comportamento che può modificare. Un rename locale ha una superficie ridotta; un retry vicino a un effetto esterno può avere poche righe e una superficie molto più ampia.
Per questo una domanda come «hai usato l’IA?» non migliora la decisione. Chiedi invece: quale stato non deve mai risultare possibile dopo il merge? Quale effetto può avvenire al massimo una volta? Quale assunzione sul confine remoto rende sicura questa riga? Le risposte devono collegare la patch a un contratto osservabile, non a una dichiarazione di fiducia.
Il meccanismo: dall’intento al segnale
Una review affidabile mette in relazione più superfici di evidenza. La nota di intento nomina ciò che si vuole preservare; il diff mostra il tentativo di realizzarlo; una prova eseguibile mette alla prova una parte dell’affermazione; contratto, telemetria e contenimento chiariscono che cosa accade oltre il percorso felice. Nessuna di queste superfici sostituisce le altre.
flowchart LR
I[Intento e invariante] --> D[Diff]
D --> P[Prova eseguibile]
P --> C[Contratto del confine]
C --> S[Segnale osservabile]
S --> R[Contenimento o rollback]
R -. verifica .-> I
Il diagramma non descrive una procedura burocratica in sei passaggi. Mostra che ogni artefatto risponde a una domanda diversa: che cosa deve restare vero, come viene implementato, quale scenario si può riprodurre, che cosa il confine promette e come si limita il danno se il segnale contraddice l’ipotesi. La review diventa più breve quando queste domande hanno una sede chiara, perché non vengono ripetute nei commenti riga per riga.
| Superficie di evidenza | Cosa stabilisce | Punto cieco |
|---|---|---|
| Nota di intento o invariante | Il comportamento che deve restare vero | Può essere corretta ma non realizzata dal codice |
| Diff | L’implementazione introdotta | Non espone tutte le assunzioni né gli effetti distribuiti |
| Test mirato o comando riproducibile | L’esito di uno scenario definito | Può mancare timeout, concorrenza o stato parziale |
| Contratto di schema o API | Ciò che è ammesso al confine | Non prova la semantica dei chiamanti nel tempo |
| Segnale osservabile | Ciò che accade dopo il deploy | Arriva dopo l’esposizione al traffico |
| Contenimento o rollback | Come ridurre l’impatto | Non corregge un guasto che nessuno ha compreso |
La tabella non è un invito a produrre un documento operativo per ogni PR. Serve a evitare due equivalenze sbagliate: test verde uguale intento dimostrato, oppure rollback disponibile uguale rollback sicuro. Un test può essere preciso e comunque non coprire il confine che rende rischiosa la modifica; un rollback può spegnere il nuovo percorso senza cancellare l’effetto che ha già prodotto.
Il punto di rottura: retry e risposta persa
Un retry verso un servizio remoto è un caso utile perché la patch appare lineare: invii una richiesta, intercetti un errore transitorio, ritenti. Il caso critico non è il rifiuto esplicito. È la risposta persa dopo che il servizio ha già eseguito l’operazione.
sequenceDiagram
participant C as Client
participant G as Gateway
participant S as Servizio remoto
C->>G: richiesta con chiave di idempotenza
G->>S: inoltro
S->>S: esegue l'effetto
S--xG: risposta persa
G--xC: timeout percepito
C->>G: retry con la stessa chiave
G->>S: inoltro del retry
alt confine idempotente
S-->>G: risultato già registrato
G-->>C: risposta coerente
else confine ambiguo
S->>S: duplica l'effetto
S-->>G: secondo risultato
G-->>C: successo con stato duplicato
end
Il timeout non dice al client se il server abbia eseguito o meno la richiesta. Se l’operazione crea un ordine, invia un’email, prenota una risorsa o compie un’altra scrittura non idempotente, un secondo invio può creare un secondo effetto. Il comportamento da decidere non è quindi «quanti retry consentire», ma se il confine riconosce la stessa intenzione come la stessa operazione.
- await remote.createOrder(payload)
+ await remote.createOrder({
+ ...payload,
+ idempotencyKey: requestId,
+ })
Il diff è utile soltanto se la chiave viene generata con una semantica chiara, arriva al servizio che deve deduplicare e il contratto spiega quale risultato viene restituito al retry. Se il servizio non supporta quella proprietà, aggiungere una chiave al payload non la crea. Potrebbe essere più corretto non ritentare, cambiare il contratto o isolare il nuovo percorso dietro un flag.
Un retry senza semantica dichiarata è una seconda esecuzione mascherata da disponibilità. Il test da chiedere deve simulare una risposta persa, non soltanto un errore prima dell’invio. Il segnale deve distinguere almeno il tentativo iniziale, il retry e un risultato già noto, così che il team possa capire se sta recuperando da un timeout o moltiplicando un effetto.
La diagnosi: domande che provano il comportamento
La provenienza del codice non è un buon criterio diagnostico. Un autore può comprendere una patch suggerita dall’IA e documentarla bene; può anche incollare uno snippet noto senza sapere perché una guardia esista. In entrambi i casi la lacuna è la stessa: manca un modello esplicito del comportamento.
Durante la review, chiedi all’autore di rispondere in modo proporzionato alla superficie toccata:
- Quale cambiamento osserverà un chiamante, un operatore o un job successivo?
- Quale invariante era vera prima e deve restare vera ora?
- Quale input, risposta o stato parziale rende insufficiente il caso felice?
- Che cosa dimostra la prova eseguibile, e che cosa lascia fuori deliberatamente?
- Se il deploy contraddice l’intento, quale azione limita l’impatto senza crearne un secondo?
Queste domande non richiedono una relazione per una funzione pura. Per quella, può bastare una frase e un test. Se la modifica attraversa schema, API e lavoro asincrono, l’autore deve mostrare più collegamenti perché il comportamento dipende da più confini. La proporzione riguarda il rischio del cambiamento, non la quantità di testo prodotta.
Un revisore può capire perfettamente il codice e non avere ancora una ragione sufficiente per approvarlo. Sapere che un catch ritenta una richiesta non chiarisce se il retry sia ammesso dal contratto. Allo stesso modo, un test può passare e non dimostrare l’intento scritto: prova un caso scelto, mentre l’intento spiega perché quel caso è importante e quale stato non deve comparire.
Quando valuti quali workflow IA vale adottare con intenzione, il punto non è aggiungere un rituale a ogni suggerimento. Devi decidere dove lo strumento può accelerare la produzione di alternative e dove il team deve rallentare abbastanza da rendere la decisione verificabile. È un confine operativo, non un giudizio sullo strumento.
La risposta: una pratica breve, non un interrogatorio
Per una modifica consequenziale, inserisci nella PR tre campi brevi e controllabili. Non una formula generica da compilare, ma informazioni che il revisore possa collegare al diff e al comportamento:
- Intento e invariante: che cosa cambia e quale stato deve restare impossibile.
- Evidenza eseguibile: il test, il comando o lo scenario che mette alla prova l’affermazione principale.
- Contenimento: come fermare, limitare o invertire il comportamento se il segnale osservato contraddice l’intento.
Il costo esiste: l’autore deve preparare una spiegazione e una review urgente può rallentare. L’alternativa trasferisce però il costo a chi ricostruisce l’invariante dal repository, a chi è on-call sotto pressione e a chi eredita la condizione nella PR successiva. La spiegazione consegna a chi gestisce l’incidente un modello di guasto prima dell’allarme.
Se questi tre campi non si collegano chiaramente al diff, non serve attribuire una colpa all’IA. Riduci la modifica, aggiungi una prova o rendi esplicita l’assunzione prima del merge. Separare un retry, una migrazione di schema, una modifica di contratto e un refactor del client può rendere la decisione più veloce, perché ogni parte torna spiegabile da chi la propone.
La stessa pratica sostiene un’architettura semplice quando il sistema è difficile da capire. Non perché ogni componente debba essere minimale, ma perché ogni confine aggiunto deve poter essere spiegato, osservato e isolato quando fallisce. Per Tech Lead e team che vogliono allenare questa conversazione su PR reali, un percorso di ai-training può partire da una modifica già in coda e dal comportamento che oggi nessuno riesce a dimostrare con sicurezza.
Domande frequenti
Vale anche per modifiche piccole o banali?
Sì, ma in proporzione. Un rename locale o una correzione che non cambia il comportamento non richiedono un piano di rollback articolato. Se una modifica tocca un contratto, una persistenza, un retry o un effetto esterno, le poche righe del diff non bastano a definirla banale.
Se il revisore capisce il codice ma l’autore non sa spiegarlo, è davvero un problema?
Sì. Il revisore potrebbe aver inferito un comportamento diverso da quello che l’autore intendeva introdurre. L’approvazione è più affidabile quando l’autore formula l’invariante e tu ne verifichi l’evidenza, invece di lasciare che entrambi assumano la stessa cosa senza dirla.
I test sostituiscono l’intento scritto?
No. Un test dimostra un caso, o una famiglia di casi, ma non chiarisce sempre perché quel caso sia decisivo. L’intento ti permette di valutare se la prova è ben scelta; la prova impedisce che l’intento resti una frase convincente ma non controllabile.
Questa pratica serve soltanto al codice generato dall’IA?
No. Vale per codice umano, snippet copiati, librerie adattate e refactor eseguiti in fretta. L’origine del testo non cambia la necessità di verificare comportamento, evidenze e possibilità di contenimento.
Nella prossima PR consequenziale, chiedi prima dell’approvazione l’invariante, una prova eseguibile e il modo di fermare il cambiamento: se non si riescono a nominare, la modifica non è ancora pronta per la review.