How to Write Clear Acceptance Criteria | Agile Guide
Write testable acceptance criteria that eliminate rework. Define done before development starts using GIVEN-WHEN-THEN format, PO collaboration, and GitScrum tracking.
9 min read
Clear acceptance criteria align expectations. GitScrum helps track criteria completion and ensures nothing is missed before a story is marked done.
Acceptance Criteria Basics
Purpose
WHY ACCEPTANCE CRITERIA MATTER:
┌─────────────────────────────────────────────────────────────┐
│ │
│ WITHOUT CLEAR CRITERIA: │
│ ─────────────────────── │
│ Developer: "I think it's done" │
│ PO: "That's not what I meant" │
│ Developer: "Back to the drawing board..." │
│ → Rework, frustration, delays │
│ │
│ WITH CLEAR CRITERIA: │
│ ──────────────────── │
│ Developer: "All criteria met and verified" │
│ PO: "Great, let's ship it" │
│ → First-time right, everyone aligned │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ ACCEPTANCE CRITERIA DEFINE: │
│ ─────────────────────────── │
│ │
│ BOUNDARIES: │
│ What's in scope, what's not │
│ "Password reset via email only (not SMS)" │
│ │
│ BEHAVIOR: │
│ How the feature should work │
│ "Shows error if email not found" │
│ │
│ CONDITIONS: │
│ Edge cases and special scenarios │
│ "Link expires after 24 hours" │
│ │
│ MEASURABLE OUTCOMES: │
│ Performance, accessibility │
│ "Page loads in under 2 seconds" │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ GOOD CRITERIA ARE: │
│ ────────────────── │
│ ✅ Testable (can verify yes/no) │
│ ✅ Clear (no ambiguity) │
│ ✅ Concise (not a novel) │
│ ✅ Independent (can test each one) │
│ ✅ Focused on outcome (not implementation) │
└─────────────────────────────────────────────────────────────┘
Writing Formats
Given-When-Then
GIVEN-WHEN-THEN FORMAT:
┌─────────────────────────────────────────────────────────────┐
│ │
│ STRUCTURE: │
│ ────────── │
│ GIVEN [precondition/context] │
│ WHEN [action/trigger] │
│ THEN [expected outcome] │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ EXAMPLE: Password Reset │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ STORY: As a user, I want to reset my password ││
│ │ ││
│ │ ACCEPTANCE CRITERIA: ││
│ │ ││
│ │ 1. GIVEN I am on the login page ││
│ │ WHEN I click "Forgot password" ││
│ │ THEN I see the password reset form ││
│ │ ││
│ │ 2. GIVEN I entered a registered email ││
│ │ WHEN I submit the reset request ││
│ │ THEN I receive a reset email within 1 minute ││
│ │ ││
│ │ 3. GIVEN I entered an unregistered email ││
│ │ WHEN I submit the reset request ││
│ │ THEN I see "No account with this email" ││
│ │ ││
│ │ 4. GIVEN I click the reset link in email ││
│ │ WHEN I set a new password ││
│ │ THEN I can log in with the new password ││
│ │ ││
│ │ 5. GIVEN the reset link is over 24 hours old ││
│ │ WHEN I click the link ││
│ │ THEN I see "Link expired, request new reset" ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ BENEFITS: │
│ • Structured and consistent │
│ • Easy to convert to automated tests │
│ • Clear preconditions │
└─────────────────────────────────────────────────────────────┘
Checklist Format
CHECKLIST FORMAT:
┌─────────────────────────────────────────────────────────────┐
│ │
│ STRUCTURE: │
│ ────────── │
│ Simple list of conditions that must be true │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ EXAMPLE: User Profile Page │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ STORY: As a user, I want to view my profile ││
│ │ ││
│ │ ACCEPTANCE CRITERIA: ││
│ │ ││
│ │ ☐ Profile shows name, email, and avatar ││
│ │ ☐ Avatar displays initials if no image uploaded ││
│ │ ☐ Edit button visible for own profile only ││
│ │ ☐ Last login date displayed ││
│ │ ☐ Page loads in under 2 seconds ││
│ │ ☐ Works on mobile (responsive) ││
│ │ ☐ Accessible via keyboard navigation ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ BENEFITS: │
│ • Quick to write │
│ • Easy to review in demos │
│ • Simple pass/fail verification │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ WHEN TO USE WHICH: │
│ ────────────────── │
│ │
│ GIVEN-WHEN-THEN: │
│ • Complex user interactions │
│ • Many edge cases │
│ • Will become automated tests │
│ │
│ CHECKLIST: │
│ • Simpler features │
│ • Non-functional requirements │
│ • Quick verification needed │
└─────────────────────────────────────────────────────────────┘
Common Patterns
Criteria by Type
ACCEPTANCE CRITERIA PATTERNS:
┌─────────────────────────────────────────────────────────────┐
│ │
│ HAPPY PATH: │
│ ─────────── │
│ The main success scenario │
│ "When user enters valid data, record is created" │
│ │
│ ERROR HANDLING: │
│ ─────────────── │
│ What happens when things go wrong │
│ "When email is invalid, show specific error message" │
│ │
│ EDGE CASES: │
│ ─────────── │
│ Boundary conditions │
│ "When 0 items in cart, show empty cart message" │
│ "When 100+ items, show pagination" │
│ │
│ PERMISSIONS: │
│ ──────────── │
│ Who can do what │
│ "Only admin can delete users" │
│ "Users can only edit their own profile" │
│ │
│ PERFORMANCE: │
│ ──────────── │
│ Speed and scale requirements │
│ "Search returns results in under 500ms" │
│ "Supports 1000 concurrent users" │
│ │
│ ACCESSIBILITY: │
│ ────────────── │
│ Inclusive design requirements │
│ "All forms navigable by keyboard" │
│ "Images have alt text" │
│ │
│ SECURITY: │
│ ───────── │
│ Protection requirements │
│ "Passwords stored hashed, not plaintext" │
│ "Session expires after 30 min inactive" │
└─────────────────────────────────────────────────────────────┘
Complete Example
COMPREHENSIVE STORY WITH AC:
┌─────────────────────────────────────────────────────────────┐
│ │
│ STORY-456: Shopping Cart Checkout │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ AS A customer ││
│ │ I WANT TO complete checkout ││
│ │ SO THAT I receive my order ││
│ │ ││
│ │ ═══════════════════════════════════════════════════════ ││
│ │ ││
│ │ ACCEPTANCE CRITERIA: ││
│ │ ││
│ │ CART REVIEW: ││
│ │ ☐ Shows all items with name, price, quantity ││
│ │ ☐ Can modify quantities (1-99) ││
│ │ ☐ Can remove items ││
│ │ ☐ Shows subtotal, tax, and total ││
│ │ ││
│ │ SHIPPING: ││
│ │ ☐ Address form validates required fields ││
│ │ ☐ Postal code validates format ││
│ │ ☐ Shows shipping options with prices ││
│ │ ☐ Saves address for future orders (opt-in) ││
│ │ ││
│ │ PAYMENT: ││
│ │ ☐ Accepts Visa, Mastercard, Amex ││
│ │ ☐ Card number validates with Luhn algorithm ││
│ │ ☐ CVV required and hidden ││
│ │ ☐ Shows card type icon based on number ││
│ │ ││
│ │ CONFIRMATION: ││
│ │ GIVEN valid cart, shipping, and payment ││
│ │ WHEN customer clicks "Place Order" ││
│ │ THEN order is created and confirmation shown ││
│ │ AND confirmation email sent within 1 minute ││
│ │ ││
│ │ ERROR HANDLING: ││
│ │ ☐ Payment failure shows "Payment declined" ││
│ │ ☐ Can retry payment without re-entering details ││
│ │ ☐ Out of stock items blocked with message ││
│ │ ││
│ │ NON-FUNCTIONAL: ││
│ │ ☐ Checkout flow completes in under 3 clicks ││
│ │ ☐ Works on mobile devices ││
│ │ ☐ Page load under 2 seconds ││
│ │ ││
│ │ OUT OF SCOPE: ││
│ │ • PayPal (separate story) ││
│ │ • Gift cards (separate story) ││
│ │ • Multiple shipping addresses ││
│ └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘
Common Mistakes
Anti-patterns
ACCEPTANCE CRITERIA ANTI-PATTERNS:
┌─────────────────────────────────────────────────────────────┐
│ │
│ TOO VAGUE: │
│ ────────── │
│ ❌ "The form should be user-friendly" │
│ ❌ "Performance should be good" │
│ ❌ "Handle errors appropriately" │
│ │
│ ✅ "Form has inline validation" │
│ ✅ "Page loads in under 2 seconds" │
│ ✅ "Invalid email shows 'Enter valid email'" │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ IMPLEMENTATION DETAILS: │
│ ─────────────────────── │
│ ❌ "Use React for the frontend" │
│ ❌ "Store in PostgreSQL database" │
│ ❌ "Use REST API with JSON" │
│ │
│ ✅ "Data persists after page refresh" │
│ ✅ "API returns response in under 200ms" │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ TOO MANY: │
│ ───────── │
│ ❌ 25 acceptance criteria for one story │
│ (story too big, split it) │
│ │
│ ✅ 3-8 criteria per story is typical │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ TOO FEW: │
│ ──────── │
│ ❌ No criteria at all ("we'll figure it out") │
│ ❌ Only happy path covered │
│ │
│ ✅ Cover happy path + key error cases │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ NOT TESTABLE: │
│ ───────────── │
│ ❌ "Users should like the new design" │
│ ❌ "System should be scalable" │
│ │
│ ✅ "User satisfaction survey scores 4/5+" │
│ ✅ "System handles 1000 concurrent requests" │
└─────────────────────────────────────────────────────────────┘