Criteri di successo: come si capisce che è fatto

“È fatto” non è una sensazione. È una verifica. Senza criteri osservabili, ogni revisione di codice generato dipende dall’umore: oggi mi sembra ok, domani penso che manchi qualcosa. Con criteri scritti prima, “fatto” è binario: sì o no, indipendentemente da chi guarda.

Perché questa lezione conta

Senza Definition of Done (DoD), task non finiscono mai (sempre c’è qualcosa che potrebbe essere migliorato) o finiscono troppo presto (la demo funziona, gli edge case no). Con DoD esplicita, il modello AI sa quando fermarsi, tu sai quando accettare, e la revisione diventa una checklist invece di un’opinione.

Obiettivo operativo

Alla fine devi saper:

1. distinguere criteri funzionali da non funzionali da DoD operativa;
2. scrivere criteri in forma osservabile (input → output, comportamento → verifica);
3. usare i criteri come filtro di accettazione del codice generato.

Nucleo della lezione

1. Tre livelli di criteri

Funzionali: cosa il sistema deve fare. Risposte alla domanda “quando l’utente fa X, cosa succede?”.

Esempi:

• “Quando l’utente clicca ‘Salva’ su una nota vuota, mostra messaggio ‘La nota è vuota’ e non salva.”
• “Endpoint GET /orders?status=pending restituisce massimo 50 ordini per pagina, ordinati per data desc.”
• “Login fallisce dopo 5 tentativi consecutivi entro 10 minuti dallo stesso IP.”

Non funzionali: come il sistema deve farlo. Performance, accessibilità, sicurezza, compatibilità.

Esempi:

• “Pagina caricata < 2s su connessione 3G simulata.”
• “Tutte le interazioni accessibili da tastiera, focus visibile.”
• “Nessuna chiave API esposta nel bundle client.”
• “Funziona su Safari ≥17, Chrome ≥120, Firefox ≥120.”

DoD operativa: cosa deve essere vero perché il task sia chiuso, oltre al fatto che il codice “funziona”.

Esempi:

• “Test automatici passano in CI.”
• “Demo manuale eseguita su mobile.”
• “README aggiornato con istruzioni nuove.”
• “Nessun warning in console.”
• “Migrations applicate e rollback testato.”

I tre livelli si sommano: feature finita = criteri funzionali OK + non funzionali OK + DoD OK.

2. Forma osservabile

Un criterio è utile solo se osservabile. “L’app deve essere veloce” non lo è. “Time-to-first-byte < 500ms” sì. Tre regole:

• Soggetto-azione-risultato concreti: chi fa cosa, cosa accade.
• Numeri quando possibile: tempo, dimensione, percentuale, quantità.
• Verifica esplicita: quale comando/azione dimostra che il criterio è soddisfatto.

Confronto:

❌ “L’errore deve essere chiaro.” ✅ “Quando il salvataggio fallisce per timeout, l’utente vede messaggio ‘Connessione lenta. Riprova fra qualche secondo’ con bottone ‘Riprova’. Verificabile tramite test automatico che simula fetch timeout.”

Il secondo è codificabile, testabile e accettabile/rifiutabile. Il primo è opinione.

3. Criteri come filtro di accettazione

Nel ciclo di vibe coding, i criteri vanno scritti prima di generare. Servono in tre punti:

• Nel prompt: l’AI sa cosa deve essere vero alla fine. Riduce spostamento di scope.
• Nel diff: rileggi i criteri prima di accettare. Per ognuno, verificabile nel codice/comportamento? sì → accetta, no → rifiuta.
• In CI/test: criteri funzionali → test automatici. Criteri non funzionali → linter, type check, audit Lighthouse. DoD → checklist manuale o script.

Senza criteri scritti prima, accetterai diff che “sembrano giusti” e ti accorgerai dei problemi solo quando un utente li scopre.

Procedura pratica

Per ogni feature significativa:

1. Scrivi 3-5 criteri funzionali (“quando X succede Y, in caso di errore Z”).
2. Scrivi 2-3 criteri non funzionali (performance, accessibilità, sicurezza minima, compatibilità).
3. Scrivi DoD operativa (5-7 voci: test, demo, doc, no warning, ecc).
4. Inserisci nel prompt come sezione “criteri di accettazione”.
5. Verifica al diff: per ogni criterio, traccia dove è soddisfatto.
6. Esegui DoD: prima di considerare il task chiuso, spunta voce per voce.

Laboratorio guidato

Feature: form di contatto su sito personale (nome, email, messaggio, invio email a te).

Scrivi criteri completi:

Funzionali (almeno 4):

