Jak pisać kryteria akceptacji, które agent AI może zweryfikować

Czym są kryteria akceptacji

Kryterium akceptacji odpowiada na pytanie „co musi być prawdą?”. Nazywa warunek, który recenzent, test albo agent może przyjąć albo odrzucić. Nie nazywa funkcji do wywołania ani pliku do edycji. Te wybory należą do implementacji.

Wymaganie jest regułą. W specyfikacji wymagań SpecScore wymaganie to nagłówek #### REQ: wewnątrz funkcjonalności: jedno zobowiązanie, z własnym identyfikatorem. Kryterium akceptacji grupuje powiązane wymagania w jeden warunek. Scenariusz to jeden konkretny przypadek, który pokazuje, że warunek zachodzi. Specyfikacja kryteriów akceptacji ujmuje to tak: kryteria odpowiadają „co musi być prawdą?”, a scenariusze odpowiadają „jak to udowodnić?”.

PRD może zawierać tę samą intencję w akapitach. Akapity pomagają człowiekowi. Agent nadal musi zgadywać, które zdanie jest testem zaliczenia albo niezaliczenia. Zapisanie kryterium jako osobnego stwierdzenia usuwa to zgadywanie.

Co sprawia, że kryteria akceptacji są sprawdzalne

Agent kodujący z AI może podążać za kryterium tylko wtedy, gdy późniejszy czytelnik potrafi wskazać dowód i powiedzieć: zaliczone albo niezaliczone. Pięć nawyków to umożliwia. Żaden z nich nie jest szablonem zdania. Są to sprawdzenia, które można zastosować do dowolnego szablonu, także do Given/When/Then i listy kontrolnej.

Given/When/Then i lista kontrolna

Dwa kształty obejmują większość przykładów kryteriów akceptacji, które zespoły naprawdę zachowują. Given/When/Then to scenariusz. Lista kontrolna to lista wyników. Użyj scenariusza, gdy liczy się kolejność stanu, akcji i wyniku. Użyj listy kontrolnej, gdy wymieniasz niezależne wyniki jednej akcji.

Dokumentacja Gherkin Cucumber nadaje krokom słowa kluczowe Given, When, Then, And i But. Ta dokumentacja używa angielskiego; Gherkin ma też tłumaczenia tych słów kluczowych. Słowa po słowie kluczowym są dopasowywane do kodu, nazywanego step definition, gdy Cucumber uruchamia plik. SpecScore nie używa tej warstwy definicji kroków. Przykład poniżej jest w Gherkin, żeby kształt był znajomy. To nie jest plik SpecScore.

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

- Submitting the email "not-an-email" shows "Enter a valid email address" beside the email field.
- The order is not placed.

Zostaw jedno When. Druga akcja to drugi scenariusz. And kontynuuje to samo słowo kluczowe: kolejne Given albo kolejne Then. Nie używaj And, żeby przemycić drugie zachowanie.

Lista kontrolna to ta sama umowa bez słów kluczowych. Każda linia nadal jest jednym obserwowalnym wynikiem. Lista powyżej to Then scenariusza, zapisana jako sprawdzenia.

Jak to się ma do wymagań EARS

Wzorce zdań są opisane w Składnia wymagań EARS wyjaśniona, z przykładami.

Przewodnik Alistaira Mavina definiuje EARS (Easy Approach to Requirements Syntax) jako mechanizm łagodnego ograniczania wymagań tekstowych. Klauzule zostają w jednej kolejności. Przewodnik podaje ogólny kształt: While <optional pre-condition>, when <optional trigger>, the <system name> shall <system response>. Wymaganie ma zero lub więcej warunków wstępnych, zero albo jeden wyzwalacz, jedną nazwę systemu i jedną lub więcej odpowiedzi systemu.

To zdanie jest zobowiązaniem: regułą, którą system ma spełnić. Kryterium akceptacji jest warunkiem, który musi być prawdziwy, aby zobowiązanie liczyło się jako spełnione. Scenariusz Given/When/Then jest jednym konkretnym przypadkiem tego warunku. Możesz zapisać wymaganie zdaniem EARS i nadal trzymać kryterium wolne od przykładowych danych wejściowych.

