Як писати критерії приймання, які перевірить ШІ-агент

Що таке критерії приймання

Критерій приймання відповідає на питання «що має бути істинним?». Він називає умову, яку рецензент, тест або агент може прийняти чи відхилити. Він не називає функцію, яку треба викликати, і не називає файл, який треба редагувати. Ці рішення належать реалізації.

Вимога — це правило. У специфікації вимог SpecScore вимога — це заголовок #### REQ: усередині функції: одне зобов’язання, зі своїм ідентифікатором. Критерій приймання збирає пов’язані вимоги в одну умову. Сценарій — це один конкретний випадок, який показує, що умова виконується. Специфікація критеріїв приймання каже так: критерії відповідають на питання «що має бути істинним?», а сценарії — на питання «як ми це доведемо?».

PRD може містити той самий намір абзацами. Абзаци допомагають людині. Агентові все одно доводиться вгадувати, яке речення є перевіркою «пройдено чи ні». Запис критерію окремим твердженням прибирає цей здогад.

Що робить критерії приймання перевірюваними

ШІ-агент для написання коду може йти за критерієм лише тоді, коли пізніший читач може вказати на свідчення і сказати «пройдено» або «не пройдено». П’ять звичок роблять це можливим. Жодна з них не є шаблоном речення. Це перевірки, які можна застосувати до будь-якого шаблону, включно з Given/When/Then і контрольним списком.

Given/When/Then і контрольний список

Дві форми покривають більшість прикладів критеріїв приймання, які команди справді зберігають. Given/When/Then — це сценарій. Контрольний список — це перелік результатів. Беріть сценарій, коли важливий порядок стану, дії і результату. Беріть контрольний список, коли перелічуєте незалежні результати однієї дії.

Довідник Gherkin від Cucumber дає крокам ключові слова Given, When, Then, And і But. Довідник використовує англійську; Gherkin має і переклади цих слів. Текст після ключового слова зіставляється з кодом, який називається step definition, коли Cucumber виконує файл. SpecScore не використовує цей шар step definition. Приклад нижче — Gherkin, щоб форма була знайомою. Це не файл 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.

Лишіть один When. Друга дія — це другий сценарій. And продовжує те саме ключове слово: ще один Given або ще один Then. Не використовуйте And, щоб пронести другу поведінку.

Контрольний список — той самий договір без ключових слів. Кожен рядок і далі є одним спостережуваним результатом. Контрольний список вище — це Then сценарію, записаний як перевірки.

Як це стосується вимог EARS

Шаблони речень описано в Синтаксис вимог EARS з поясненням і прикладами.

Посібник Alistair Mavin визначає EARS (Easy Approach to Requirements Syntax) як механізм, що м’яко обмежує текстові вимоги. Клаузи лишаються в одному порядку. Посібник дає загальну форму: While <optional pre-condition>, when <optional trigger>, the <system name> shall <system response>. Вимога має нуль або більше передумов, нуль або один тригер, одне ім’я системи і одну або більше відповідей системи.

Це речення — зобов’язання: правило, яке система має виконати. Критерій приймання — умова, яка має бути істинною, щоб зобов’язання вважалося виконаним. Сценарій Given/When/Then — один конкретний випадок цієї умови. Можна написати вимогу реченням EARS і все одно тримати критерій вільним від зразків введення.

У функції SpecScore вимога може бути реченням у стилі EARS під заголовком #### REQ:. Критерій лишається абстрактною умовою. Сценарій несе приклад. EARS не замінює ні того, ні іншого. Він лише обмежує речення вимоги.

Приклади критеріїв приймання: розпливчасті й перевірювані

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.

Як SpecScore їх зберігає і що перевіряє CI

SpecScore публікує формат у репозиторії specscore/specscore, а CLI — у specscore/specscore-cli. Ці два документи описують критерії приймання не зовсім в одній і тій самій формі. Обидва актуальні. Цей розділ каже, який документ якій формі відповідає, а потім — що саме відхиляє specscore spec lint.

Специфікація критеріїв приймання (README функції за цим URL) кладе критерії просто в README функції. Кожна функція має розділ ## Acceptance Criteria. Кожен критерій — це заголовок ### AC: {slug}. Slug пишеться малими літерами і через дефіс. Наступний рядок — **Requirements:**, і він перелічує вимоги, які критерій збирає, у вигляді {feature-id}#req:{slug}. Далі йде проза: складена умова. Специфікація каже, що ця проза лишається абстрактною. У ній не має бути кроків Given/When/Then, зразків введення і подробиць реалізації. Якщо критеріїв ще немає, розділ читається як «Not defined yet.», а розділ Open Questions каже «Acceptance criteria not yet defined for this feature.». Критерії — необов’язкове групування: специфікація велить додати критерій, коли він збирає дві або більше вимог, і пропустити його, коли він лише повторив би одну вимогу.