• Quando un campo richiesto è vuoto, l’invio è impedito e il campo è evidenziato in rosso.
• Quando email non valida (no @, spazi, caratteri illegali), errore “Email non valida” sotto il campo.
• All’invio riuscito, messaggio “Messaggio inviato. Ti risponderò entro 48h.” e form svuotato.
• All’invio fallito (rete o server), messaggio “Errore invio. Riprova fra qualche minuto.” con bottone “Riprova”.
• Il form non si invia più di 3 volte da stesso IP nei 10 minuti (anti-spam basico).

Non funzionali (almeno 3):

• Caricamento iniziale < 1s su 3G simulato.
• Form usabile da tastiera (Tab, Shift+Tab, Enter), focus visibile.
• Email ricevuta da te entro 30 secondi dall’invio.
• Nessun secret nel bundle client.

DoD:

• Test E2E che invia form e verifica ricezione email (smoke test).
• Test unitario validazione email.
• Manual test con form vuoto, email invalida, invio multiplo.
• Lighthouse score Performance ≥ 90.
• README aggiornato con env vars necessarie.
• Build pulita, no warning.

Output atteso

Una scheda criteri compilata per la prossima feature reale che vuoi sviluppare. Tre sezioni: funzionali, non funzionali, DoD. Ogni voce osservabile e verificabile.

Studio passo passo

Studia questa lezione in tre passaggi, senza correre subito al prompt o al codice.

1. Prima lettura: chiarisci l’obiettivo: definire risultati osservabili prima di generare codice, così la revisione non dipende da impressioni. Se non riesci a riscriverlo in una frase tua, rileggi il nucleo della lezione.
2. Seconda lettura: trasforma i contenuti in domande operative:

• Criteri funzionali: cosa deve accadere, con quali input, in quali stati e con quali messaggi.
• Criteri non funzionali: velocità percepita, accessibilità, sicurezza minima, leggibilità, manutenibilità.
• Definizione di done: demo, test manuali, test automatici, assenza di errori in console, comportamento mobile.

3. Applicazione: svolgi il laboratorio: scrivere criteri di accettazione per una feature piccola usando esempi concreti e casi limite. L’output da ottenere è: una mini Definition of Done da allegare a ogni richiesta di generazione o modifica.

Prima di passare alla lezione successiva, controlla di avere un artefatto concreto: una tabella, un prompt, una checklist, un mini report, un diff commentato o una decisione scritta. Nel vibe coding la comprensione resta astratta finché non produce una traccia verificabile.

Checklist di verifica

• ho scritto criteri prima di generare codice, non dopo;
• ogni criterio è osservabile, non opinione;
• ho almeno una verifica automatica (test/lint) per i criteri funzionali principali;
• la DoD è una lista che posso davvero spuntare voce per voce.

Errori comuni

Criteri vaghi. “Funziona bene”, “ha buona UX”, “veloce”. Inutili.

Niente criteri non funzionali. Solo funzionali → app che fa la demo ma è inaccessibile, lenta, insicura.

DoD assente. Senza, accetti codice che “fa la cosa” ma non è pronto (no test, no doc, warning non risolti).

Criteri scritti dopo il diff. A quel punto giustifichi il codice esistente invece di valutarlo. Sempre prima.

Troppi criteri all’inizio. 30 criteri per una feature piccola = analysis paralysis. Inizia con 5-8 criteri totali, aggiungi solo se servono.

Prompt di lavoro

Sto progettando criteri di accettazione per questa feature:

Feature: [descrizione 2 righe]
Persona: [chi la usa]
Vincoli rigidi: [da scheda vincoli]

Aiutami a costruire criteri completi in tre sezioni:

1. Funzionali (4-6, formato "quando X, allora Y, in caso di errore Z"):
   - cosa accade nel caso normale
   - cosa accade in caso di errore (almeno 2)
   - cosa NON deve accadere (almeno 1)

2. Non funzionali (3-4, con numeri):
   - performance: [es. tempo di risposta < ...]
   - accessibilità: [WCAG AA: contrasto, tastiera, screen reader]
   - sicurezza: [es. validazione server, segreti non esposti]
   - compatibilità: [browser/dispositivi minimi]

3. DoD operativa (5-7 voci spuntabili):
   - test automatici
   - demo manuale
   - documentazione
   - osservabilità (log, monitor)
   - revisione

Verifica che ogni criterio sia osservabile (esiste un comando/azione che dimostra sì/no).

Non scrivere ancora codice. Concludi indicando quali criteri sono ambigui e meritano di essere chiariti.

Esercizio finale

Riguarda un task che hai chiuso recentemente con AI. Aveva criteri scritti prima? Se sì, sono stati tutti soddisfatti? Se no, scrivili ora a posteriori e verifica voce per voce. Probabilmente scopri 1-2 criteri non rispettati che non avevi notato. Quel “non avevo notato” è la differenza fra task chiuso e task finito.