AI 에이전트가 검증할 수 있는 인수 기준을 쓰는 법

인수 기준이란

인수 기준은 「무엇이 참이어야 하는가」에 답합니다. 리뷰어, 테스트, 또는 에이전트가 받아들이거나 거절할 수 있는 조건을 이름 붙입니다. 호출할 함수나 고칠 파일은 이름 붙이지 않습니다. 그 선택은 구현에 속합니다.

요구사항은 규칙입니다. SpecScore 요구사항 명세에서 요구사항은 기능 안의 #### REQ: 제목입니다. 의무가 하나이고, 식별자가 따로 있습니다. 인수 기준은 관련된 요구사항을 하나의 조건으로 묶습니다. 시나리오는 그 조건이 성립함을 보여 주는 구체적인 사례 하나입니다. 인수 기준 명세는 이렇게 말합니다. 기준은 「무엇이 참이어야 하는가」에 답하고, 시나리오는 「어떻게 증명하는가」에 답합니다.

PRD는 같은 의도를 문단에 담을 수 있습니다. 문단은 사람에게 도움이 됩니다. 에이전트는 어느 문장이 통과와 실패의 시험인지 여전히 짐작해야 합니다. 기준을 그 자체로 한 문장에 쓰면 그 짐작이 사라집니다.

인수 기준을 검증 가능하게 만드는 것

AI 코딩 에이전트가 기준을 따를 수 있는 때는, 나중에 읽는 사람이 증거를 가리키며 통과 또는 실패라고 말할 수 있을 때뿐입니다. 다섯 가지 습관이 그것을 가능하게 합니다. 어느 것도 문장 틀이 아닙니다. Given/When/Then과 체크리스트를 포함해, 어떤 틀에도 적용할 수 있는 검사입니다.

Given/When/Then과 체크리스트

팀이 실제로 남겨 두는 인수 기준 예시의 대부분은 두 형태로 충분합니다. Given/When/Then은 시나리오입니다. 체크리스트는 결과의 목록입니다. 상태, 동작, 결과의 순서가 중요하면 시나리오를 쓰세요. 한 동작에서 서로 독립인 결과를 나열할 때는 체크리스트를 쓰세요.

Cucumber의 Gherkin 레퍼런스는 단계에 Given, When, Then, And, But이라는 키워드를 줍니다. 레퍼런스는 영어를 씁니다. Gherkin에는 그 키워드의 번역도 있습니다. 키워드 뒤의 말은 Cucumber가 파일을 실행할 때 step definition이라는 코드에 맞춰집니다. 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>입니다. 요구사항에는 사전 조건이 0개 이상, 트리거가 0개 또는 1개, 시스템 이름이 하나, 시스템 응답이 하나 이상 있습니다.

그 문장은 의무입니다. 시스템이 지켜야 하는 규칙입니다. 인수 기준은 그 의무가 충족된 것으로 치려면 참이어야 하는 조건입니다. Given/When/Then 시나리오는 그 조건의 구체적인 사례 하나입니다. 요구사항을 EARS 문장으로 쓰고도, 기준에는 예시 입력을 넣지 않은 채로 둘 수 있습니다.

SpecScore 기능에서 요구사항은 #### REQ: 제목 아래의 EARS풍 문장일 수 있습니다. 기준은 추상적인 조건으로 남습니다. 시나리오가 예시를 가집니다. 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가 실제로 거부하는 것을 말합니다.

그 인수 기준 명세, 곧 그 URL에서 제공되는 기능 README는 기준을 기능 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는 기능 README의 Acceptance Criteria 절을 그 표와, 절이 생성되었으며 손으로 고치지 말라는 주석으로 바꿉니다. # AC: 제목이 없는 파일은 그 명령의 오류입니다.

이 저장소의 CI는 dogfood 워크플로입니다. CLI v0.39.1을 설치하고, 풀 리퀘스트와 main으로의 푸시에서 specscore spec lint를 실행합니다. 2026년 11월 3일에 확인한 바로는, 그 릴리스와 CLI 기본 브랜치가 모두 아래 규칙을 포함합니다. 린터가 검사하는 것은 구조입니다. 영어의 잘잘못은 채점하지 않습니다.

규칙 ac-heading-format은 오류입니다. 기능 README(제목이 # Feature:인 파일)에서 인수 기준 제목처럼 보이는 줄은 정확히 ### AC: <id>여야 합니다. 콜론 뒤는 공백 하나, id는 kebab-case입니다. ### AC: <id> (verifies ...) 형태의 제목도 받습니다. --fix는 공백만 고칩니다. 대문자나 밑줄이 있는 id는 보고되고 사람에게 남습니다. 이 규칙은 **Requirements:** 줄을 요구하지 않고, 「Not defined yet.」자리표시도 요구하지 않으며, 산문에 Given, When, Then이 있어도 경고하지 않습니다. 그 경고를 위한 명세 자신의 시나리오는 이 CLI의 lint 규칙이 아닙니다.

원본 기능을 이름 붙인 계획에서, 린터는 그 기능의 Acceptance Criteria 절 안에 있는 ### AC: 제목을 읽습니다. 규칙 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를 다른 산출물 사이에 두어 보여 줍니다.

자주 묻는 질문

출처

2026년 11월 3일에 읽었습니다. 제3자 페이지는 그곳에 공개된 정의에 대해서만 인용합니다.

• 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

관련

• AI 코딩을 위한 Markdown PRD 템플릿
• CI에서 명세 린터로 명세를 린트하기
• EARS 요구사항 구문을 예와 함께 설명
• 스펙 주도 개발
• 스펙 주도 개발 도구
• 인수 기준 명세
• 좋은 질문 하기
• 로그인 기능을 예시로
• Rehearse
• SpecScore가 검증하는 것
• CLI