Software requirements documents: what to specify before you build
A requirements document is the brief every estimate, design and test is built from. This page lays out the sections one needs, what goes in each and an example line for each, from how Agnotic Technologies scopes builds with clients in discovery.
For founders, product owners and engineering leads about to brief an in-house team or a development partner.
What goes in a software requirements document?
A software requirements document states what a system must do and the conditions it must meet: purpose and scope, users and roles, user stories with acceptance criteria, data and retention, integrations, non-functional and compliance requirements, assumptions and traceability. ISO/IEC/IEEE 29148 describes this content. Agnotic Technologies writes it with clients during discovery.
Last reviewed by the Agnotic Technologies engineering team
Why do requirements documents fail the team that builds from them?
Most documents are long enough. The trouble is what they leave out, or say in a way nobody can test.
Solutions written as requirements
"Add a dropdown for status" fixes the design before anyone has said what the user needs to decide.
No acceptance criteria
A story without criteria means the developer, the tester and the client each decide separately when it is done.
Non-functional needs left to the end
Speed, uptime, accessibility and security are raised after the build, when meeting them means rework.
Integrations listed by name only
"Integrates with the EHR" hides the direction, the standard, the owner and who grants access, which is where the effort sits.
No out-of-scope list
Without it, every reader fills the gaps with their own expectations, and the scope grows quietly.
No change control
The document is right on the day it is signed and wrong a month later, because changes live in chat threads.
What do we build from a requirements document?
Agnotic Technologies writes the requirements with you in discovery, then builds the software against them, to your requirements. These are the parts we typically deliver.
Backlog with acceptance criteria
Each requirement becomes stories with testable criteria, in your tracker, ordered by release.
Traceability from requirement to test
Every requirement ID linked to the stories, code changes and tests that cover it, so gaps show before release.
Integration contracts
An interface sheet per integration and, where we own the API, an OpenAPI description agreed before coding starts.
Data inventory and retention rules
Entities, sources, owners, regulated fields and retention periods, carried into the schema and the deletion jobs.
Non-functional test suites
Load tests, accessibility checks against WCAG 2.2 and security tests that run against the stated targets.
Security requirements by level
Security requirements drawn from the OWASP ASVS at the level the product needs, and verified in testing.
Change control workflow
A change request with impact on scope, tests and release, approved before it enters the backlog.
Which sections does a requirements document need?
Ten sections, in the order we write them. Each shows what goes in it and one example line. Keep the numbering: later sections and tests refer back to it.
Purpose, scope and out of scope
Why the system exists, the problem it solves and the edge of the first release.
- The business goal and how you will know the release worked
- What is in the first release, and what is deliberately not
- Systems the product replaces or must leave untouched
Example line Out of scope for release 1: payments, a native mobile app and data migration from the old portal.
Stakeholders, users and roles
Who uses the system, who approves it and what each role may do.
- Each user group with its main goal and how often it uses the product
- Roles and the actions each may take, written as permissions
- Who signs off the requirements and who decides on changes
Example line Clinic manager: invites staff, assigns roles and sees reports for their own clinic only.
Workflows and user stories with acceptance criteria
The main journeys as steps, then stories that each pass or fail a test.
- One workflow per main journey, including the error and empty states
- Stories in the form: as a role, I need an action, so that an outcome
- Acceptance criteria as given, when, then statements a tester can run
Example line Given an expired invite link, when the user opens it, then they see a message and a button to request a new one.
Functional requirements by feature
What the system must do, grouped by feature, each with a unique ID.
- One requirement per statement, using "must" for required and "should" for preferred
- Business rules and calculations written out, with their source
- Notifications, reports and exports with who receives them and when
Example line FR-12: The system must lock an account after five failed sign-in attempts and email the account owner.
Data: entities, sources and retention
What the system stores, where each item comes from and how long it is kept.
- Main entities and their key fields, with the system of record for each
- Regulated data marked: health, payment, personal or government identifiers
- Retention and deletion rules, and any data to migrate on day one
Example line Appointment history: kept for 7 years after the last visit, then deleted by a monthly job (client's retention policy).
Integrations
One entry per interface, because this is where estimates most often go wrong.
- Direction, trigger and frequency of each exchange
- Standard or API (for example REST with OpenAPI, HL7 FHIR R4, X12 EDI) and authentication
- Who owns the other system, who grants access and where the test environment is
Example line INT-3: Send each signed order to the lab system as an HL7 v2 message within one minute; lab vendor provides test access.
Non-functional requirements
How well the system must work, named with the ISO/IEC 25010 quality characteristics so nothing is skipped.
- Performance and capacity, stated as a measurable target per key action
- Availability, backup and recovery targets
- Security, stated by OWASP ASVS level, and accessibility, stated by WCAG 2.2 level
- Supported browsers, devices and languages
Example line NFR-4: All patient-facing screens must meet WCAG 2.2 Level AA.
Compliance and regulatory constraints
The rules the product must meet, written as requirements engineers can build and test.
- Each regulation or contract clause that applies, and which feature it touches
- Audit logging, access review and data residency needs
- Evidence the client needs at release, such as test reports or a security review
Example line CMP-2: Every view of a patient record must be written to the audit log with user, record and time.
Assumptions, dependencies and constraints
What the plan relies on that the team does not control.
- Assumptions to confirm, each with an owner and a date
- Dependencies on other teams, vendors or approvals
- Fixed constraints: hosting, technology choices, budget or launch date
Example line A-5: The client's identity provider supports OpenID Connect; owner: client IT, confirm by the end of discovery.
Traceability, acceptance and change control
How each requirement is proven and how the document stays true after sign-off.
- A trace from each requirement ID to its stories and tests
- How the release is accepted, and by whom
- How a change is requested, assessed and approved, and where the history is kept
Example line Change requests are logged with their impact on scope, tests and release date, and approved by the product owner before work starts.
How do you turn a vague requirement into a testable one?
Read each requirement and ask how a tester would prove it. These examples show the rewrite; the targets in them are examples, not recommendations.
| Area | Vague | Testable rewrite |
|---|---|---|
| Performance | The app must be fast. | Search results must load within 2 seconds for 95% of requests at the stated peak load. |
| Availability | The system should always be up. | The patient portal must be available 99.9% of each calendar month, excluding announced maintenance windows. |
| Accessibility | The site must be accessible. | All public pages must meet WCAG 2.2 Level AA, checked by automated tests and a manual screen reader pass. |
| Security | Data must be secure. | The API must meet OWASP ASVS Level 2, and all stored personal data must be encrypted. |
| Integration | Sync with the CRM. | New leads must reach the CRM within 5 minutes through its REST API, with failures retried and alerted. |
| Usability | Easy to use for staff. | A new staff user must be able to book an appointment without help after the 10-minute onboarding. |
Which gaps send a build back to the start?
These are the omissions we look for first when a client brings us an existing requirements document.
- Integrations without an owner
- Nobody has confirmed who grants access to the other system, so the integration waits weeks for credentials.
- Roles without permissions
- Roles are named but nobody has said what each one may see or change.
- Missing states
- Only the happy path is described; empty, error, offline and expired states are found in testing.
- Data migration forgotten
- The old system's data has to move on day one, and nobody planned how it maps.
- Targets with no number
- "Fast" and "secure" cannot be tested, so they cannot be accepted either.
- Compliance as a footnote
- Rules are listed at the end instead of written into the features they constrain.
Trusted by global innovators
Which standards help structure the document?
Short facts from the standards bodies whose work a requirements document can cite, each linked to its primary source.
ISO/IEC/IEEE 29148:2018 specifies the processes for requirements engineering across the system and software life cycle, the information items those processes produce and the required content of those items.
Source: ISO/IEC/IEEE 29148:2018 (iso.org)ISO/IEC 25010:2023 defines a product quality model of nine characteristics, divided into subcharacteristics, that can be used to specify and evaluate requirements for software products.
Source: ISO/IEC 25010:2023 (iso.org)WCAG 2.2, a W3C Recommendation dated 12 December 2024, defines three levels of conformance: A (lowest), AA and AAA (highest).
Source: W3C, WCAG 2.2The OWASP Application Security Verification Standard provides a basis for testing web application security controls and a list of requirements for secure development; its latest stable version is 5.0.0.
Source: OWASP ASVS project
What can a requirements document not settle?
- Cost and timeline
- An estimate comes from the requirements, but this page gives no prices or durations. We size the work with you in discovery.
- Design
- Requirements say what the system must do. Screens, flows and visual design come later and are tested with users.
- Legal interpretation
- The document records the rules that apply. Whether a rule applies to your product is a question for your compliance advisers.
- Industry detail
- Some products need more, such as an EHR requirements checklist or a clinical workflow map before the stories.
Which services turn requirements into software?
Where Agnotic Technologies helps you write requirements and build against them.
- Product discovery sprintWorkshops, research and a prioritized scope before the build starts.
- Software feasibility studyChecks the assumptions behind a build before you commit to it.
- Healthcare software scope builderTurn an idea into features, users, integrations and risks in one scope.
- Accessibility engineeringWCAG 2.2 requirements built in and tested, not added at the end.
- QA and testing servicesTest plans and automation traced back to each requirement.