W funkcjonalności SpecScore wymaganie może być zdaniem w stylu EARS pod nagłówkiem #### REQ:. Kryterium pozostaje abstrakcyjnym warunkiem. Scenariusz niesie przykład. EARS nie zastępuje żadnego z nich. Ogranicza tylko zdanie wymagania.

Przykłady kryteriów akceptacji: ogólnikowe i sprawdzalne

The checkout form should handle bad input gracefully and feel fast.

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.

Users can sign in, reset a password, and see an error if the account is locked.

When a visitor submits a known email and the matching password, the app sets a session cookie and redirects to /dashboard.

The handler returns 400 from validateEmail().

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.

Jak SpecScore je przechowuje i co sprawdza CI

SpecScore publikuje format w repozytorium specscore/specscore, a CLI w specscore/specscore-cli. Te dwa dokumenty nie opisują kryteriów akceptacji w dokładnie tym samym kształcie. Oba są aktualne. Ta sekcja mówi, który jest który, a potem, co naprawdę odrzuca specscore spec lint.

Specyfikacja kryteriów akceptacji — README funkcjonalności udostępniany pod tym adresem — umieszcza kryteria w treści README funkcjonalności. Każda funkcjonalność ma sekcję ## Acceptance Criteria. Każde kryterium to nagłówek ### AC: {slug}. Slug jest pisany małymi literami i z łącznikami. Następna linia to **Requirements:** i wymienia wymagania, które kryterium grupuje, jako {feature-id}#req:{slug}. Potem idzie proza: warunek złożony. Specyfikacja mówi, że ta proza zostaje abstrakcyjna. Nie może zawierać kroków Given/When/Then, przykładowych danych wejściowych ani szczegółu implementacji. Gdy kryteriów jeszcze nie ma, sekcja brzmi „Not defined yet.”, a sekcja Open Questions mówi „Acceptance criteria not yet defined for this feature.”. Kryteria są opcjonalnym grupowaniem: specyfikacja mówi, żeby dodać kryterium, gdy grupuje dwa lub więcej wymagań, i pominąć je, gdy tylko powtórzyłoby pojedyncze wymaganie.

Konkretnym dowodem jest plik scenariusza w katalogu _tests/ funkcjonalności. Specyfikacja scenariuszy wymaga tytułu # Scenario:, sekcji ## Steps, wielkich liter GIVEN, WHEN, THEN oraz AND, i dokładnie jednego WHEN. Opcjonalna linia **Validates:** łączy scenariusz z {feature-path}#ac:{slug} albo z wymaganiem. Sekcja ## Rehearse może zawierać wykonywalny skrypt w bloku rehearse, który zaczyna się od shebanga.

CLI czyta też cienkie pliki kryteriów, po jednym na kryterium, w _acs/<slug>.ac.md. Przykład logowania i przewodnik Rehearse dokumentują ten kształt: # AC: <slug>, opcjonalne **Status:**, **Verifies:** i **Applies-to:**, oraz warunek pod ## Statement. specscore rehearse acs <feature-dir> wypisuje tabelę podsumowania z tych plików. specscore rehearse acs --write zastępuje sekcję Acceptance Criteria w README funkcjonalności tą tabelą i komentarzem, że sekcja jest generowana i nie powinna być edytowana ręcznie. Plik bez nagłówka # AC: jest błędem tego polecenia.

CI w tym repozytorium to workflow dogfood. Instaluje CLI v0.39.1 i uruchamia specscore spec lint przy pull requestach i przy pushach na main. Sprawdzone 3 listopada 2026, to wydanie i domyślna gałąź CLI zawierają poniższe reguły. Linter sprawdza strukturę. Nie ocenia angielskiego.

