Writing effective acceptance criteria

Good acceptance criteria are specific, verifiable, and complete. This guide shows how to write criteria that lead to accurate verification.

Be specific

Vague criteria can’t be reliably verified.

Too vague:

-[ ] Endpoint is secure

Specific:

-[ ] Requires authentication via Bearer token
-[ ] Returns 401 for missing or invalid token
-[ ] Returns 403 if user lacks permission

Too vague:

-[ ] Handles errors properly

Specific:

-[ ] Returns 404 if resource not found
-[ ] Returns 503 if downstream service unavailable
-[ ] Error responses include correlation ID

Include both positive and negative requirements

Say what should happen and what shouldn’t.

-[ ] Response includes: status, renewal_date, plan_name
-[ ] Response excludes: internal_id, billing_provider_id

-[ ] Creates new user record
-[ ] Does not modify existing user records

Negative requirements often catch bugs that positive requirements miss.

Cover error cases

Don’t just test the happy path.

-[ ] Returns 400 for malformed request body
-[ ] Returns 404 if subscription not found
-[ ] Returns 409 if resource already exists
-[ ] Returns 503 if payment service unavailable

Think about what could go wrong and how your code should respond.

Add performance requirements only when meaningful

-[ ] P99 latency under 200ms
-[ ] No N+1 queries

Only include these if they’re actual requirements. Don’t add “P99 under 100ms” to everything just because it sounds good.

Express constraints as criteria

Things that must not happen:

-[ ] No new external dependencies
-[ ] Does not modify database schemas
-[ ] Does not call billing-service directly
-[ ] No breaking changes to existing API

Use concrete values

Vague:

-[ ] Returns appropriate status code

Concrete:

-[ ] Returns HTTP 201 on successful creation

Vague:

-[ ] Response includes required fields

Concrete:

-[ ] Response includes: id, name, created_at

Group related criteria

For readability, group criteria by concern:

## Acceptance Criteria

### Endpoint behavior
-[ ] Endpoint: `POST /api/v1/users`
-[ ] Accepts JSON request body
-[ ] Returns HTTP 201 on success

### Validation
-[ ] Returns 400 if email is missing
-[ ] Returns 400 if email format is invalid
-[ ] Returns 409 if email already exists

### Response
-[ ] Response includes: id, email, created_at
-[ ] Response excludes: password_hash

### Security
-[ ] Requires admin authentication
-[ ] Password is hashed before storage

Common patterns

REST endpoint

-[ ] Endpoint: `GET /api/v1/resource/{id}`
-[ ] Requires authentication
-[ ] Returns 200 with resource data
-[ ] Returns 404 if not found
-[ ] Returns 403 if user lacks access
-[ ] Response format matches ResourceSchema

Data mutation

-[ ] Creates/updates record in database
-[ ] Validates input before persisting
-[ ] Returns created/updated resource
-[ ] Emits event to message queue
-[ ] Operation is idempotent

Integration

-[ ] Calls external-service API
-[ ] Handles timeout with retry
-[ ] Handles 5xx with graceful degradation
-[ ] Logs external call with correlation ID

Criteria to avoid

Implementation details:

# Bad - specifies how, not what
-[ ] Uses Redis for caching
-[ ] Implements retry with exponential backoff

Better to focus on behavior:

# Good - specifies observable behavior
-[ ] Caches response for 60 seconds
-[ ] Retries failed requests up to 3 times

Subjective judgments:

# Bad - can't be objectively verified
-[ ] Code is clean and readable
-[ ] Performance is acceptable

Compound criteria:

# Bad - multiple things in one criterion
-[ ] Validates input, creates record, and sends email

Split into separate criteria:

# Good - one thing per criterion
-[ ] Validates input against schema
-[ ] Creates record in database
-[ ] Sends confirmation email

See also

• Tutorial: Your first spec

• Reference: Spec format

• Explanation: How verification works