L'AI coding ha bisogno di checkpoint di ambiguità

L’AI-assisted coding cambia la forma del lavoro di sviluppo perché sposta lo sforzo dalla scrittura al giudizio. Un modello può produrre rapidamente un’implementazione plausibile, a volte con test utili e una spiegazione ordinata. Quella velocità è reale. Lo è anche il rischio: una modifica può compilare, superare un happy path ristretto e nascondere comunque assunzioni di prodotto non risolte, scorciatoie rischiose, test mancanti o dubbi emersi durante il debugging.

La tesi è semplice: l’AI-assisted coding ha bisogno di checkpoint di ambiguità. Non più burocrazia, non una seconda code review, non un generico invito a stare attenti. Un checkpoint è un piccolo momento di handoff, esplicito, tra la bozza generata e il review packet. Serve a catturare ciò che l’AI ha fatto sembrare finito, ma che una persona deve ancora possedere.

Addy Osmani descrive questo schema come il “70% problem”: l’AI può portare il lavoro gran parte della strada verso una soluzione funzionante, mentre la parte finale richiede handoff umano, gestione dell’ambiguità, debugging e presenza attiva quando le macchine fanno molta parte della digitazione. Questa cornice è importante perché l’ultimo 30% non è semplice rifinitura. È il punto in cui la responsabilità diventa visibile. La fonte di riferimento è il recap di Osmani sull’AI-assisted engineering: AI-Assisted Engineering: My 2025 Substack Recap.

L’ultimo 30% è un problema di handoff

Il problema non è sempre codice sbagliato. Spesso è codice che sembra buono, ma con ownership poco chiara.

Una sviluppatrice chiede a un tool di AI coding di aggiungere un’impostazione, rifattorizzare un componente, generare una migration o collegare una nuova risposta API a un’interfaccia. L’output sembra coerente. I file toccati sono quelli plausibili. I nomi sono abbastanza allineati. Il modello spiega il lavoro con sicurezza. Il team sente di aver guadagnato velocità.

Poi inizia la review e l’ambiguità emerge. Perché è stato scelto quel comportamento per lo stato vuoto? La migration copre i record esistenti o solo quelli nuovi? L’agente ha rispettato il confine di autorizzazione previsto o ha copiato il pattern più vicino? I test dimostrano la regola di business o congelano soltanto l’implementazione generata? Chi ha verificato l’edge case citato nel ticket ma non inserito nel prompt?

Se queste domande compaiono per la prima volta in code review, la review sta facendo due lavori insieme. Valuta la modifica e ricostruisce l’intento. È costoso. Crea anche incentivi sbagliati: i reviewer finiscono per concentrarsi su stile, naming e bug evidenti perché l’incertezza più profonda non è stata preparata per loro.

Per questo i criteri di accettazione restano necessari. Nell’articolo AI coding: prima i criteri di accettazione il punto è che il prompt non dovrebbe essere il primo luogo in cui il team definisce cosa significa done. Il checkpoint di ambiguità estende l’idea più a valle. Anche con buoni criteri, il lavoro generato rivelerà punti in cui i criteri erano incompleti, il codebase aveva convenzioni implicite o la strada implementativa ha imposto una scelta.

Cosa deve contenere un checkpoint di ambiguità?

Un checkpoint di ambiguità deve essere abbastanza leggero da essere usato nel lavoro reale. Se diventa un documento che nessuno aggiorna, verrà saltato. L’obiettivo è rendere l’handoff ispezionabile prima della review, non creare un archivio di compliance.

Usa cinque campi.

Primo: assunzioni di prodotto non risolte. Non sono note tecniche. Sono frasi come: “Ho assunto che lo stato di default debba mostrare l’etichetta legacy finché l’utente non salva”, oppure “Ho assunto che admin e owner condividano lo stesso percorso di permessi.” Se l’assunzione cambia esperienza utente, modello dati, regola di prezzo o comportamento operativo, va scritta qui.

Secondo: scorciatoie implementative. Il codice generato dall’AI spesso segue il pattern locale più disponibile. Può andare bene, ma il reviewer non dovrebbe scoprirlo leggendo ogni riga del diff. Scrivi la scorciatoia in modo diretto: “Riutilizzato il parser esistente anche se non valida i campi sconosciuti”, oppure “Mantenuta la chiamata sincrona perché il flusso circostante è sincrono.” Una scorciatoia non è automaticamente un errore. Il problema sono le scorciatoie nascoste.

Terzo: test mancanti. Non basta scrivere “servono più test”, perché non aiuta nessuno. Nomina la prova assente: “Nessun test per account eliminato”, “Nessuna fixture con più valute”, “Nessun test di rollback della migration”, oppure “Nessun test browser per la navigazione da tastiera.” Così il reviewer riceve una mappa del rischio, non una richiesta generica di attenzione.

