Agenti di coding AI: servono review packet

Gli agenti di coding AI hanno bisogno di review packet, non di prompt più grandi. È questo il cambio operativo che product leader ed engineering leader dovrebbero introdurre prima di allargare l’uso degli agenti nella delivery.

Un prompt lungo dà una sensazione di controllo. Dentro ci puoi mettere istruzioni, vincoli, esempi, regole di stile, divieti, eccezioni e avvertenze. Ma quando un agente apre una pull request, chi fa review non ha bisogno di leggere la storia completa di tutto ciò che il prompt cercava di evitare. Ha bisogno di un passaggio di consegne breve, verificabile e concreto.

Il rischio non è solo che l’agente scriva un bug. Anche le persone scrivono bug. Il rischio più serio è che il team accetti output non posseduto da nessuno perché sembra completo, compila in locale e arriva con una spiegazione abbastanza sicura da abbassare la diffidenza giusta. Un review packet riporta l’output dell’agente dentro il lavoro di engineering. Spiega cosa voleva ottenere la modifica, quali parti del sistema ha toccato, come è stata verificata, cosa non ha funzionato, chi decide sul rilascio e come si torna indietro se la produzione racconta un’altra storia.

Il prompt non è il passaggio di consegne

Un buon prompt aiuta l’agente a partire. Non basta per aiutare il team a chiudere.

Le best practice di OpenAI per Codex insistono su contesto persistente tramite AGENTS.md, obiettivi chiari, vincoli, comandi di test e lint, aspettative di review e verifica del risultato. È una direzione utile perché sposta il lavoro dagli esperimenti isolati a un ambiente operativo ripetibile. La guida suggerisce anche di chiedere all’agente di eseguire i controlli rilevanti, confermare il comportamento e rivedere il proprio diff prima dell’accettazione.

Queste pratiche migliorano la qualità della generazione, ma non sostituiscono il giudizio di rilascio. Il passaggio di consegne deve comunque reggere una review umana, una merge queue, un canale incident e uno sviluppatore futuro che prova a capire perché quella modifica esiste.

Qui molti team ottimizzano la cosa sbagliata. Vedono una PR debole prodotta da un agente e rispondono creando un master prompt più lungo. Il prompt diventa un deposito di preferenze: usa i nostri pattern, non toccare billing, evita migrazioni rischiose, ricorda l’accessibilità, aggiungi test, tieni piccolo il diff, spiega i tradeoff. Alcune di queste cose appartengono alla guida riutilizzabile del repository. Alcune appartengono ai criteri di accettazione. Quasi nessuna dovrebbe essere l’unica evidenza dentro la PR.

Se il team fatica già a definire cosa significa done, parti da AI coding: prima i criteri di accettazione. Se invece il team mergea senza una vera via d’uscita, affianca questo tema ad Agenti AI: servono piani di rollback. Il review packet sta in mezzo: è l’artefatto che permette a chi fa review di chiedersi, in fretta e in modo concreto, se la modifica costruita dall’agente è abbastanza sicura da rilasciare.

Cosa deve contenere il review packet?

Il packet deve essere abbastanza leggero da essere usato davvero. Se diventa una seconda specifica, marcisce. Può vivere nella descrizione della pull request, in un template di issue o nella checklist della merge request.

Dovrebbe contenere sette campi.

Intento. Una o due frasi che descrivono l’esito utente, business o operativo. Non “refactor del servizio auth”. Meglio: “Impedire che link di invito scaduti creino workspace attivi, mantenendo invariato il flusso di reinvio.”

Superfici toccate. Elenca moduli, route, tabelle, feature flag, job asincroni, API esterne e schermate coinvolte. Aiuta a indirizzare la review alle persone giuste. E blocca un fallimento tipico degli agenti: una modifica che sembra locale ma altera in silenzio un’astrazione condivisa.

Criteri di accettazione. Linka o riporta le condizioni che devono essere vere perché il lavoro sia considerato fatto. Qui il product leadership deve restare nel giro. Se l’agente non riesce a collegare il diff ai criteri di accettazione, il team sta rivedendo codice senza rivedere la decisione.

Evidenza di test. Indica test, lint, type check, build e flussi manuali eseguiti. Servono risultati, non impressioni. “I test passano” è debole. “pnpm test packages/invites passato in locale alle 14:32; flusso Playwright invite-resend passato su preview” è molto più utile.

