In short: The structure follows the accepted layout of requirements documents (IEEE 830 and ISO/IEC/IEEE 29148): introduction and scope, overall description, specific requirements, and verification. We add three things that real projects most often lack: a roles and permissions table, a list of what is out of scope, and acceptance criteria for every requirement in a testable form. A specification without acceptance criteria is a statement of intent, not a specification.
The structure
| # | Section | What goes in it |
|---|
| 1 | Purpose and scope | The business problem in a sentence or two, who the users are, what this version includes, and what it does not |
| 2 | Terms | Every business term in the document, each with a single definition. If the team uses two names for the same thing, choose one here. |
| 3 | Users and roles | A table: role, what it can see, what it can change, and what it may not do |
| 4 | Processes | The main business processes, step by step, including what happens when something goes wrong |
| 5 | Functional requirements | A user story for each capability, and acceptance criteria for each story |
| 6 | Data model | Entities, important fields, relations, and which system is the source of each field |
| 7 | Integrations | External systems, what passes, in which direction, and what happens when they are unavailable |
| 8 | Non-functional requirements | Performance, availability, security, privacy, accessibility, and languages |
| 9 | Verification | How each requirement is checked: scenarios, test data, who signs off |
| 10 | Appendices | Sample screens, existing reports, and sample files |
Section 1: what is out of scope
The list of what is out of scope matters as much as the list of what is in. Without it each side fills the gap with its own expectation: the client assumes there is an app, the developer assumes there is only a website. A short list of what this version does not include removes most of the arguments at the end of a project.
Section 3: roles and permissions
This is the section most specifications skip, and it is exactly where vulnerabilities are born. A sample structure:
| Role | Sees | Changes | Forbidden |
|---|
| Customer | Their own orders | Their own details | Viewing other customers' orders |
| Support agent | Their customers' orders | Order status | Deleting an order, changing a price |
| Manager | Everything | Everything except payment history | Changing a completed payment |
For every row in the forbidden column, write a test scenario in section 9. Without a scenario, there is no way to know whether the restriction actually works.
Section 5: requirements you can test
Each requirement is written as a user story and as an acceptance criterion. The common form is: given a state, when an action happens, then the system responds like this.
Example. Given a signed-in customer with two open orders, when they open the orders list, then they see only their own two orders, newest first.
The system shall be user friendly is not a requirement, because it cannot be tested. An order can be submitted in no more than three taps from the home screen is a requirement.
Section 8: what gets forgotten for Israel
- Hebrew and right-to-left text, including fields that mix Hebrew and English, and numbers within Hebrew text.
- The Israeli ID number with its check digit, and the VAT dealer number.
- VAT and invoices, including the allocation number (מספר הקצאה) on invoices above the threshold.
- A Sunday to Thursday work week and holidays, if the system has times, queues or shifts.
- Amendment 13 to the Privacy Protection Law: which personal data is kept, who can access it, and how access is logged.
- Accessibility under the Israeli standard, if the system is public-facing.
How to use the template
- Start with sections 1 and 3: what we build, what we do not, and who may do what.
- Write the processes before the requirements. Requirements written without a process describe screens, not work.
- Add the acceptance criterion to each requirement immediately, not at the end.
- Check the data model against the reports the business needs: every report should follow from the data being kept.
If development uses AI tools, the same document works as the tool's specification. Just make sure it is explicit about everything a person would normally infer from context.
Frequently asked questions
What should a software specification contain?
Purpose and scope, terms, users and roles with permissions, processes, functional requirements with acceptance criteria, a data model, integrations, non-functional requirements, and a verification plan.
What is the difference between a specification and a requirements document?
In everyday practice, they are usually the same document. Standards distinguish between business requirements, system requirements, and a software specification, but for a mid-sized project one well-structured document is enough.
How long should a specification be?
Long enough for a developer to build without guessing and a client to check without arguing. The page count matters less than every requirement having an acceptance criterion and the permissions being written down.
What is the most common mistake in specifications?
Requirements that cannot be tested, no list of what is out of scope, and no permissions table. All three surface only at the end of the project, when fixing them costs the most.
Can this specification be used with AI coding tools?
Yes. A document with scope, acceptance criteria, a data model, and permissions is exactly what tools like Claude Code and Lovable need, so they do not fill gaps with guesses.
Where to start
Fill in sections 1 and 3 yourself: what we build, what we do not, and who may do what. Send them to me and we will continue from there to processes and requirements.
Talk to me
Related: CRM requirements and development, Specifications before building with AI, Architecture review