Comment écrire des critères d'acceptation qu'un agent d'IA peut vérifier
Les critères d'acceptation (AC, acceptance criteria) sont les conditions qui doivent être vraies pour qu'un changement compte comme terminé. Given/When/Then est la forme des étapes dans Gherkin, le langage que Cucumber utilise pour le développement piloté par le comportement (BDD, behaviour-driven development) : Given un état de départ, When une action se produit, Then un résultat observable suit. Un document d'exigences produit (PRD, product requirements document) est le texte qui nomme le problème et le produit visé. Le développement piloté par les spécifications (SDD, spec-driven development) traite une spécification structurée, et non cette prose seule, comme la source par rapport à laquelle l'implémentation est vérifiée. EARS (Easy Approach to Requirements Syntax) est une façon de contraindre une phrase d'exigence pour que ses clauses restent dans un ordre fixe. L'intégration continue (CI, continuous integration) est une vérification automatique de chaque changement proposé ; ce site décrit les deux vérifications SpecScore sur la page des validateurs. Cette page montre comment écrire des critères d'acceptation testables qu'un agent d'intelligence artificielle (IA, artificial intelligence) peut vérifier, avec des exemples de critères d'acceptation, et ce que l'interface en ligne de commande (CLI, command-line interface) de SpecScore vérifie réellement.
Mis à jour le 3 novembre 2026.
Ce que sont les critères d'acceptation
Un critère d'acceptation répond à « qu'est-ce qui doit être vrai ? ». Il nomme une condition qu'un relecteur, un test ou un agent peut accepter ou rejeter. Il ne nomme pas la fonction à appeler ni le fichier à modifier. Ces choix appartiennent à l'implémentation.
Une exigence est la règle. Dans la spécification des exigences de SpecScore, une exigence est un titre #### REQ: à l'intérieur d'une fonctionnalité : une obligation, avec son propre identifiant. Un critère d'acceptation regroupe des exigences liées en une condition. Un scénario est un cas concret qui montre que la condition tient. La spécification des critères d'acceptation le dit ainsi : les critères répondent à « qu'est-ce qui doit être vrai ? », et les scénarios répondent à « comment le prouvons-nous ? ».
Un PRD peut contenir la même intention en paragraphes. Les paragraphes aident une personne. Un agent doit encore deviner quelle phrase est le test de réussite ou d'échec. Écrire le critère comme un énoncé à part supprime cette devinette.
Ce qui rend les critères d'acceptation testables
Un agent de programmation par IA ne peut suivre un critère que lorsqu'un lecteur ultérieur peut désigner une preuve et dire réussi ou échoué. Cinq habitudes rendent cela possible. Aucune n'est un modèle de phrase. Ce sont des vérifications que l'on peut appliquer à n'importe quel modèle, y compris Given/When/Then et une liste de contrôle.
Observable
Le résultat est quelque chose qu'un tiers peut voir : un message sur la page, un enregistrement qui a été stocké ou qui ne l'a pas été, une redirection, un formulaire rejeté. « Le système comprend l'acheteur » n'est pas observable. « La page affiche Enter a valid email address à côté du champ e-mail » l'est.
Spécifique
Nommez l'acteur, l'entrée et le résultat. « Une mauvaise entrée est gérée » ne dit pas quelle entrée ni quel traitement. « L'acheteur envoie l'e-mail not-an-email » le dit. Spécifique ne signifie pas coller chaque valeur de production. Cela signifie qu'un lecteur peut inventer un jeu d'essai et savoir ce qui doit se passer.
Un comportement
Un critère, un comportement. « L'acheteur peut se connecter, réinitialiser un mot de passe et voir un message de verrouillage » fait trois critères dans une phrase. Un agent qui implémente le premier et saute le troisième peut encore prétendre que la phrase est faite. Séparez-les.
Réussite ou échec
Un critère d'acceptation testable a deux issues. « Le formulaire devrait sembler rapide » a une pente, pas un résultat. S'il vous faut une borne, écrivez-la : « la page de paiement affiche l'erreur sans autre requête vers le serveur ». Si vous ne pouvez pas dire à quoi ressemble l'échec, la phrase n'est pas encore un critère.
Sans mots vagues
Retirez les mots qui cachent le résultat : élégant, intuitif, robuste, convivial, fluide, rapide, devrait et approprié. Remplacez chacun par la preuve que vous accepteriez. « Gérer les erreurs avec élégance » devient « afficher Enter a valid email address à côté du champ, et ne pas passer la commande ».
Given/When/Then et une liste de contrôle
Deux formes couvrent la plupart des exemples de critères d'acceptation que les équipes conservent vraiment. Given/When/Then est un scénario. Une liste de contrôle est une liste de résultats. Utilisez le scénario lorsque l'ordre de l'état, de l'action et du résultat compte. Utilisez la liste lorsque vous énumérez des résultats indépendants d'une seule action.
La référence Gherkin de Cucumber donne aux étapes les mots-clés Given, When, Then, And et But. La référence est en anglais ; Gherkin a aussi des traductions de ces mots-clés. Le texte après le mot-clé est associé à du code, appelé step definition, lorsque Cucumber exécute le fichier. SpecScore n'utilise pas cette couche de step definition. L'exemple ci-dessous est du Gherkin, montré pour que la forme soit familière. Ce n'est pas un fichier 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
Liste de contrôle
- Submitting the email "not-an-email" shows "Enter a valid email address" beside the email field.
- The order is not placed.
Gardez un seul When. Une seconde action est un second scénario. And poursuit le même mot-clé : un autre Given, ou un autre Then. N'utilisez pas And pour glisser un second comportement.
Une liste de contrôle est le même contrat sans les mots-clés. Chaque ligne reste un résultat observable. La liste ci-dessus est le Then du scénario, écrit comme des vérifications.
Le guide d'Alistair Mavin définit EARS (Easy Approach to Requirements Syntax) comme un mécanisme pour contraindre en douceur les exigences textuelles. Les clauses restent dans un seul ordre. Le guide donne la forme générique : While <optional pre-condition>, when <optional trigger>, the <system name> shall <system response>. Une exigence a zéro précondition ou plus, zéro déclencheur ou un seul, un nom de système, et une réponse du système ou plus.
Cette phrase est l'obligation : la règle que le système doit respecter. Un critère d'acceptation est la condition qui doit être vraie pour que l'obligation compte comme respectée. Un scénario Given/When/Then est un cas concret de cette condition. Vous pouvez écrire l'exigence dans une phrase EARS et garder le critère libre de données d'exemple.
Dans une fonctionnalité SpecScore, l'exigence peut être une phrase de style EARS sous un titre #### REQ:. Le critère reste la condition abstraite. Le scénario porte l'exemple. EARS ne remplace ni l'un ni l'autre. Il ne contraint que la phrase de l'exigence.
Exemples de critères d'acceptation : vagues et testables
Nommez la preuve
Vague
The checkout form should handle bad input gracefully and feel fast.
Testable
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 ligne vague a deux exigences cachées (erreurs, vitesse) et aucune preuve. La ligne testable a une action et deux résultats qu'une personne ou un agent peut vérifier. Les exemples restent en anglais parce que les mots-clés du format sont en anglais.
Un comportement
Vague
Users can sign in, reset a password, and see an error if the account is locked.
Testable
When a visitor submits a known email and the matching password, the app sets a session cookie and redirects to /dashboard.
La connexion, la réinitialisation et le verrouillage sont trois comportements. La ligne testable garde la connexion. La réinitialisation et le verrouillage reçoivent chacun leur critère, avec leurs entrées et leurs résultats.
Le résultat, pas le nom de la fonction
Vague
The handler returns 400 from validateEmail().
Testable
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 nom de fonction et un code de statut attachent le critère au code d'aujourd'hui. Le résultat tient encore si la vérification passe à une autre fonction. Gardez les codes de statut lorsque le code de statut est le comportement promis, et dites-le comme résultat observable.
Comment SpecScore les enregistre, et ce que la CI vérifie
SpecScore publie le format dans le dépôt specscore/specscore et la CLI dans specscore/specscore-cli. Les deux documents ne décrivent pas les critères d'acceptation exactement sous la même forme. Les deux sont actuels. Cette section dit lequel est lequel, puis ce que specscore spec lint rejette réellement.
La spécification des critères d'acceptation — le README de fonctionnalité servi à cette URL — place les critères directement dans le README de la fonctionnalité. Chaque fonctionnalité a une section ## Acceptance Criteria. Chaque critère est un titre ### AC: {slug}. Le slug est en minuscules et séparé par des traits d'union. La ligne suivante est **Requirements:** et liste les exigences qu'il regroupe, sous la forme {feature-id}#req:{slug}. Ensuite vient la prose : la condition composite. La spécification dit que cette prose reste abstraite. Elle ne doit pas contenir d'étapes Given/When/Then, d'entrées d'exemple ni de détail d'implémentation. Lorsqu'aucun critère n'existe encore, la section dit «Not defined yet.» et la section Open Questions dit «Acceptance criteria not yet defined for this feature.». Les critères sont un regroupement facultatif : la spécification dit d'en ajouter un lorsqu'il regroupe deux exigences ou plus, et de l'omettre lorsqu'il ne ferait que répéter une seule exigence.
La preuve concrète est un fichier de scénario dans le répertoire _tests/ de la fonctionnalité. La spécification de scénario exige un titre # Scenario:, une section ## Steps, les mots GIVEN, WHEN, THEN et AND en majuscules, et exactement un WHEN. Une ligne facultative **Validates:** relie le scénario à {feature-path}#ac:{slug} ou à une exigence. Une section ## Rehearse peut contenir un script exécutable dans un bloc rehearse qui commence par un shebang.
La CLI lit aussi des fichiers de critère fins, un par critère, à _acs/<slug>.ac.md. L'exemple de connexion et le guide Rehearse documentent cette forme : # AC: <slug>, facultatifs **Status:**, **Verifies:** et **Applies-to:**, et la condition sous ## Statement. specscore rehearse acs <feature-dir> imprime un tableau récapitulatif à partir de ces fichiers. specscore rehearse acs --write remplace la section Acceptance Criteria du README de la fonctionnalité par ce tableau et un commentaire qui dit que la section est générée et ne doit pas être modifiée à la main. Un fichier sans titre # AC: est une erreur de cette commande.
La CI de ce dépôt est le workflow dogfood. Il installe la CLI v0.39.1 et exécute specscore spec lint sur les pull requests et sur les pushes vers main. Au contrôle du 3 novembre 2026, cette version et la branche par défaut de la CLI incluent toutes deux les règles ci-dessous. Le linter vérifie la structure. Il ne note pas l'anglais.
La règle ac-heading-format est une erreur. Dans un README de fonctionnalité (un fichier dont le titre est # Feature:), une ligne qui ressemble à un titre de critère d'acceptation doit être exactement ### AC: <id> avec un espace après le deux-points et un id en kebab-case. Un titre de la forme ### AC: <id> (verifies ...) est aussi accepté. --fix ne corrige que l'espacement. Un id avec des majuscules ou des tirets bas est signalé et laissé à une personne. La règle n'exige pas la ligne **Requirements:**, n'exige pas le marqueur «Not defined yet.» et n'avertit pas lorsque la prose contient Given, When ou Then. Le scénario propre à la spécification pour cet avertissement n'est pas une règle de lint dans cette CLI.
Sur un plan qui nomme une fonctionnalité source, le linter lit les titres ### AC: dans la section Acceptance Criteria de cette fonctionnalité. La règle P-002 signale une valeur **Verifies:** de tâche qui n'est pas <feature-slug>#ac:<ac-slug> pour l'un de ces titres. La règle P-001 signale un titre qu'aucune tâche ne couvre et qui n'est pas listé sous ## Deferred AC Coverage. Ces deux règles n'ouvrent pas _acs/*.ac.md. Un tableau récapitulatif issu de rehearse acs --write n'a pas de titres ### AC:, donc les règles de plan ne voient pas les fichiers fins.
La même commande de lint ne vérifie pas les mots-clés des étapes de scénario. specscore rehearse exécute les fichiers de scénario : le guide Rehearse utilise un titre tel que ## Given ou ## When au-dessus d'une commande dans un bloc, et **Use:** pour appeler une vérification réutilisable. Un fichier avec un Given et plusieurs branches When s'exécute comme des cas séparés. specscore rehearse new <feature-slug>#ac:<ac-slug> lit le README de la fonctionnalité et extrait les lignes Given/When/Then de ce critère vers spec/features/<feature-slug>/_tests/<ac-slug>.md. Rien de tout cela ne s'exécute dans le workflow dogfood. Le workflow exécute specscore spec lint.
Critère en ligne, d'après la spécification des critères d'acceptation
## 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.
Fichier de critère fin, la forme que lit 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.
Fichier de scénario, d'après la spécification de scénario
# 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
Scénario Rehearse, la forme du guide 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
```
Les quatre échantillons illustrent ces formes. Ils ne sont pas un arbre de fonctionnalité complet, et cette page ne prétend pas qu'ils passent specscore spec lint à eux seuls. Un README de fonctionnalité a aussi besoin de ses autres sections obligatoires avant que cette commande soit propre.
Si vous voulez une liste de questions pour tirer le critère d'une demande vague, utilisez Poser de bonnes questions. Le parcours de connexion montre un critère fin, session-hardened, à sa place parmi les autres artefacts.
Questions fréquentes
Que sont les critères d'acceptation ?
Les critères d'acceptation (AC) sont les conditions qui doivent être vraies pour qu'un changement compte comme terminé. Dans la spécification des critères d'acceptation de SpecScore, ils sont abstraits : ils disent ce qui doit être vrai, et ils laissent les étapes concrètes à un scénario.
Qu'est-ce que Given/When/Then ?
Given/When/Then est la forme des étapes dans Gherkin : Given un état de départ, When une action se produit, Then un résultat observable suit. Cucumber documente les mots-clés dans la référence Gherkin. La spécification de scénario de SpecScore utilise les mots-clés en majuscules GIVEN, WHEN, THEN et AND, avec exactement un WHEN par fichier de scénario.
Comment écrire des critères d'acceptation pour un agent de programmation par IA ?
Écrivez un seul comportement observable, avec l'acteur, l'entrée et le résultat, et sans mots vagues. Placez les données d'exemple dans un scénario, pas dans le critère abstrait. L'agent peut alors implémenter par rapport au critère et vérifier le scénario.
Les critères d'acceptation sont-ils la même chose que les cas de test ?
Non. Un critère énonce la condition. Un cas de test, ou un scénario SpecScore, est une exécution avec des entrées concrètes qui montre que la condition tient ou échoue. Plusieurs scénarios peuvent soutenir un critère.
specscore spec lint juge-t-il les formulations vagues ?
Non. Dans la CLI v0.39.1, la version qu'installe la CI de ce dépôt, ac-heading-format vérifie le titre ### AC:. Il ne note pas des mots comme «graceful» ou «fast», et il n'avertit pas lorsqu'un critère contient Given/When/Then. La formulation est un travail d'écriture. La page des validateurs sépare ce lint déterministe de la revue manuelle par IA.
Où vont les étapes Given/When/Then dans SpecScore ?
Dans un scénario, pas dans le critère d'acceptation. La spécification des critères d'acceptation interdit les étapes Given/When/Then à l'intérieur du critère. La spécification de scénario les place dans _tests/, sous ## Steps. Rehearse exécute une forme apparentée : des titres et des commandes dans des blocs sous _tests/, documentée dans le guide Rehearse. Le linter n'impose pas les mots-clés des étapes.
Sources
Lu le 3 novembre 2026. Les pages tierces ne sont citées que pour les définitions qu'elles publient.