Quick summary
How to write software requirements: for each feature, write who it is for, what they need to do and why, then list the checks that prove it works. Add the business rules, the edge cases and what is out of scope. Leave the technical choices to the developer.
The format that works: a user story ("As a team admin, I want to invite a colleague by email so that they can see our account") followed by acceptance criteria ("Given..., When..., Then..."). There is a worked example and a template to copy below.
How much detail: it depends on how you pay. A fixed price quote needs every screen and rule up front. Hourly or subscription work needs one clear request at a time, written just before it is built.
How to Write Software Requirements at a Glance
| Part | What it answers | Example |
|---|---|---|
| Problem and goal | Why are we building this, and for whom? | "Admins can't add colleagues, so accounts stay single-user and teams churn" |
| Users and roles | Who uses it, and what can each type do? | Account owner, admin, member |
| User stories | What does each user need to do, and why? | "As an admin, I want to invite a colleague by email so that they can see our account" |
| Acceptance criteria | How will we know it works? | "Given I am an admin, When I invite an email address, Then that person gets an invite within a minute" |
| Rules and edge cases | What happens in the unusual cases? | Invites expire after 7 days; an existing user is added without a second account |
| Non-functional needs | How fast, how safe, on which devices? | Works on the latest Chrome, Safari and Edge; members never see billing |
| Out of scope | What are we not building now? | No bulk invites from a spreadsheet in this version |
Before you send requirements to a developer, check these four things:
- Check 1, "Could two people read this the same way?" Words like "fast", "simple" and "user-friendly" mean something different to everyone. Replace them with something you can test.
- Check 2, "Does every feature have acceptance criteria?" If you cannot say how you will check it, the developer is guessing, and you will argue about whether it is done.
- Check 3, "Have I said what is out of scope?" A short "not in this version" list prevents more disagreements than any other section.
- Check 4, "Is each requirement one thing?" "Users can invite colleagues and manage billing" is two requirements. Split it so each can be built, tested and accepted on its own.
Have a list of things to build and no one to build them?
A senior developer on subscription: $2,995 a month, as many requests as you like, each shipped within 2 business days, and your money back if the first 14 days don’t prove it.
In this article
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
This guide is for founders who need to tell a developer or agency what to build. It is written for business owners, not engineers, so it skips the 40-page formal specification and covers what a developer actually needs from you. If you are still deciding who to hire, see how to choose a software development company.
What Software Requirements Are
Software requirements are a written description of what the software must do and how well it must do it. They are the agreement between you and whoever builds it. Developers, testers and, if things go wrong, lawyers all read them.
They come in two kinds:
- Functional requirements say what the software does. "A user can reset their password by email." "An admin can export all invoices as a spreadsheet."
- Non-functional requirements say how well it must do it. How fast pages load, how data is protected, how many people can use it at once, and which browsers and devices it must support.
Most founders write the first kind and forget the second. The second kind is where unpleasant surprises come from, such as an app that works on a laptop and breaks on a phone.
The international standard for requirements, ISO/IEC/IEEE 29148, lists the qualities a good requirement should have. In plain terms: it is needed, it is clear enough that only one reading is possible, it is complete, it covers one thing, it can be built, and it can be checked. You do not need to read the standard. If each line you write passes "one thing, one meaning, and testable", you are most of the way there.
Why Requirements Decide How a Project Goes
PMI, the Project Management Institute, found that nearly half of unsuccessful projects missed their goals because of inaccurate requirements management. Estimates suffer too. Steve McConnell's "cone of uncertainty" puts estimates made at the idea stage anywhere from a quarter of the real effort to four times it, and the range only narrows as requirements get written and decisions get made. Clear requirements are the cheapest way to get a quote you can trust.
How to Write Software Requirements, Step by Step
- 1
1. Start with the problem, not the feature
Write two or three sentences on what is wrong today, who it affects and what changes when it is fixed. "Customers keep asking for X" is a good start. The developer may know a simpler way to solve the problem than the feature you had in mind, but only if you tell them the problem.
- 2
2. List the types of users
Name each kind of person who will use the feature and what they are allowed to do: an account owner, an admin, a regular member, a customer who is not logged in. Many bugs and security holes come from rules about who can see what that nobody wrote down.
- 3
3. Write each feature as a user story
Use the form "As a (type of user), I want (to do something) so that (reason)." The Agile Alliance calls this template "training wheels": it makes you say who the feature is for and why, not just what it does. One story per thing a user needs to do.
- 4
4. Add acceptance criteria to every story
These are the checks that prove the feature works. Write them as Given (the starting situation), When (what the user does), Then (what should happen). Cucumber, the testing tool that popularized this format, recommends three to five steps per example. Aim for a handful of criteria per story, including at least one where something goes wrong.
- 5
5. Write down the rules and edge cases
What happens if someone is invited twice? If the invite expires? If the person already has an account? If the payment fails halfway? These are the questions a developer will otherwise answer for you, and the answer may not be the one you wanted.
- 6
6. Add the non-functional needs
Which browsers and devices it must work on, any speed you need ("search results in under two seconds"), what data must be protected and who must never see it, and which other systems it connects to, such as Stripe or your email provider.
- 7
7. Mark priorities and what is out of scope
Label each story Must Have, Should Have, Could Have or Won't Have this time. That is the MoSCoW method from DSDM, where the Must Haves are the smallest set that is still usable. Then list what you are deliberately not building now.
- 8
8. Review it with the developer before work starts
Ask them to read it and send back every question they have. Each question is a gap you just closed for free. If they have no questions at all about something non-trivial, be wary: they may be filling the gaps with guesses.
A Software Requirements Example
Here is one feature, written the way a developer can build and test it. Say you run a SaaS product that only allows one login per account, and customers want to add their colleagues.
Problem. Every account has one login, so customers share passwords or leave. Three of our largest customers asked for team access this quarter.
User story. As an account admin, I want to invite a colleague by email so that they can use our account with their own login.
Acceptance criteria:
- Criterion 1: Given I am an admin, When I enter a colleague's email and click Invite, Then they receive an invite email within one minute.
- Criterion 2: Given I have received an invite, When I click the link and set a password, Then I am logged in to that account as a member.
- Criterion 3: Given an invite is more than 7 days old, When someone clicks the link, Then they see "This invite has expired" and a button to ask for a new one.
- Criterion 4: Given I am a member, not an admin, When I open the team page, Then I can see the team but cannot invite or remove anyone.
Rules and edge cases:
- Inviting an email that already belongs to a user adds them to this account. It never creates a second login.
- Inviting the same email twice resends the invite rather than sending two.
- Only admins can see billing. Members cannot.
Non-functional needs. Works on the latest versions of Chrome, Safari and Edge, on a phone and a laptop. The invite link works once and only for the email it was sent to.
Out of scope for this version. Bulk invites from a spreadsheet, custom roles beyond admin and member, and single sign-on.
Priority. Must Have.
That is one page, and a developer can estimate it, build it and show you each criterion working. Notice what it does not say: which database table to use, which email service, how the code is organized. Those are the developer's decisions.
Software Requirements Template
Copy these sections into a document, one page per feature, or one document for a small project.
| Section | What to write | Keep it to |
|---|---|---|
| Problem | What is wrong today, who it affects, what changes when it is fixed | 2 or 3 sentences |
| Users | Each type of user and what they can and cannot do | A short list |
| User stories | "As a..., I want... so that..." for each thing a user needs to do | One line each |
| Acceptance criteria | Given, When, Then checks for each story, including a failure case | 3 to 6 per story |
| Rules and edge cases | Duplicates, expiry, limits, failures, what happens to existing data | A short list |
| Non-functional needs | Devices and browsers, speed, security, privacy, connected systems | A short list |
| Out of scope | What you are deliberately not building now | A short list |
| Priority | Must, Should, Could or Won't Have this time | One word per story |
| Open questions | Anything you have not decided yet | As many as you have |
Add designs if you have them. A rough sketch on paper, photographed, answers more layout questions than a page of description. Screenshots of a product that does something similar help too.
Good vs Bad Requirements
| Vague | Testable |
|---|---|
| The app should be fast | The dashboard loads in under 3 seconds with a year of data |
| Users can manage their team | Admins can invite and remove members; members can only view the team list |
| Make the signup simple | Signup needs only an email and a password; email confirmation can happen later |
| It should be secure | Members never see billing; each customer only ever sees their own account's data |
| Integrate with Stripe | When a payment fails, the account is marked past due and the admin gets an email |
| Works on mobile | Every page works in Safari on an iPhone and Chrome on Android, with no sideways scrolling |
Common Mistakes
- Writing the solution instead of the need. "Add a dropdown with all customers" may be the wrong answer to "I need to find a customer quickly." Describe the need and let the developer suggest the best way.
- Describing the happy path only. Most of the work, and most of the bugs, are in what happens when things go wrong.
- Leaving permissions unstated. Who can see and change what is the rule people forget most, and it is a security issue. Access control is the top risk in the 2025 OWASP Top 10, covered in our guide to code audit services.
- Writing everything up front for a product that will change. A long specification written months ahead goes stale. Write the detail just before each piece is built.
- No priorities. If everything is a Must Have, nothing is, and the first thing cut when time runs out may be the one you cared about most.
- Skipping the review. A requirement the developer has not questioned is one they may have read differently from you.
How Much Detail You Need Depends on How You Pay
| How you buy development | What you need written | When |
|---|---|---|
| Fixed price project | Every screen, rule and edge case, with acceptance criteria for each milestone | All of it before the quote |
| Time and materials (hourly) | A prioritized list of user stories, with detail for the next few | Detail shortly before each is built |
| Development subscription | One clear request at a time, with its acceptance criteria | Just before it goes into the queue |
| In-house developer | A prioritized backlog and regular conversations | Ongoing |
With a fixed price, the price is only fixed for the scope on paper, so anything missing becomes a paid change. Our guide to fixed price software development covers that trade-off, and software development contracts covers putting the scope and acceptance criteria into the contract. If you pay by the hour or by the month, you can write requirements one feature at a time, and each one can learn from what shipped before it.
How StackTie Fits
StackTie is a development subscription. You write requests in plain English on your own Trello board, they are worked one at a time in the order you set, and each one comes back in days as a pull request with a plain-English summary of what changed. You do not need a full specification to start: a request written like the example above is ideal, and a rougher one is fine, because we ask about anything unclear before building, and big requests are split into smaller pieces that each ship on their own. When you subscribe, a pinned card asks four quick questions (what the product does, your stack, where it runs and your top three priorities) so the first request starts with context. One senior developer, Michael, leads every build, and everything we build belongs to your company. There is a money-back guarantee if it is not a fit. The subscription is not for native iOS or Android apps or a whole team working in parallel. The price and what is included are on the homepage.
