Prompt per agenti di coding: criteri di accettazione, non desideri

Quando chiedi qualcosa a un agente di coding, la differenza tra un risultato utile e uno da rifare sta quasi sempre nel modo in cui descrivi cosa significa «fatto». Un desiderio («rendi la pagina più bella») lascia all’agente il compito di indovinare. Un criterio di accettazione lo rende verificabile.

Desiderio contro criterio

• Desiderio: «Migliora le prestazioni della home.»
• Criterio: «Il punteggio Lighthouse di performance su mobile arriva a 95 o più, senza rimuovere contenuti, e la build continua a passare.»

Una struttura che funziona

• Contesto: cosa esiste già e dove (file, componenti).
• Obiettivo: il risultato che vuoi, in una frase.
• Vincoli: cosa non deve cambiare, cosa non aggiungere (dipendenze, pagine, file).
• Criteri di accettazione: tre o quattro controlli concreti che puoi verificare.
• Come verificare: build, test, screenshot, comandi da eseguire.

Un esempio

Aggiungi una sezione «Servizi» dopo «Lavori».

Contesto: i testi stanno in src/content.js, in italiano e inglese.
Vincoli: nessuna nuova dipendenza, stesso stile delle card esistenti.
Fatto quando:
- la sezione compare in italiano e in inglese;
- su mobile le card sono in una colonna, senza scroll orizzontale;
- la build passa;
- nessun commit finché non approvo.

Altri accorgimenti

• Per cambiamenti grandi chiedi prima un piano e approvalo: costa meno correggere un piano che un diff.
• Allega esempi o screenshot quando parli di aspetto: «come questa card, ma più compatta» vale più di tre aggettivi.
• Elenca anche cosa non vuoi: i divieti riducono le sorprese.
• Se l’agente sbaglia, correggi il prompt (o il file di istruzioni) e non solo il risultato.

Un buon criterio ha una proprietà semplice: puoi controllarlo senza fidarti di chi ti dice che è soddisfatto.