Requirements specification (PRD or SRS)
- Status
- Approved
- Version
- 1.0.0
- Authority
- Recommended practice
- Applies to
- Core
Summary
A requirements specification is the one written statement of what a product must do and how well, agreed before it is built. Call it a PRD (product requirements document) when it is written from the product side and an SRS (software requirements specification) when it is written for engineers; the discipline is the same. A good specification is short enough to be read, precise enough to be tested, and tied together by stable ids: every requirement traces back to a vision outcome or scenario and forward to the acceptance criteria and tests that prove it.
Rules
- R1. A product MUST have one requirements specification, stored in the project repository under version control, as the authoritative statement of its requirements. Blueprints, roadmaps, issues and tests MUST refer to requirements by id and MUST NOT restate them.
- R2. The specification MUST contain at least: the problem, the scenarios, the functional requirements, the quality (non-functional) requirements, the acceptance criteria, the constraints and assumptions, and the out-of-scope list. It SHOULD also list open questions.
- R3. Every scenario, requirement and acceptance criterion MUST have a unique id with a prefix that shows
its kind (for example
S-A,FR-1,NFR-1,AC-1). Ids MUST NOT be renumbered or reused; a withdrawn requirement keeps its id and is marked withdrawn with the date and the reason. - R4. A requirement MUST state exactly one need. A statement that joins two independently testable behaviours MUST be split into two requirements.
- R5. A requirement MUST be verifiable by test, inspection, demonstration or analysis. A quality requirement MUST give a measurable target and the condition under which it is measured.
- R6. Requirements MUST NOT use unmeasurable words such as “fast”, “easy”, “user-friendly”, “flexible”, “robust”, “as appropriate”, “etc.” or “and/or”. Rewrite the statement with a measurable term, or move the aim to the vision.
- R7. A requirement MUST say what is needed, not how it is built. A technology or design choice MAY appear as a constraint only with its source or reason; otherwise it belongs in the blueprint and its decision records.
- R8. The specification MUST state which keyword convention it uses (RFC 2119 as clarified by RFC 8174, or a sentence template such as EARS), and every requirement MUST follow it.
- R9. Every requirement MUST trace back to its source (a vision outcome, a scenario, a stakeholder need or a constraint) and forward to at least one acceptance criterion. Later artefacts that implement or verify a requirement MUST cite its id, so that a text search for the id finds them all.
- R10. Each assumption MUST name how and by when it will be checked. Each open question MUST name who answers it.
- R11. The set of requirements MUST be consistent. Two requirements that contradict each other MUST be resolved, or recorded as an open question with an owner, before the specification is approved.
- R12. The specification MUST be reviewed by someone other than its author and approved by the person who owns the product before work that depends on it begins. The status and the date of approval MUST be recorded in the document; an author MUST NOT approve its own specification.
- R13. A change to an approved requirement MUST be made as a reviewed change to the specification, and every artefact that depends on the requirement MUST be checked in the same or a linked change.
- R14. Terms with a specific meaning in the product SHOULD be defined once, in a glossary the specification
links to. Scenarios SHOULD be written end to end, with actor, inputs and result, and requirements SHOULD be
prioritised (see
req.scope-and-mvp).
Guidance
- PRD, SRS and the standard’s names. ISO/IEC/IEEE 29148 separates stakeholder requirements (what the
people involved need), system requirements and software requirements. In a small product one document covers
all three levels; keep the sections apart so a reader can tell a need from a technical requirement. The Hub
template is
templates/prd.md; copy it toproject/PRD.md. - Agile does not mean undocumented. Atlassian’s guidance on PRDs stresses shared understanding, goals, user stories and a clear out-of-scope list, kept short and updated as the team learns. A specification in a repository under review fits that: it is a living file, not a signed-off binder.
- One sentence per requirement. A sentence template removes ambiguity. EARS has five patterns: always
active (
The <system> shall <response>), state-driven (While <state>, …), event-driven (When <trigger>, …), optional feature (Where <feature is included>, …) and unwanted behaviour (If <trigger>, then …). RFC 2119 keywords with a short sentence are enough for many teams. Pick one. - Measurable quality. “Fast” becomes “the product page loads in under 2 s at the 95th percentile on a mid-range phone over a 4G connection, measured by (tool)”. Name the tool or the check, so that the acceptance criterion can be written from the requirement alone.
- Traceability in practice. Cite ids where people already look: the issue title or body, the pull request
description, the test name or comment, the blueprint section. Then
grep FR-3shows the reason, the design, the work and the proof. A spreadsheet matrix that nobody updates is worse than ids in the places the work happens. - Review checklist. Is each requirement singular, verifiable and free of vague words? Does each have an id, a source and a criterion? Does each vision outcome have at least one scenario or requirement? Do any two requirements conflict? Is the out-of-scope list present? Is every assumption checkable?
- Working with agents. Give an agent the specification’s ids, not a summary. Ask it to cite ids in commits and pull requests, and to raise a question instead of inventing a requirement when the text is silent.
- When not to apply. A bug fix or a small change to a product whose specification is approved needs an issue with acceptance criteria and, where a requirement changes, a reviewed edit of the specification.
Explanation
The IREB glossary defines a requirements specification as a systematically represented collection of requirements that satisfies given criteria, and defines traceability as the ability to follow a requirement back to its origins and forward to its implementation, design and tests. Those two ideas carry the rules: a specification is useful only if its parts can be checked, and a requirement is useful only if its reason and its proof can be found.
ISO/IEC/IEEE 29148 lists characteristics of a good individual requirement, among them necessary, unambiguous, singular, feasible and verifiable, and characteristics of a good set, such as complete and consistent. R4 to R7 and R11 apply those to a small written specification. Wiegers and Beatty set out the same discipline for practice: a requirement is a statement that can be tested, kept apart from design, and traced to the need that caused it. SWEBOK v4 treats elicitation, analysis, specification and validation of requirements as one cycle, which is why approval (R12) and controlled change (R13) are part of the standard and not afterthoughts.
Stable ids make the rest cheap. When a requirement keeps its id for the life of the product, an issue, a test and a decision record can all point at it without a document-wide update, and a reviewer can answer “why does this exist?” with one search.
Examples
Good — singular, verifiable, with ids, a source and a criterion:
| ID | Requirement | Source ||------|----------------------------------------------------------------------------------------|--------|| FR-4 | When a visitor submits the search form, the site MUST show matching items, best first. | S-B || FR-5 | The site MUST show at most 20 search results per page. | S-B || NFR-2 | The search results page MUST load in under 1.5 s at the 95th percentile, measured by the weekly synthetic check on staging. | Outcome 2 |
- [ ] AC-4 Searching for a known title returns it as the first result (FR-4).- [ ] AC-5 A search with more than 20 hits shows 20 and a link to the next page (FR-5).Bad — several needs in one line, vague words, a design choice, no id:
The search should be fast and user-friendly, show relevant results and filters, and use Elasticsearch.Sources
- SWEBOK Guide v4.0 — IEEE Computer Society, all rights reserved; Software Requirements knowledge area, summarised. Accessed 2026-11-20.
- IREB CPRE Glossary — © IREB, all rights reserved; the definitions of requirements specification and traceability are paraphrased. Accessed 2026-11-20.
- Karl Wiegers and Joy Beatty, Software Requirements, 3rd edition — Microsoft Press, all rights reserved; summarised, not copied. Accessed 2026-11-20.
- Atlassian, “How to create a product requirements document (PRD)” — all rights reserved; the content of an agile PRD, summarised. Accessed 2026-11-20.
- Alistair Mavin, “EARS: Easy Approach to Requirements Syntax” — all rights reserved; the five sentence patterns are summarised, not copied. Accessed 2026-11-20.
- ISO/IEC/IEEE 29148:2018, Systems and software engineering — Life cycle processes — Requirements engineering; RFC 2119 and RFC 8174 (IETF, keywords for requirement levels) — referenced by name only.