Конкретний доказ — файл сценарію в каталозі _tests/ цієї функції. Специфікація сценаріїв вимагає заголовок # Scenario:, розділ ## Steps, великі літери GIVEN, WHEN, THEN і AND, і рівно один WHEN. Необов’язковий рядок **Validates:** пов’язує сценарій із {feature-path}#ac:{slug} або з вимогою. Розділ ## Rehearse може містити виконуваний скрипт у блоці rehearse, який починається з shebang.

CLI також читає тонкі файли критеріїв, по одному на критерій, за шляхом _acs/<slug>.ac.md. Приклад входу і посібник Rehearse описують цю форму: # AC: <slug>, необов’язкові **Status:**, **Verifies:** і **Applies-to:**, і умову під ## Statement. specscore rehearse acs <feature-dir> друкує зведену таблицю з цих файлів. specscore rehearse acs --write замінює розділ Acceptance Criteria в README функції цією таблицею і коментарем про те, що розділ згенеровано і його не слід правити вручну. Файл без заголовка # AC: — помилка цієї команди.

CI в цьому репозиторії — це воркфлоу dogfood. Він встановлює CLI v0.39.1 і запускає specscore spec lint для pull request і для push до main. На 3 листопада 2026 року перевірено: цей реліз і гілка за замовчуванням CLI обидва містять правила нижче. Лінтер перевіряє структуру. Він не оцінює англійський текст.

Правило ac-heading-format — це помилка. У README функції (файлі, заголовок якого — # Feature:) рядок, який виглядає як заголовок критерію приймання, має бути точно ### AC: <id>, з одним пробілом після двокрапки і ідентифікатором у kebab-case. Заголовок вигляду ### AC: <id> (verifies ...) теж приймається. --fix лагодить лише пробіли. Ідентифікатор із великими літерами або підкресленнями повідомляється і лишається людині. Правило не вимагає рядок **Requirements:**, не вимагає заповнювач «Not defined yet.» і не попереджає, якщо проза містить Given, When або Then. Власний сценарій специфікації для цього попередження в цьому CLI не є правилом lint.

У плані, який називає вихідну функцію, лінтер читає заголовки ### AC: усередині розділу Acceptance Criteria цієї функції. Правило P-002 повідомляє значення **Verifies:** задачі, яке не дорівнює <feature-slug>#ac:<ac-slug> для одного з цих заголовків. Правило P-001 повідомляє заголовок, якого не покриває жодна задача і якого не перелічено в ## Deferred AC Coverage. Ці два правила не відкривають _acs/*.ac.md. Зведена таблиця з rehearse acs --write не має заголовків ### AC:, тож правила плану не бачать тонкі файли.

Та сама команда lint не перевіряє ключові слова кроків сценарію. specscore rehearse запускає файли сценаріїв: посібник Rehearse ставить заголовок на кшталт ## Given або ## When над командою в блоці коду і **Use:**, щоб викликати придатну до повторного використання перевірку. Файл з одним Given і кількома гілками When виконується як окремі випадки. specscore rehearse new <feature-slug>#ac:<ac-slug> читає README функції і витягує рядки Given/When/Then із цього критерію в spec/features/<feature-slug>/_tests/<ac-slug>.md. Ніщо з цього не виконується у воркфлоу dogfood. Воркфлоу запускає 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
```

Чотири зразки ілюструють ці форми. Вони не є повним деревом функцій, і ця сторінка не стверджує, що вони самі по собі проходять specscore spec lint. README функції потрібні й інші обов’язкові розділи, перш ніж ця команда завершиться чисто.

Якщо потрібен список питань, щоб витягти критерій із розпливчастого запиту, візьміть Як ставити добрі питання. Розбір входу показує один тонкий критерій, session-hardened, на своєму місці серед інших артефактів.

Питання й відповіді

Джерела

Прочитано 3 листопада 2026 року. Сторонні сторінки цитуються лише за визначення, які вони публікують.

• Cucumber — довідник Gherkin
• Cucumber — розробка, керована поведінкою
• Alistair Mavin — EARS
• Синтаксис вимог EARS з поясненням і прикладами
• SpecScore — специфікація критеріїв приймання
• specscore/specscore — функція критеріїв приймання
• specscore/specscore — функція сценарію
• specscore/specscore — функція вимоги
• SpecScore — специфікація функції
• SpecScore — Rehearse
• SpecScore — приклад входу
• SpecScore — Як ставити добрі питання
• specscore/specscore-cli
• specscore/specscore
• Воркфлоу dogfood (CLI v0.39.1)
• specscore-cli — ac-heading-format
• specscore-cli — правила плану P-001 і P-002

Пов’язане

• Шаблон PRD у Markdown для програмування зі ШІ
• Лінтувати специфікації в CI лінтером специфікацій
• Синтаксис вимог EARS з поясненням і прикладами
• Розробка за специфікаціями
• Інструменти розробки за специфікаціями
• Специфікація критеріїв приймання
• Як ставити добрі питання
• Функція входу на прикладі
• Rehearse
• Що перевіряє SpecScore
• CLI