Writing acceptance criteria with Given/When/Then: A practical guide

Acceptance criteria answer one question: "How do we know this is done?"

In traditional development, vague acceptance criteria are annoying but survivable — the developer asks clarifying questions. With AI coding agents, vague criteria are fatal. The agent doesn't ask questions. It guesses. And it guesses wrong.

What is Given/When/Then?

Given/When/Then is a format from Behavior-Driven Development (BDD) that structures acceptance criteria as scenarios:

• Given — the initial state or precondition
• When — the action or event
• Then — the expected outcome

Example:

``` Given a user is logged in and has admin role When they navigate to /settings/team Then they see the team management panel with member list ```

This format is powerful because it's simultaneously human-readable and machine-parseable. Your PM can write it. Your AI agent can consume it.

Why Given/When/Then matters for AI agents

AI coding agents use acceptance criteria to:

1. Scope the implementation — Each scenario defines a concrete behavior to implement
2. Generate tests — Given/When/Then maps directly to test cases
3. Self-verify — The agent can check its own output against the criteria
4. Prevent scope creep — If it's not in a scenario, it's not in scope

Without acceptance criteria, the agent has to infer what "done" means from the spec description. This is where hallucination happens.

How to write good acceptance criteria

Rule 1: One behavior per scenario

Bad: ``` Given a user submits the form Then the data is saved, an email is sent, and the dashboard updates ```

Good: ``` Scenario 1: Data persistence Given a user fills in all required fields When they click Submit Then the form data is saved to the database

Scenario 2: Email notification Given a user has submitted the form When the save is successful Then a confirmation email is sent to the user's address

Scenario 3: Dashboard update Given a user has submitted the form When they navigate to the dashboard Then the new entry appears in the recent activity list ```

Rule 2: Be specific about state

Bad: ``` Given a user is on the page When they do the thing Then it works ```

Good: ``` Given a user is authenticated with role "editor" And they are viewing project "acme-web" change #42 When they click the "Approve" button Then the change status transitions from "review" to "ready" And a notification is sent to the change author ```

Rule 3: Include negative scenarios

Don't just test the happy path. AI agents need to know what should NOT happen:

``` Given a user is authenticated with role "viewer" When they attempt to click the "Approve" button Then the button is disabled And a tooltip shows "Only editors and admins can approve" ```

Rule 4: Specify edge cases explicitly

``` Given a user submits the form with an email field containing "user@" When validation runs Then an inline error appears: "Please enter a valid email address" And the form is NOT submitted ```

Acceptance criteria in Colign

Colign treats acceptance criteria as first-class entities, not footnotes. Each scenario is:

• Independently created and managed (separate from the proposal document)
• Structured as Given/When/Then with dedicated fields
• Trackable — mark scenarios as "met" during implementation
• Accessible via MCP — AI agents can list and read all scenarios

This means your AI agent doesn't just see "build a login page." It sees every specific behavior the login page must exhibit, every edge case it must handle, and every negative scenario it must prevent.

From criteria to code: The flow

1. PM/Engineer writes scenarios in Colign using Given/When/Then
2. Team reviews scenarios during spec review (catches missing cases early)
3. AI agent reads scenarios via MCP when implementing
4. Agent generates tests that map 1:1 to scenarios
5. Agent implements code to pass those tests
6. Scenarios marked "met" as tests pass

This is the tightest possible loop between "what should it do?" and "does it do it?"

FAQ

Q: How many scenarios per spec? A: Typically 5–15. Fewer than 5 usually means missing edge cases. More than 15 might mean the spec scope is too large.

Q: Should acceptance criteria be technical or business-focused? A: Business-focused, written in domain language. The AI agent translates to technical implementation. This keeps criteria accessible to PMs and designers.

Q: Can AI help write acceptance criteria? A: Yes. Colign's `suggest_spec` tool can propose scenarios based on your spec. But always review them — AI tends to miss negative scenarios and domain-specific edge cases.