Come dare al tuo agente di coding IA una chiara 'definizione di fatto'

Quando un collega umano prende in carico un ticket vago, colma le lacune con il proprio giudizio e fa domande. Un agente di coding IA non fa né l'una né l'altra cosa. Legge la tua richiesta, scrive il codice, esegue i controlli che può, e dichiara la funzionalità terminata — spesso senza una sola domanda di chiarimento. Come dice una guida, quando affidi requisiti vaghi a un agente, "lo spazio di manovra non viene assorbito — viene costruito."

Questo rende la tua definizione di fatto la singola cosa a maggior effetto leva che puoi scrivere. Questa guida spiega come scriverne una su cui un agente possa effettivamente agire.

Criteri di accettazione vs. definizione di fatto

Due idee correlate, che vale la pena tenere distinte:

• I criteri di accettazione sono specifici della funzionalità: cosa deve fare questo particolare lavoro per essere considerato corretto.
• La definizione di fatto è valida per l'intero progetto: i controlli di qualità che ogni modifica deve superare prima di essere rilasciata — test, revisione, documentazione, nessun segreto committato.

Pensa ai criteri di accettazione come al "abbiamo costruito la cosa giusta" e alla definizione di fatto come al "l'abbiamo costruita secondo il nostro standard." Il tuo agente ha bisogno di entrambe. (Atlassian offre una buona introduzione alla distinzione.)

Rendila verificabile, non aspirazionale

Il test per un buon criterio: uno script — o l'agente stesso — potrebbe verificare se è vero? "Il modulo di login dovrebbe risultare veloce" non è verificabile. Riscrivilo come qualcosa che ha un contorno netto:

• L'invio di credenziali valide reindirizza a /dashboard entro 500ms
• L'invio di una password errata mostra un errore inline e non naviga altrove
• L'invio di un campo vuoto viene bloccato lato client prima di qualsiasi richiesta di rete
• I login falliti sono limitati a 5 tentativi al minuto per IP

Ogni riga è qualcosa che l'agente può costruire e confermare. Il consiglio di Addy Osmani su come scrivere una buona specifica per gli agenti IA è di concentrarsi su cosa e perché, non sul come riga per riga — descrivi l'intento e i vincoli, e lascia che sia l'agente a scegliere l'implementazione.

Un esempio concreto

Confronta questi due prompt per lo stesso compito.

Vago:

Aggiungi un modo per gli utenti di reimpostare la password.

Con una definizione di fatto:

Aggiungi un flusso di reset della password. "Fatto" significa:

• Un endpoint POST /auth/reset-request accetta un'email e restituisce sempre 200 (non rivelare mai se l'email esiste)
• Un token firmato, monouso e valido per 1 ora viene inviato via email tramite il mailer esistente in src/lib/mail.ts
• POST /auth/reset-confirm valida il token, applica la policy corrente sulle password e invalida il token dopo l'uso
• I test coprono: reset valido, token scaduto, token riutilizzato, email sconosciuta
• Nessuna nuova dipendenza senza segnalarla prima

La seconda versione non è più lunga perché è burocratica — è più lunga perché ogni ambiguità che l'agente altrimenti avrebbe indovinato è ora decisa. Le scelte sensibili dal punto di vista della sicurezza (non far trapelare l'esistenza dell'account, far scadere i token, uso monouso) sono proprio quelle su cui meno vuoi che un agente improvvisi.

Integra il 'fatto' nel ciclo dell'agente

La vera forza di una definizione di fatto verificabile è che chiude il ciclo di feedback dell'agente. Un ciclo agentico di scrivi codice → testa → correggi → ripeti converge solo se c'è un obiettivo chiaro da centrare. Quando i tuoi criteri corrispondono a test reali, l'agente può eseguirli, vedere i fallimenti e correggere il proprio lavoro prima di restituirtelo.

Quindi non limitarti a descrivere il "fatto" — dai all'agente un modo per verificarlo:

• Indicagli il comando di test (npm test, pytest) e digli che la funzionalità non è finita finché non passano.
• Per le cose difficili da verificare con il codice — leggibilità, aderenza a un pattern esistente — usa una passata con un LLM come giudice (LLM-as-a-judge): un secondo prompt che valuta l'output rispetto al tuo standard di qualità. Anthropic e altri hanno riscontrato che questo approccio è efficace per i controlli soggettivi.
• Mantieni la sicurezza e il "niente codice segnaposto/mock" nella tua definizione di fatto valida per l'intero progetto, così da applicarli a ogni modifica, non solo a quelle che ti ricordi di menzionare.

Mettila dove l'agente la vedrà

Scrivi una volta la tua definizione di fatto valida per l'intero progetto, in un file che l'agente legge automaticamente — un AGENTS.md o un CLAUDE.md nella radice del repository. I criteri di accettazione specifici della funzionalità vanno nel prompt del task stesso. In questo modo "il nostro standard" è sempre nel contesto, e devi esplicitare solo ciò che è unico del lavoro di oggi.

Il cambiamento è sottile ma è tutto il gioco: con un agente capace, i tuoi criteri di accettazione smettono di essere una nota per un collega e diventano la specifica su cui il codice viene costruito. Scrivili di conseguenza.