How to Write Requirements for Developers
To write product requirements a developer can actually build from, describe the problem before the solution, define what success looks like, break the product into user stories, give every story acceptance criteria, and list what is out of scope. One to three clear pages beat a 40-page specification. This guide is for non-technical founders and product owners briefing a freelancer, an agency or a first hire, and it ends with a template you can copy.
As a product owner on a white-label food delivery SaaS, I wrote requirements that developers had to turn into working features for several businesses at once. The pattern below is what consistently produced the right thing on the first build instead of the third.
Why Do Developers Build the Wrong Thing?
Developers rarely build the wrong thing because they are careless. They build it because the requirements left gaps, and they filled those gaps with reasonable guesses.
The three most common gaps are:
- A solution without the problem. "Add a dashboard" says what to build but not why. A dashboard for an investor update and a dashboard for daily operations are completely different products.
- No definition of done. "Users can reset their password" leaves open whether the link expires, whether old sessions are logged out and what happens with an unknown email address.
- Unstated scope. If you do not say what is out, everything you mentioned once in a call might be assumed to be in.
This is the same gap I described in Developers Are Great at HOW. But What About WHY and WHAT?: good requirements hand the developer the WHY and the WHAT, so their skill goes into the HOW.
What Should a Requirements Document Include?
A requirements document for an MVP needs six parts:
| Part | What it answers | Typical length |
|---|---|---|
| Problem statement | Who has what problem, and how do they handle it today? | One paragraph |
| Success criteria | How will you know the product works? | Three to five measurable points |
| Users and roles | Who uses it, and what can each role do? | A short list |
| User stories | What does each user need to do? | One line each |
| Acceptance criteria | When is each story done? | Three to six checks per story |
| Out of scope and constraints | What will not be built, and what limits apply? | A short list |
Notice what is missing: database choices, frameworks and screen-by-screen pixel layouts. Those are decisions for the developer, informed by your constraints.
How Do You Write the Problem Statement?
Write one paragraph that names the user, their problem and what they do about it today. Avoid describing features here.
Weak: "We need an app with booking, payments and notifications."
Strong: "Independent yoga teachers manage class bookings through WhatsApp messages and a spreadsheet. They lose bookings when messages get buried, and chasing payments takes about three hours a week. We want teachers to publish a schedule, let students book and pay in one step, and see who is coming to each class."
The strong version tells the developer what matters (missed bookings, payment chasing, attendance) and gives them room to propose the simplest way to solve it.
How Do You Define Success?
List three to five outcomes you can check after launch. They keep the build focused and give you a way to judge whether it worked.
- A student can find a class and book it in under one minute.
- A teacher can publish a weekly schedule in under five minutes.
- 80% of bookings are paid at the time of booking.
- Teachers no longer need WhatsApp to track who is attending.
When a feature request comes up mid-build, ask whether it moves one of these. If not, it waits.
How Do You Write User Stories?
A user story describes one thing one type of user needs to do, and why:
As a [type of user], I want to [do something] so that [outcome].
Examples:
- As a student, I want to see this week's classes with open spots so that I can choose one that fits my schedule.
- As a student, I want to pay when I book so that my spot is confirmed.
- As a teacher, I want to see who has booked each class so that I know how many people to expect.
- As a teacher, I want to cancel a class and notify everyone booked so that students are not left waiting.
Keep each story small enough that a developer could build it in a few days. If a story needs a paragraph to explain, split it.
How Do You Write Acceptance Criteria?
Acceptance criteria are the testable conditions that must be true for a story to count as done. They are where most misunderstandings are prevented.
For story 4 above:
- The teacher can cancel any future class from the class page.
- Every student booked on that class receives an email within five minutes.
- Students who paid are refunded automatically, and the email says so.
- The cancelled class no longer appears in the student schedule.
- A class cannot be cancelled after it has started.
A useful format for trickier cases is Given / When / Then:
Given a class that starts in two hours, when a student tries to cancel their booking, then they see a message that cancellations close 12 hours before class, and the booking stays.
Write criteria for the unhappy paths too: wrong input, missing data, an expired link, a payment that fails. That is where guesses usually go wrong.
What Should Be Out of Scope?
Write an explicit list of what the first version will not include:
- No mobile app; a mobile-friendly website only.
- No subscriptions or class packs; single-class payments only.
- No multi-teacher studios; one teacher per account.
- No in-app chat.
This list protects your budget more than any other part of the document. It also makes conversations easier: when a new idea comes up, you add it to the list for later instead of arguing about it.
Which Constraints Should You Share?
Share anything that limits the solution, even if it seems obvious to you:
- Budget and deadline, including any fixed launch date.
- Systems it must connect to, such as an existing website, a payment provider or a CRM.
- Data rules, such as where data must be stored or what you are not allowed to collect.
- Who maintains it later, because that affects the right technology choice.
Leave the technology decision to the developer unless one of these constraints forces it. If you are unsure whether the developer's proposal is sound, that is a good moment for a short build vs buy check or an outside opinion.
A Requirements Template You Can Copy
1. Problem Who has the problem, what it is, how they handle it today. (One paragraph) 2. Success criteria 3–5 measurable outcomes we will check after launch. 3. Users and roles Each type of user and what they are allowed to do. 4. User stories As a [user], I want to [action] so that [outcome]. 5. Acceptance criteria (per story) - Testable condition - Testable condition - Given / When / Then for edge cases 6. Out of scope (version 1) - Explicitly excluded item 7. Constraints Budget, deadline, integrations, data rules, who maintains it. 8. Open questions Anything you have not decided yet, so the developer can flag it.
How Do You Use the Document With Your Developer?
Send it before the first technical call, and ask the developer to come back with questions, not just an estimate. Good developers will find gaps you missed; that is a sign of a careful partner, not a difficult one. When hiring your first developer, how a candidate responds to your requirements is one of the best signals you will get.
If you are working with an agency, the same document makes their proposals comparable, and it pairs well with these questions to ask a dev agency before signing. For AI features specifically, add what the model should do when it is unsure, which I cover in what an AI MVP actually looks like.
Requirements are a living document. Update them when you learn something, keep the out-of-scope list growing, and treat every "that is not what I meant" as a missing acceptance criterion to add next time.
Frequently Asked Questions
What should product requirements for a developer include? The problem and who has it, measurable success criteria, user flows written as user stories, acceptance criteria for each story, and an explicit out-of-scope list. Add constraints such as budget, deadline, integrations and data rules.
How long should a requirements document be? For an MVP, one to three pages is usually enough. A one-page brief plus user stories with acceptance criteria beats a long specification nobody reads. A document that keeps growing usually means the scope is too large for a first version.
What is the difference between a user story and acceptance criteria? A user story describes what someone wants to do and why. Acceptance criteria are the specific, testable conditions that must be true for that story to count as done. The story gives direction; the criteria define finished.
Should a non-technical founder specify the tech stack? Usually not. Describe the problem, users, constraints and required integrations, and let the developer propose the stack with reasons. Specify technology only when a real constraint forces it.
Why do developers keep building the wrong thing? Usually because the requirements described a solution without the problem, left out edge cases, or never defined done. Writing the problem first and adding acceptance criteria to every story removes most of the guesswork.