Fallimenti noti. Questo campo è importante perché le PR degli agenti spesso nascondono incertezza dietro sintesi lucidissime. Se un test è fallito ed è stato giudicato non correlato, scrivilo. Se un percorso QA manuale non è stato eseguito perché mancava una credenziale di terza parte nel sandbox, scrivilo. Se la migrazione non è stata provata, scrivilo.

Owner. Nomina la persona responsabile della decisione di rilascio. Non deve essere per forza chi ha invocato l’agente. Deve essere chi può decidere se il packet è sufficiente, chiedere altra evidenza, rimandare il merge o gestire il follow-up se qualcosa va storto.

Link di rollback. Linka feature flag, piano di revert, runbook, rollback della migrazione o checkpoint di deploy. Per le modifiche generate da agenti, il rollback non può essere una promessa vaga. Deve essere visibile prima del merge.

I review packet riducono il teatro della velocità

La ricerca DORA su AI-assisted software development inquadra l’AI dentro il sistema di delivery, non come scorciatoia per aggirarlo. La ricerca DORA 2025 descrive l’AI come un amplificatore dei punti di forza e delle debolezze già presenti nell’organizzazione. È l’avvertimento giusto per i leader: se il processo di code review è fragile, gli agenti non lo renderanno magicamente rigoroso. Potrebbero solo aumentare il volume di lavoro che entra in un processo fragile.

Senza packet, l’adozione degli agenti produce teatro della velocità. Il team può mostrare più PR, draft più rapidi e meno tempo tra ticket e diff. Ma se chi fa review non vede intento, rischio, evidenza e ownership, il sistema reale non è diventato più veloce. È diventato più rumoroso.

Un review packet cambia la conversazione sulla performance. Invece di chiedere “L’agente ha finito?”, il team chiede “La modifica è reviewable?” Invece di celebrare righe generate, guarda l’evidenza di rilascio. Invece di discutere se il prompt debba essere più lungo, migliora i campi mancanti nell’ultima PR rischiosa.

È anche il modo in cui i product leader restano coinvolti senza fingersi code reviewer. Non devono ispezionare ogni dettaglio implementativo. Devono sapere se la modifica corrisponde al comportamento accettato, se la classe di rischio è coerente con il rollout e se esiste un owner umano. Questa è governance della delivery, non micromanagement.

Dove devono intervenire i leader?

Non partire comprando un altro tool o imponendo un prompt aziendale. Parti da un repository e da una classe di modifiche in cui l’output degli agenti entra già nel flusso di review.

Aggiungi una sezione nel template PR chiamata “AI review packet”. Rendila obbligatoria per ogni modifica generata, modificata o revisionata in modo sostanziale da un agente. Mantieni la forma semplice:

• Intento
• Superfici toccate
• Criteri di accettazione
• Controlli eseguiti
• Controlli falliti o saltati
• Owner umano
• Link di rollback

Poi rivedi cinque PR recenti prodotte con agenti. Non valutarle solo in base al fatto che alla fine abbiano funzionato. Valutale in base alla possibilità di ricostruire la decisione al momento del merge. Si capiva cosa cambiava? Si vedevano i test rilevanti? Si capiva cosa non era stato verificato? Si trovava l’owner? Si poteva tornare indietro?

Se la risposta è no, il problema non è la lunghezza del prompt. Il problema è che l’organizzazione ha lasciato passare output fuori dalla normale traccia di evidenza. È correggibile, ma solo se l’adozione degli agenti viene trattata come cambiamento di workflow, non come trucco privato di produttività. È lo stesso punto discusso in AI-assisted delivery: più output non significa più controllo.

Parti da una PR

Il prossimo passo è volutamente piccolo. Scegli una PR recente generata da AI e ricostruisci il review packet a posteriori. Non riscrivere la storia. Aggiungi i fatti mancanti come commenti: intento, superfici, test, fallimenti, owner, rollback.

L’esercizio farà emergere il vero gap. Forse i criteri di accettazione erano vaghi. Forse l’agente ha toccato un modulo condiviso inatteso. Forse i test non sono stati eseguiti perché l’ambiente locale è rotto. Forse il rollback esiste in teoria, ma non come link utilizzabile sotto pressione.

Questo è il lavoro utile. Prompt più grandi possono migliorare il draft. I review packet migliorano il passaggio di consegne. Se gli agenti di coding AI devono diventare parte della delivery, ogni modifica generata da un agente deve arrivare come qualcosa che un team umano può rivedere, possedere e annullare in sicurezza.