Reguła ac-heading-format jest błędem. W README funkcjonalności (pliku, którego tytuł to # Feature:) linia, która wygląda jak nagłówek kryterium akceptacji, musi mieć dokładnie postać ### AC: <id> z jedną spacją po dwukropku i identyfikatorem w kebab-case. Akceptowany jest też nagłówek w postaci ### AC: <id> (verifies ...). --fix poprawia tylko odstępy. Identyfikator z wielkimi literami albo podkreśleniami jest zgłaszany i zostawiany osobie. Reguła nie wymaga linii **Requirements:**, nie wymaga zastępnika „Not defined yet.” i nie ostrzega, gdy proza zawiera Given, When albo Then. Własny scenariusz specyfikacji dla tego ostrzeżenia nie jest regułą lintera w tej CLI.

W planie, który nazywa funkcjonalność źródłową, linter czyta nagłówki ### AC: wewnątrz sekcji Acceptance Criteria tej funkcjonalności. Reguła P-002 zgłasza wartość **Verifies:** zadania, która nie jest <feature-slug>#ac:<ac-slug> dla jednego z tych nagłówków. Reguła P-001 zgłasza nagłówek, którego nie pokrywa żadne zadanie i który nie jest wymieniony pod ## Deferred AC Coverage. Te dwie reguły nie otwierają _acs/*.ac.md. Tabela podsumowania z rehearse acs --write nie ma nagłówków ### AC:, więc reguły planu nie widzą cienkich plików.

To samo polecenie lint nie sprawdza słów kluczowych kroków scenariusza. specscore rehearse uruchamia pliki scenariuszy: przewodnik Rehearse używa nagłówka takiego jak ## Given albo ## When nad poleceniem w bloku oraz **Use:**, żeby wywołać sprawdzanie wielokrotnego użytku. Plik z jednym Given i kilkoma gałęziami When uruchamia się jako osobne przypadki. specscore rehearse new <feature-slug>#ac:<ac-slug> czyta README funkcjonalności i wyciąga linie Given/When/Then z tego kryterium do spec/features/<feature-slug>/_tests/<ac-slug>.md. Nic z tego nie jest uruchamiane w workflow dogfood. Ten workflow uruchamia specscore spec lint.

## 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.

# 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.

# 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

# 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
```

Cztery próbki ilustrują te kształty. Nie są kompletnym drzewem funkcjonalności i ta strona nie twierdzi, że same przechodzą specscore spec lint. README funkcjonalności potrzebuje też pozostałych wymaganych sekcji, zanim to polecenie będzie czyste.

Jeśli chcesz listę pytań, żeby wydobyć kryterium z ogólnikowej prośby, użyj Zadawanie dobrych pytań. Przewodnik logowania pokazuje jedno cienkie kryterium, session-hardened, na miejscu wśród pozostałych artefaktów.

Najczęstsze pytania

Źródła

Przeczytano 3 listopada 2026. Strony osób trzecich są cytowane tylko dla definicji, które publikują.

• Cucumber — dokumentacja Gherkin
• Cucumber — rozwój sterowany zachowaniem
• Alistair Mavin — EARS
• Składnia wymagań EARS wyjaśniona, z przykładami
• SpecScore — specyfikacja kryteriów akceptacji
• specscore/specscore — funkcjonalność kryteriów akceptacji
• specscore/specscore — funkcjonalność scenariuszy
• specscore/specscore — funkcjonalność wymagań
• SpecScore — specyfikacja funkcjonalności
• SpecScore — Rehearse
• SpecScore — przykład logowania
• SpecScore — Zadawanie dobrych pytań
• specscore/specscore-cli
• specscore/specscore
• Workflow dogfood (CLI v0.39.1)
• specscore-cli — ac-heading-format
• specscore-cli — reguły planu P-001 i P-002

Powiązane

• Szablon PRD w Markdown do programowania z AI
• Lintowanie specyfikacji w CI linterem specyfikacji
• Składnia wymagań EARS wyjaśniona, z przykładami
• Rozwój sterowany specyfikacją
• Narzędzia rozwoju sterowanego specyfikacją
• Specyfikacja kryteriów akceptacji
• Zadawanie dobrych pytań
• Funkcjonalność logowania, na przykładzie
• Rehearse
• Co waliduje SpecScore
• CLI