Part of Mechanisms of Vibe Coding

Mechanism: Acceptance Criteria

One-sentence definition

Acceptance criteria are specific, checkable conditions that must all pass for work to count as done — turning a goal from a headline into a checklist the agent and tests can enforce.

The problem

Your goal says “health endpoint works.” The agent returns { ok: true } with no uptime, wrong content-type, or breaks the default response without verbose. You argued about whether it “works” because done was one sentence for a multi-aspect outcome.

Goals point direction. Acceptance criteria define the contract — often several bullets, each independently verifiable.

Symptoms:

• Debates after verify “passes” on a narrow test
• Agent fixes one aspect and regresses another
• QA finds issues not covered by the single test you wrote
• “Works on my machine” with no shared checklist

How it works

Write criteria as Given / When / Then or plain bullets — each must be testable or observable:

Goal: Optional verbose health details

Acceptance criteria:
- AC1: GET /health without query returns { ok: boolean } only (unchanged)
- AC2: GET /health?verbose=1 returns ok + details.uptime (number, seconds)
- AC3: details appears only when verbose=1; no extra keys when absent
- AC4: health.test.ts covers AC1–AC3

Map criteria to tests where possible. Verify loop runs the suite; criteria tell you what the suite must prove.

  Goal (summary outcome)
       │
       ▼
  Acceptance criteria (checklist)
       │
       ▼
  Tests / manual checks per criterion
       │
       ▼
  All green ──► done

When to use it

• Multi-aspect features (API + backward compatibility + errors)
• Work handed to agents or other humans — shared definition of done
• Before loops — criteria become loop termination targets
• Replacing vague goals like “handle errors properly”

When not to use it

• Single-criterion bugfix — one test may be enough; do not inflate
• Criteria you cannot check — “feels fast” needs a metric or drop it
• Copy-pasting criteria from a template without reading the feature

Failure modes

One mega-criterion — “Works correctly in all cases.” Fix: Split into observable bullets.

Untestable criteria — “Clean code.” Fix: Lint rule, file boundary, or remove.

Criteria drift — Adding ACs mid-session without updating tests. Fix: New AC → new test or explicit manual check in verify.

Orphan tests — Tests that do not map to any AC. Fix: Name tests after AC ids or document mapping.

AC without goal — Checklist with no summary outcome. Fix: One goal line plus criteria underneath.

Minimal example

Context: Verbose health endpoint from split-and-conquer slice 1.

Steps:

1. Paste goal + AC block (AC1–AC4 above) before agent edits.

1. Ask agent: “Implement and add tests that map to AC1–AC4.”

1. Verify: every AC has a matching green test or logged manual check.

Done when: You can tick every AC without “well, mostly.”

Tool instances (optional deep-dive)

Portable idea above; this section is tool-specific. Date: June 2026.

Cursor

• Put AC block in first message; reference AC ids in follow-ups (“AC2 still fails”).
• Plan mode: Require plan steps labeled AC1, AC2, …
• Rules: “Do not mark done until all acceptance criteria are verified.”

Other tools

BDD frameworks (Gherkin), issue templates with AC sections — same mechanism in Jira/GitHub.

Related mechanisms

• Goal — summary; AC is the expanded contract
• Verify loop — runs checks against criteria
• Example-driven spec — examples as criteria for behavior

Try it yourself

Exercise: Take one goal you already wrote. Add 3–5 acceptance criteria — each falsifiable in one sentence.

You need: Existing goal or backlog item; five minutes

Done when: A failing criterion would force you to say “not done” even if the agent claims success.