Quarto: note di debugging. Qui la persona registra cosa è sembrato sospetto durante il lavoro con il modello: tentativi falliti, stack trace confusi, comportamenti flaky, sezioni rigenerate o punti in cui il modello si è contraddetto. Queste note sono preziose perché il lavoro assistito dall’AI può nascondere l’esplorazione. Il diff finale può sembrare lineare anche quando il percorso è stato disordinato.

Quinto: owner del giudizio finale. Non l’autore di default e non “il team”. Se un’assunzione di prodotto richiede conferma del PM, nomina il PM. Se una migration dati richiede review di staff engineering, nomina quella persona o quel ruolo. Se la postura di sicurezza è incerta, nomina l’approvatore. L’ownership deve seguire l’ambiguità, non il commit.

In cosa è diverso dalla code review?

Il checkpoint di ambiguità avviene prima della code review e ha uno scopo diverso.

La code review chiede: “Questa modifica deve entrare nel codebase?” Il checkpoint chiede: “Quale giudizio umano serve ancora prima di poter rispondere a quella domanda?” La differenza è sottile, ma decisiva. La review è una superficie decisionale. Il checkpoint è una superficie di preparazione.

Senza checkpoint, i review packet diventano sovraccarichi. L’articolo Agenti di coding AI: servono review packet spiega perché il lavoro generato dall’AI va confezionato in modo che i reviewer vedano intento, scope ed evidenze. Il checkpoint di ambiguità è un ingrediente di quel packet. È la parte che ammette cosa non è ancora risolto.

Qui i team devono anche evitare la recita della certezza. Un assistente AI può produrre un bel riassunto: file modificati, funzioni aggiunte, test aggiornati. È utile, ma non basta. Una persona deve aggiungere le parti che il modello non è qualificato a possedere: significato di business, tolleranza al rischio, contesto di produzione e ciò che è stato deliberatamente escluso.

Un buon checkpoint non è una confessione di fallimento dell’AI. È la prova che il team è rimasto nel loop. Dice: qui la macchina ci ha accelerato, qui il codebase ha fatto resistenza, qui una persona deve decidere.

Come si introduce nel team?

Parti da una classe di lavoro, non da ogni modifica. Scegli cambiamenti assistiti dall’AI che toccano comportamento di prodotto, persistenza dati, permessi, billing, onboarding o workflow visibili ai clienti. Non iniziare da microcopy innocue o refactor meccanici. Il checkpoint è più utile dove un output plausibile può creare ambiguità reale.

Aggiungi un template breve alla pull request o al review packet:

• Assunzioni di prodotto:
• Scorciatoie prese:
• Test mancanti:
• Note di debugging:
• Owner del giudizio finale:

Lascia i campi vuoti solo quando sono davvero vuoti. “Nessuna notata” è meglio del silenzio perché obbliga l’autore a fare una dichiarazione. Se un reviewer trova poi un’assunzione non elencata, il team ha un punto concreto da migliorare nel checkpoint successivo.

Il checkpoint aiuta anche i PM a partecipare senza fingere di fare review riga per riga. Un PM può leggere le assunzioni di prodotto e decidere se il comportamento corrisponde all’esito desiderato. Un engineering lead può scansionare scorciatoie e test mancanti. Un reviewer può leggere il diff con il giusto modello di rischio.

Questo non sostituisce il pensiero sul rollback. Per lavoro AI sensibile alla produzione, Agenti AI: servono piani di rollback resta lo strato successivo. Il checkpoint di ambiguità risponde a quale giudizio serve prima del merge. Il piano di rollback risponde a come il team recupera se quel giudizio si rivela incompleto.

Fai un checkpoint prima del prossimo merge

Il test pratico è semplice. Prendi una modifica generata con AI questa settimana e segna il primo punto in cui è diventato necessario il giudizio umano. È successo quando il modello ha scelto una forma dati? Quando ha dedotto una regola di business? Quando ha saltato un test? Quando il debugging è passato dalla sintassi al comportamento del sistema? Quello è il checkpoint.

Non misurare la pratica solo dal fatto che rallenti o meno la prima pull request. Potrebbe rallentarla. Misurala dal fatto che la review diventi più chiara, che le assunzioni smettano di nascondersi nel codice generato e che l’ownership finisca alla persona più adatta a decidere.

L’AI-assisted coding non è pericoloso perché scrive codice. È pericoloso quando i team confondono progresso plausibile con delivery responsabile. I checkpoint di ambiguità rendono visibile l’handoff. Conservano la velocità dell’assistenza AI, ma riportano l’ultimo 30% allo scoperto, dove giudizio di prodotto, giudizio tecnico e ownership possono fare il loro lavoro.