_1751731246795-BygAaJJK.png){kind=logo}
How do you write software acceptance criteria that actually prevent disputes?
Why Most Acceptance Criteria Fail
Disputes usually don't come from bad faith—they come from two parties reading the same sentence and picturing different things. Phrases like 'the dashboard should load quickly' or 'the app should handle high traffic' feel clear when written but collapse the moment testing begins. Good criteria eliminate the gap between what was imagined and what was built.
The Core Formula: Given / When / Then
Borrow the Gherkin format used in behavior-driven development. It forces specificity:
- Given a precondition or starting state
- When a user or system takes a specific action
- Then a measurable outcome occurs
Example: Given a registered user on a slow 3G connection, when they open the order history page, then the page fully renders within 3 seconds and displays the last 50 orders. That single sentence replaces 'the app should be fast and show order history.'
Six Rules Worth Following
- Replace adjectives with numbers. 'Fast' becomes '≤2 seconds.' 'Reliable' becomes '99.5% uptime measured monthly.'
- Specify edge cases explicitly. What happens if a file upload exceeds the size limit? If a payment gateway times out? Silence on edge cases is where disputes are born.
- Separate functional from non-functional criteria. Keep behavior (what it does) and quality attributes (how well it does it) in distinct sections so nothing gets missed.
- Include negative cases. 'The system must reject login attempts after 5 failed tries within 10 minutes' is as important as the happy path.
- Get written sign-off before development starts. A shared document with dated approvals from both the client and the development lead is the single most dispute-preventive step you can take.
- Tie criteria to milestones, not just final delivery. Milestone-based review catches misalignment early, when correction is cheap.
What to Include in the Document
| Section | What It Contains |
|---|---|
| Feature description | One-sentence plain-English summary of the feature |
| Acceptance criteria | Given/When/Then statements, one per testable behavior |
| Out of scope | Explicit list of what will NOT be built in this iteration |
| Test method | Who tests it and how (manual QA, automated test, UAT session) |
| Sign-off | Names, roles, and date of approval |
Honest Tradeoffs
Writing tight criteria takes time upfront—typically a structured discovery session before any development begins. Teams that skip this to move faster almost always spend more time in disputes later. The tradeoff is front-loaded clarity vs. back-loaded conflict.
CodeNicely runs a structured scoping phase before every engagement precisely because of this: all acceptance criteria, edge cases, and out-of-scope boundaries are documented and signed off before the first sprint. It's one of the practices that has helped ship 50+ products without IP or delivery disputes.
Related questions
Who should write the acceptance criteria—the client or the development team?
Both. The client defines the business outcome they need; the development team translates it into testable technical statements. Neither side alone catches all the gaps. A joint review session before sign-off is the practical minimum.
How detailed is too detailed when writing acceptance criteria?
If a criterion describes implementation choices—specific algorithms, database schemas, or code structure—it's too detailed. Criteria should describe what the system does from a user or system perspective, not how the code achieves it. That boundary keeps developers free to make good technical decisions while keeping clients protected on outcomes.
What happens when requirements change mid-project?
Any change to scope should trigger a written amendment to the acceptance criteria, with a new sign-off. A lightweight change-request form that logs what changed, why, and the impact on timeline or cost prevents retrospective disputes about what was originally agreed.
Can acceptance criteria be written for design or UX deliverables, not just code?
Yes. Design criteria might specify that a screen matches an approved Figma frame at a named breakpoint, passes WCAG 2.1 AA contrast checks, or that a user can complete a specific task in a usability test without assistance. The same pass/fail logic applies.
Want a direct answer for your project?
CodeNicely builds AI products, MVPs, and custom software for founders and teams worldwide. Tell us what you're building.
Talk to our team