How to Write Acceptance Criteria for Software Development Projects
Acceptance criteria define the specific conditions your software must meet before you can consider a feature complete and ready to accept. They are the measurable checkpoints that tell your development team exactly what "done" looks like, and they protect you from vague deliverables, endless revisions, and scope disagreements.
When written well, acceptance criteria turn abstract requirements into testable conditions. When written poorly or skipped entirely, they guarantee miscommunication, rework, and budget overruns.
What Acceptance Criteria Actually Are
Acceptance criteria are a set of statements, each with a clear pass/fail result, that specify the functional and non-functional requirements of a user story or feature. They answer the question: "How will I know this feature works correctly?"
Unlike a broad project specification, acceptance criteria are feature-specific. They sit at the level of individual user stories in Agile workflows, or alongside specific deliverables in milestone-based contracts. They are written before development starts, agreed upon by both client and development team, and used during testing to verify the work.
They are not the same as a definition of done. A definition of done applies to all work (code is reviewed, tests pass, documentation is updated). Acceptance criteria are unique to each feature and describe its specific behavior.
Two Common Formats for Writing Acceptance Criteria
Most acceptance criteria follow one of two formats: scenario-based (Given/When/Then) or checklist-based. Pick the format that fits the complexity of the feature.
Scenario-Based: Given/When/Then
The Given/When/Then format is borrowed from behavior-driven development. It describes a specific scenario with context, action, and outcome. Use it for features where user interaction or system state matters.
Structure:
- Given [some context or precondition]
- When [an action is taken]
- Then [this is the expected result]
Example for a login feature:
Given a registered user is on the login page
When they enter a valid email and password and click "Log In"
Then they are redirected to the dashboard within 2 seconds
Given a user enters an incorrect password
When they click "Log In"
Then they see the error message "Invalid email or password" and remain on the login page
Given a user has failed login attempts 5 times in 10 minutes
When they attempt a 6th login
Then their account is locked for 15 minutes and they see "Too many failed attempts. Try again in 15 minutes."
This format forces specificity. It clarifies what state the system should be in, what the user does, and what happens as a result. It is also directly translatable into automated tests.
Checklist-Based
A checklist format works well for simpler features or configuration tasks where scenarios are less relevant. It is just a bulleted list of conditions that must all be true.
Example for an export feature:
- User can export transaction history as a CSV file
- CSV includes columns: Date, Description, Amount, Status
- CSV filename format is
transactions_YYYY-MM-DD.csv - Export includes only transactions from the selected date range
- Export completes within 10 seconds for up to 10,000 rows
- User sees a success message after download starts
Each item is binary: it either works or it does not. Checklist format is faster to write, but it does not capture edge cases or workflows as clearly as Given/When/Then.
What Makes Acceptance Criteria Effective
Good acceptance criteria share these qualities:
Clear and testable. Each criterion must have an obvious pass or fail outcome. Avoid vague language like "user-friendly" or "fast." Instead, specify "page loads in under 3 seconds" or "form has inline validation messages."
Written from the user's perspective. Describe what the user experiences, not how the system is built. "User sees their profile picture" is better than "ProfileImage component renders correctly."
Agreed on before development starts. Acceptance criteria are a contract. If they are written after the feature is already built, they are documentation, not criteria. Lock them in during discovery or sprint planning.
Scoped to one feature. Do not mix multiple features into one set of criteria. Each user story or task should have its own discrete set.
Include edge cases and error states. Happy-path scenarios are not enough. Cover what happens when a user enters invalid data, loses connection, or tries something unexpected.
Common Mistakes When Writing Acceptance Criteria
Being too vague. "The payment system should work correctly" is not a criterion. "User can pay with Visa, Mastercard, or American Express, and receives an email confirmation within 1 minute" is.
Skipping non-functional requirements. Performance, security, and accessibility matter. Include criteria like "API responds in under 500ms" or "all form fields are keyboard-navigable."
Writing them after the fact. If acceptance criteria are written after development is underway, they cannot guide the work. They become a rubber stamp, not a specification.
Not involving the development team. Acceptance criteria should be a conversation between client and builder. The team can spot ambiguity, technical constraints, or missing scenarios you might not anticipate.
Overloading a single feature. If your acceptance criteria list is 20 items long, the feature is probably too big. Break it into smaller stories.
Who Should Write Acceptance Criteria?
In an Agile team, the product owner typically writes the first draft, often with input from stakeholders or the client. The development team then reviews and refines them during backlog grooming or sprint planning. Both sides must agree before the work begins.
When working with an agency, you (the client) may draft acceptance criteria based on your business requirements, or the agency may propose them during the discovery phase based on your goals. Either way, final criteria should be explicitly agreed upon and documented in your project tracker or contract.
How Acceptance Criteria Fit Into Your Contract
If your contract includes milestone-based payments or a formal acceptance process, acceptance criteria become the basis for that acceptance. When the agency says a milestone is complete, you test it against the agreed criteria. If all criteria pass, you approve the milestone. If they do not, the work is not done.
This makes acceptance criteria a risk management tool. They remove subjectivity from "done" and give both parties a shared, objective standard.
For time-and-materials contracts, acceptance criteria still matter. They keep sprints focused and prevent drift. Even if you are not gating payment on acceptance, you are still gating progress and prioritization.
Acceptance Criteria and Change Requests
Acceptance criteria also clarify what counts as a change request. If a feature behaves exactly as the agreed criteria describe, asking for different behavior is a change, not a bug. If it does not meet the criteria, it is incomplete work, not a change.
This distinction matters for budget and timeline. Clear criteria protect both sides: the client knows what they are getting, and the agency knows when the scope is expanding.
A Practical Example: Password Reset Feature
Here is how acceptance criteria might look for a password reset feature, using the Given/When/Then format:
Given a user clicks "Forgot Password" on the login page
When they enter a registered email address and click "Send Reset Link"
Then they see the message "If that email is registered, you will receive a reset link within 5 minutes"
Given a user receives a password reset email
When they click the reset link within 1 hour
Then they are taken to a page where they can enter a new password
Given a user enters a new password that meets requirements (8+ characters, 1 uppercase, 1 number)
When they click "Reset Password"
Then their password is updated and they are redirected to the login page with the message "Password updated successfully"
Given a user clicks a reset link that is more than 1 hour old
When the page loads
Then they see "This reset link has expired. Please request a new one."
Given a user enters a new password that does not meet requirements
When they try to submit
Then they see inline validation errors listing which requirements are not met
Notice how each scenario is specific, testable, and covers both success and failure cases. A QA tester or client can run through these scenarios and verify the feature works as agreed.
Start With Acceptance Criteria, Not After
The best time to write acceptance criteria is during planning, before any code is written. If you are hiring an agency, ask them how they handle acceptance criteria. Do they write them? Do they expect you to? How are they documented and tracked?
Good agencies will propose acceptance criteria as part of discovery or sprint planning. If an agency hands you user stories without acceptance criteria, that is a warning sign. It means "done" will be defined retroactively, which is a recipe for conflict.
If you are defining your own, start simple. Pick one feature, write 3 to 5 criteria, and test them against the "can I pass or fail this?" standard. Refine from there.
Acceptance criteria are not bureaucracy. They are clarity. They turn "build me a login system" into a testable, unambiguous contract that protects your time, your budget, and your product.
If you are scoping a software project and want help structuring requirements, acceptance criteria, and delivery milestones, Stardelite works with clients to define clear, testable specifications before development begins.