AI coding: prima i criteri di accettazione

Gli agenti di AI coding rendono troppo facile iniziare prima di aver definito il lavoro. Un founder scrive “sistema l’onboarding”. Una product lead chiede “migliora lo stato vuoto”. Un engineer dice “risolvi il bug intermittente della signup”. L’agente produce una diff, spesso plausibile, e il team passa la review a ricostruire cosa avrebbe dovuto significare davvero quel task.

È la conversazione sbagliata. Il collo di bottiglia non è solo capire se l’agente sappia scrivere codice. Il collo di bottiglia è capire se la persona gli abbia dato, prima di partire, una definizione di fatto ispezionabile.

La guida di OpenAI su Codex insiste proprio su questo punto operativo: i task funzionano meglio quando includono obiettivo, contesto rilevante, vincoli e ciò che deve essere vero alla fine. La stessa guida suggerisce di trattare Codex meno come un assistente occasionale e più come un compagno di lavoro da configurare e migliorare nel tempo, con contesto di progetto e abitudini di review. Riferimenti utili sono le best practice Codex di OpenAI e il documento su come OpenAI usa Codex.

La mossa pratica è semplice: trasformare il prompt in un contratto di task per l’agente prima che l’agente tocchi il codice.

Il prompt non è la definizione di fatto

Un prompt può esprimere un’intenzione. Non crea automaticamente responsabilità.

“Migliora il checkout” può voler dire ridurre il testo, cambiare il riepilogo ordine, gestire diversamente un pagamento fallito o sistemare le label di accessibilità. Sono tutte interpretazioni ragionevoli. Solo una, però, potrebbe essere il lavoro che serve davvero questa settimana.

Quando lavorano tra persone, i team usano spesso la conversazione per ridurre l’ambiguità. Una senior engineer chiede: “Quale pagina?” Un designer chiede: “Quale problema stiamo risolvendo?” Un product manager chiede: “Come capiremo che è migliorato?” Con un agente di AI coding, questo passaggio si salta facilmente perché l’agente è sempre pronto a iniziare.

Quella disponibilità crea debito di review. La pull request non viene più valutata rispetto a un risultato chiaro. Viene valutata rispetto alla memoria, al gusto e alle ipotesi del reviewer su cosa intendesse il prompt. Così un team finisce per dire che l’agente è “inaffidabile”, quando la diagnosi più precisa è che il task non era reviewable.

Il problema è vicino a quello discusso in Agenti AI: servono code operative, non solo prompt. Quando il lavoro agentico non è più un comando usa e getta, servono scope, ownership, stato e condizioni di stop. I criteri di accettazione sono la porta d’ingresso di questo sistema: rendono l’unità di lavoro abbastanza piccola da assegnare e abbastanza concreta da controllare.

Cosa deve contenere un contratto di task per l’agente?

Un contratto di task per l’agente non è una specifica pesante. È un brief breve che impedisce a un’intenzione vaga di diventare codice vago. Può stare in un ticket, in una issue, in un commento operativo o in una nota del repository.

Servono sei campi.

Obiettivo. Descrivi l’esito utente o business, non solo la richiesta tecnica. “Permettere ai membri invitati di accettare l’invito dopo il login con Google” è più forte di “fix invite login”.

Vincoli. Elenca i confini che l’agente deve rispettare. Possono includere regole architetturali, design system, requisiti di accessibilità, convenzioni di naming, compatibilità API, sicurezza, performance o “non modificare la logica di billing”. Qui product judgment e standard ingegneristici si incontrano.

File o aree coinvolte. Indica all’agente i file, le route, i componenti, i test, la documentazione o gli esempi probabilmente rilevanti. Non significa fingere di conoscere tutta l’implementazione. Significa ridurre lo spazio di ricerca e rendere visibili le assunzioni. Il materiale di OpenAI su Codex consiglia prompt simili a issue GitHub, con percorsi file, nomi di componenti, diff e snippet quando sono utili.

Criteri di accettazione. Definisci cosa deve essere vero quando il task è completo. I criteri buoni sono osservabili: lo stato vuoto appare solo quando il progetto non ha task, la CTA primaria apre la modale di creazione, la scorciatoia da tastiera esistente continua a funzionare, il test rilevante passa, il bug non si riproduce più seguendo gli step indicati.

Percorso di review. Chiarisci chi rivede cosa. Una persona product può rivedere comportamento e copy. Una persona engineering può rivedere coerenza tecnica, test e rischio. Un founder può approvare il tradeoff se la modifica impatta pricing o attivazione. Senza percorso di review, l’agente può creare lavoro che compila, ma resta sospeso socialmente.

