Come scrivere criteri di accettazione che un agente IA possa verificare
I criteri di accettazione (AC, acceptance criteria) sono le condizioni che devono essere vere perché un cambiamento conti come completato. Given/When/Then è la forma dei passi in Gherkin, il linguaggio che Cucumber usa per lo sviluppo guidato dal comportamento (BDD, behaviour-driven development): Given uno stato di partenza, When avviene un'azione, Then segue un risultato osservabile. Un documento dei requisiti di prodotto (PRD, product requirements document) è il testo che nomina il problema e il prodotto previsto. Lo sviluppo guidato dalle specifiche (SDD, spec-driven development) tratta una specifica strutturata, non solo quella prosa, come la fonte rispetto alla quale si controlla l'implementazione. EARS (Easy Approach to Requirements Syntax) è un modo per vincolare una frase di requisito così che le sue clausole restino in un ordine fisso. L'integrazione continua (CI, continuous integration) è un controllo automatico su ogni cambiamento proposto; questo sito descrive i due controlli SpecScore nella pagina dei validatori. Questa pagina mostra come scrivere criteri di accettazione testabili che un agente di intelligenza artificiale (IA, artificial intelligence) possa verificare, con esempi di criteri di accettazione, e che cosa controlla davvero l'interfaccia a riga di comando (CLI, command-line interface) di SpecScore.
Aggiornato il 3 novembre 2026.
Che cosa sono i criteri di accettazione
Un criterio di accettazione risponde a «che cosa deve essere vero?». Nomina una condizione che un revisore, un test o un agente può accettare o rifiutare. Non nomina la funzione da chiamare né il file da modificare. Quelle scelte appartengono all'implementazione.
Un requisito è la regola. Nella specifica dei requisiti di SpecScore, un requisito è un titolo #### REQ: dentro una funzionalità: un obbligo, con il proprio identificatore. Un criterio di accettazione riunisce requisiti collegati in una condizione. Uno scenario è un caso concreto che mostra che la condizione vale. La specifica dei criteri di accettazione lo dice così: i criteri rispondono a «che cosa deve essere vero?», e gli scenari rispondono a «come lo dimostriamo?».
Un PRD può contenere la stessa intenzione in paragrafi. I paragrafi aiutano una persona. Un agente deve ancora indovinare quale frase è il test di superamento o di fallimento. Scrivere il criterio come enunciato a sé toglie quell'indovinello.
Che cosa rende testabili i criteri di accettazione
Un agente di programmazione con IA può seguire un criterio solo quando un lettore successivo può indicare una prova e dire superato o fallito. Cinque abitudini lo rendono possibile. Nessuna è un modello di frase. Sono controlli che puoi applicare a qualunque modello, compreso Given/When/Then e un elenco di controllo.
Osservabile
Il risultato è qualcosa che una persona esterna può vedere: un messaggio sulla pagina, un record che è stato salvato oppure no, un reindirizzamento, un modulo rifiutato. «Il sistema capisce l'acquirente» non è osservabile. «La pagina mostra Enter a valid email address accanto al campo e-mail» lo è.
Specifico
Nomina l'attore, l'input e il risultato. «L'input errato viene gestito» non dice quale input né quale gestione. «L'acquirente invia l'e-mail not-an-email» sì. Specifico non significa incollare ogni valore di produzione. Significa che un lettore può inventare un dato di prova e sapere che cosa deve succedere.
Un comportamento
Un criterio, un comportamento. «L'acquirente può accedere, reimpostare una password e vedere un messaggio di blocco» sono tre criteri in una frase. Un agente che implementa il primo e salta il terzo può comunque sostenere che la frase è fatta. Separali.
Superato o fallito
Un criterio di accettazione testabile ha due esiti. «Il modulo dovrebbe sembrare veloce» ha una pendenza, non un risultato. Se ti serve un limite, scrivilo: «la pagina di pagamento mostra l'errore senza un'ulteriore richiesta al server». Se non puoi dire che aspetto ha il fallimento, la frase non è ancora un criterio.
Senza parole vaghe
Togli le parole che nascondono il risultato: elegante, intuitivo, robusto, facile da usare, fluido, veloce, dovrebbe e appropriato. Sostituisci ciascuna con la prova che accetteresti. «Gestire gli errori con eleganza» diventa «mostrare Enter a valid email address accanto al campo, e non effettuare l'ordine».
Given/When/Then e un elenco di controllo
Due forme coprono la maggior parte degli esempi di criteri di accettazione che i team conservano davvero. Given/When/Then è uno scenario. Un elenco di controllo è un elenco di risultati. Usa lo scenario quando conta l'ordine di stato, azione e risultato. Usa l'elenco quando elenchi risultati indipendenti di una sola azione.
Il riferimento Gherkin di Cucumber assegna ai passi le parole chiave Given, When, Then, And e But. Il riferimento usa l'inglese; Gherkin ha anche traduzioni di quelle parole. Il testo dopo la parola chiave viene abbinato a codice, chiamato step definition, quando Cucumber esegue il file. SpecScore non usa quello strato di step definition. L'esempio sotto è Gherkin, mostrato perché la forma sia familiare. Non è un file SpecScore.
Given/When/Then
Scenario: Reject an email that is not a valid address
Given the shopper is on the checkout form
When the shopper submits the email "not-an-email"
Then the page shows "Enter a valid email address" beside the email field
And the order is not placed
Elenco di controllo
- Submitting the email "not-an-email" shows "Enter a valid email address" beside the email field.
- The order is not placed.
Tieni un solo When. Una seconda azione è un secondo scenario. And continua la stessa parola chiave: un altro Given, oppure un altro Then. Non usare And per infilare un secondo comportamento.
Un elenco di controllo è lo stesso contratto senza le parole chiave. Ogni riga resta un risultato osservabile. L'elenco sopra è il Then dello scenario, scritto come controlli.
La guida di Alistair Mavin definisce EARS (Easy Approach to Requirements Syntax) come un meccanismo per vincolare dolcemente i requisiti testuali. Le clausole restano in un solo ordine. La guida dà la forma generica: While <optional pre-condition>, when <optional trigger>, the <system name> shall <system response>. Un requisito ha zero o più precondizioni, zero o un trigger, un nome di sistema e una o più risposte del sistema.
Quella frase è l'obbligo: la regola che il sistema deve soddisfare. Un criterio di accettazione è la condizione che deve essere vera perché l'obbligo conti come soddisfatto. Uno scenario Given/When/Then è un caso concreto di quella condizione. Puoi scrivere il requisito in una frase EARS e tenere comunque il criterio libero da input di esempio.
In una funzionalità SpecScore, il requisito può essere una frase in stile EARS sotto un titolo #### REQ:. Il criterio resta la condizione astratta. Lo scenario porta l'esempio. EARS non sostituisce né l'uno né l'altro. Vincola solo la frase del requisito.
Esempi di criteri di accettazione: vaghi e testabili
Nomina la prova
Vago
The checkout form should handle bad input gracefully and feel fast.
Testabile
When the shopper submits the email "not-an-email", the checkout page shows "Enter a valid email address" beside that field and does not place the order.
La riga vaga ha due richieste nascoste (errori, velocità) e nessuna prova. La riga testabile ha un'azione e due risultati che una persona o un agente può controllare. Gli esempi restano in inglese perché le parole chiave del formato sono in inglese.
Un comportamento
Vago
Users can sign in, reset a password, and see an error if the account is locked.
Testabile
When a visitor submits a known email and the matching password, the app sets a session cookie and redirects to /dashboard.
Accesso, reimpostazione e blocco sono tre comportamenti. La riga testabile tiene l'accesso. Reimpostazione e blocco ricevono ciascuno il proprio criterio, con i propri input e risultati.
Il risultato, non il nome della funzione
Vago
The handler returns 400 from validateEmail().
Testabile
When the shopper submits an email that is not a valid address, the checkout page shows "Enter a valid email address" and does not place the order.
Un nome di funzione e un codice di stato legano il criterio al codice di oggi. Il risultato resta valido se il controllo si sposta in un'altra funzione. Conserva i codici di stato quando il codice di stato è il comportamento che hai promesso, e dillo come risultato osservabile.
Come SpecScore li conserva, e che cosa controlla la CI
SpecScore pubblica il formato nel repository specscore/specscore e la CLI in specscore/specscore-cli. I due documenti non descrivono i criteri di accettazione esattamente nella stessa forma. Entrambi sono attuali. Questa sezione dice qual è quale, e poi che cosa specscore spec lint rifiuta davvero.
La specifica dei criteri di accettazione — il README di funzionalità servito a quell'URL — mette i criteri direttamente nel README della funzionalità. Ogni funzionalità ha una sezione ## Acceptance Criteria. Ogni criterio è un titolo ### AC: {slug}. Lo slug è in minuscolo e con trattini. La riga successiva è **Requirements:** ed elenca i requisiti che raggruppa, nella forma {feature-id}#req:{slug}. Poi viene la prosa: la condizione composta. La specifica dice che quella prosa resta astratta. Non deve contenere passi Given/When/Then, input di esempio né dettaglio di implementazione. Quando non esistono ancora criteri, la sezione dice «Not defined yet.» e la sezione Open Questions dice «Acceptance criteria not yet defined for this feature.». I criteri sono un raggruppamento facoltativo: la specifica dice di aggiungerne uno quando raggruppa due o più requisiti, e di ometterlo quando si limiterebbe a ripetere un solo requisito.
La prova concreta è un file di scenario nella directory _tests/ della funzionalità. La specifica di scenario richiede un titolo # Scenario:, una sezione ## Steps, le parole GIVEN, WHEN, THEN e AND in maiuscolo, ed esattamente un WHEN. Una riga facoltativa **Validates:** collega lo scenario a {feature-path}#ac:{slug} o a un requisito. Una sezione ## Rehearse può contenere uno script eseguibile in un blocco rehearse che inizia con uno shebang.
La CLI legge anche file di criterio sottili, uno per criterio, in _acs/<slug>.ac.md. L'esempio di accesso e la guida di Rehearse documentano questa forma: # AC: <slug>, facoltativi **Status:**, **Verifies:** e **Applies-to:**, e la condizione sotto ## Statement. specscore rehearse acs <feature-dir> stampa una tabella riassuntiva a partire da quei file. specscore rehearse acs --write sostituisce la sezione Acceptance Criteria del README della funzionalità con quella tabella e un commento che dice che la sezione è generata e non va modificata a mano. Un file senza titolo # AC: è un errore di quel comando.
La CI di questo repository è il workflow dogfood. Installa la CLI v0.39.1 ed esegue specscore spec lint sulle pull request e sui push verso main. Al controllo del 3 novembre 2026, quella versione e il branch predefinito della CLI includono entrambi le regole sotto. Il linter controlla la struttura. Non valuta l'inglese.
La regola ac-heading-format è un errore. In un README di funzionalità (un file il cui titolo è # Feature:), una riga che sembra un titolo di criterio di accettazione deve essere esattamente ### AC: <id> con uno spazio dopo i due punti e un id in kebab-case. È accettato anche un titolo della forma ### AC: <id> (verifies ...). --fix corregge solo la spaziatura. Un id con lettere maiuscole o trattini bassi viene segnalato e lasciato a una persona. La regola non richiede la riga **Requirements:**, non richiede il segnaposto «Not defined yet.» e non avvisa quando la prosa contiene Given, When o Then. Lo scenario della specifica per quell'avviso non è una regola di lint in questa CLI.
In un piano che nomina una funzionalità di origine, il linter legge i titoli ### AC: nella sezione Acceptance Criteria di quella funzionalità. La regola P-002 segnala un valore **Verifies:** di attività che non è <feature-slug>#ac:<ac-slug> per uno di quei titoli. La regola P-001 segnala un titolo che nessuna attività copre e che non è elencato sotto ## Deferred AC Coverage. Quelle due regole non aprono _acs/*.ac.md. Una tabella riassuntiva da rehearse acs --write non ha titoli ### AC:, quindi le regole del piano non vedono i file sottili.
Lo stesso comando di lint non controlla le parole chiave dei passi dello scenario. specscore rehearse esegue i file di scenario: la guida di Rehearse usa un titolo come ## Given o ## When sopra un comando in un blocco, e **Use:** per chiamare un controllo riutilizzabile. Un file con un Given e diversi rami When viene eseguito come casi separati. specscore rehearse new <feature-slug>#ac:<ac-slug> legge il README della funzionalità ed estrae le righe Given/When/Then di quel criterio in spec/features/<feature-slug>/_tests/<ac-slug>.md. Niente di tutto questo gira nel workflow dogfood. Il workflow esegue specscore spec lint.
Criterio in linea, dalla specifica dei criteri di accettazione
## Acceptance Criteria
### AC: invalid-email-rejected
**Requirements:** checkout#req:reject-invalid-email
An email that is not a valid address is rejected, and the order is not placed.
File di criterio sottile, la forma che legge rehearse acs
# AC: invalid-email-rejected
**Status:** accepted
**Verifies:** checkout#req:reject-invalid-email
## Statement
An email that is not a valid address is rejected, and the order is not placed.
File di scenario, dalla specifica di scenario
# Scenario: Reject an invalid email
**Validates:** [checkout#ac:invalid-email-rejected](../README.md#ac-invalid-email-rejected)
## Steps
GIVEN the shopper is on the checkout form
WHEN the shopper submits the email "not-an-email"
THEN the page shows "Enter a valid email address" beside the email field
AND the order is not placed
Scenario Rehearse, la forma della guida di Rehearse
# Rehearse: Reject an invalid email
## Given a submitted email that is not a valid address
```bash
printf 'email=not-an-email\n' > form.txt
```
## When the response is recorded
```bash
printf 'Enter a valid email address\n' > out.txt
```
## Then the message is the invalid-email text
```bash
grep -q 'Enter a valid email address' out.txt
```
I quattro campioni illustrano quelle forme. Non sono un albero di funzionalità completo, e questa pagina non afferma che superino specscore spec lint da soli. Un README di funzionalità ha bisogno anche delle altre sezioni obbligatorie prima che quel comando sia pulito.
Se vuoi un elenco di domande per ricavare il criterio da una richiesta vaga, usa Fare buone domande. Il percorso di accesso mostra un criterio sottile, session-hardened, al suo posto tra gli altri artefatti.
Domande frequenti
Che cosa sono i criteri di accettazione?
I criteri di accettazione (AC) sono le condizioni che devono essere vere perché un cambiamento conti come completato. Nella specifica dei criteri di accettazione di SpecScore sono astratti: dicono che cosa deve essere vero, e lasciano i passi concreti a uno scenario.
Che cos'è Given/When/Then?
Given/When/Then è la forma dei passi in Gherkin: Given uno stato di partenza, When avviene un'azione, Then segue un risultato osservabile. Cucumber documenta le parole chiave nel riferimento Gherkin. La specifica di scenario di SpecScore usa le parole chiave maiuscole GIVEN, WHEN, THEN e AND, con esattamente un WHEN per file di scenario.
Come scrivo i criteri di accettazione per un agente di programmazione con IA?
Scrivi un solo comportamento osservabile, con l'attore, l'input e il risultato, e senza parole vaghe. Metti i dati di esempio in uno scenario, non nel criterio astratto. L'agente può quindi implementare rispetto al criterio e controllare lo scenario.
I criteri di accettazione sono la stessa cosa dei casi di test?
No. Un criterio enuncia la condizione. Un caso di test, o uno scenario SpecScore, è un'esecuzione con input concreti che mostra la condizione valida o fallita. Diversi scenari possono sostenere un criterio.
specscore spec lint giudica le formulazioni vaghe?
No. Nella CLI v0.39.1, la versione che la CI di questo repository installa, ac-heading-format controlla il titolo ### AC:. Non valuta parole come «graceful» o «fast», e non avvisa quando un criterio contiene Given/When/Then. La formulazione è un lavoro di scrittura. La pagina dei validatori separa quel lint deterministico dalla revisione manuale con IA.
Dove vanno i passi Given/When/Then in SpecScore?
In uno scenario, non nel criterio di accettazione. La specifica dei criteri di accettazione vieta i passi Given/When/Then dentro il criterio. La specifica di scenario li mette in _tests/, sotto ## Steps. Rehearse esegue una forma affine: titoli e comandi in blocchi sotto _tests/, documentata nella guida di Rehearse. Il linter non impone le parole chiave dei passi.
Fonti
Letto il 3 novembre 2026. Le pagine di terzi sono citate solo per le definizioni che pubblicano.