Nota di rollback. Aggiungi il modo più rapido e sicuro per annullare la modifica. Può bastare “feature flag singola”, “revert della PR” o “migrazione additiva, nessun rollback necessario finché la nuova colonna non viene letta in produzione”. Il punto è pensare al raggio d’impatto prima del merge.

Un contratto compatto può essere così:

Obiettivo: ridurre la confusione dopo la creazione di un workspace vuoto.
Vincoli: usare il componente EmptyState esistente, nessuna nuova dipendenza, preservare i nomi degli eventi analytics.
Aree coinvolte: app/workspaces/[id]/page.tsx, components/empty-state, test onboarding.
Criteri di accettazione:
- Un workspace vuoto mostra titolo, breve spiegazione e CTA Crea primo progetto.
- La CTA apre la modale esistente di creazione progetto.
- Un workspace con progetti resta invariato.
- I test rilevanti passano o l’agente spiega perché non ha cambiato test.
Review: product rivede copy e comportamento, engineering rivede diff e test.
Rollback: revert della PR, nessuna modifica database.

Non è burocrazia. È la forma minima di un task verificabile.

Perché i criteri migliorano la review?

I criteri di accettazione cambiano la domanda da “Mi piace questa diff?” a “Questa diff soddisfa il contratto?”

Il cambio è importante perché il codice generato da AI può essere fluido e distraente. Può introdurre un helper elegante ma inutile. Può risolvere un problema vicino, non quello richiesto. Può allargare lo scope perché il prompt lasciava spazio all’interpretazione. Senza criteri, il reviewer deve controllare qualità del codice e intenzione prodotto nello stesso momento.

Con i criteri, la review diventa più ordinata.

Prima si controlla l’esito: il comportamento corrisponde all’obiettivo? Poi i confini: l’agente è rimasto dentro file, pattern e vincoli, oppure ha riscritto codice non correlato? Poi l’evidenza: ci sono test, lint, type check, screenshot, step di riproduzione o note manuali? Infine la reversibilità: se la modifica fallisce in produzione, il team sa come tornare indietro?

Per questo i criteri non devono essere solo tecnici. “I test passano” è spesso necessario, ma non basta. Il lavoro visibile agli utenti richiede criteri comportamentali. I tool interni richiedono criteri di workflow. Le modifiche di misurazione richiedono criteri su eventi e data contract. L’output dell’agente diventa più sicuro quando la definizione di fatto riflette il sistema reale, non solo il compilatore.

Lo stesso principio emerge in Un product operating model parte dai diritti decisionali. Un workflow non è sano perché tutti possono commentare. È sano quando le persone giuste sanno quali decisioni possiedono. La review dell’AI coding ha bisogno della stessa chiarezza.

Dove deve intervenire il product leader?

Un product leader non deve diventare la polizia dei prompt. Deve definire dove l’ambiguità costa cara.

Una regola utile: intervenire prima che l’agente parta quando il task tocca comportamento utente, logiche di revenue, raccolta dati o convenzioni cross-team. Sono aree in cui una diff tecnicamente valida può comunque essere una decisione prodotto sbagliata.

Per una piccola correzione visuale, il contratto può essere minuscolo. Per una modifica alla signup, dovrebbe includere stati attesi, edge case, eventi analytics e ownership della review. Per billing, permessi, autenticazione o migrazioni, dovrebbe includere vincoli espliciti e rollback prima di concedere accesso in scrittura all’agente.

Non è un argomento contro la velocità. È il modo in cui la velocità sopravvive alla review. I team che saltano il contratto sembrano veloci nella prima ora e poi perdono la giornata in rework. I team che definiscono il contratto lasciano l’agente correre dentro un perimetro più piccolo.

Il passo successivo è rendere riusabili i contratti ricorrenti. Le regole durevoli del repository possono vivere in un file per agenti, in una convenzione di team o in un template di task. Comandi di test, pattern di naming, regole architetturali e significato di “done” devono stare vicino al lavoro. Se l’agente fa lo stesso errore due volte, aggiorna la guida durevole invece di ripetere la correzione in ogni prompt.

Un artefatto piccolo, un’abitudine grande

Il contratto di task per l’agente è volutamente sobrio: obiettivo, vincoli, file coinvolti, criteri di accettazione, percorso di review, nota di rollback. Non promette AI coding perfetto. Rende il fallimento più facile da vedere, rivedere e correggere.

Questo è il vantaggio operativo. Il team smette di trattare l’AI coding come output magico e inizia a trattarlo come lavoro delegato. Il lavoro delegato ha bisogno di una definizione di fatto prima dell’esecuzione, non dopo l’arrivo della diff.

Se il tuo workflow di AI coding produce troppo rework, non partire cambiando modello, aggiungendo tool o scrivendo prompt più lunghi. Parti dal contratto del task. L’agente può aiutare in modo affidabile solo quando la persona ha reso il lavoro reviewable.