Writing Good Requirements: A Step-by-Step Guide

Contributor
Mar 27
5 min read

A good requirement is a statement about what the system should do, written so that engineers can build it, testers can verify it, and stakeholders can agree it captures their needs. Most requirements fall short in at least one of these. The result is rework, dispute, and feature drift.

This guide is a step-by-step approach to writing requirements that work.

What a Good Requirement Looks Like

A good requirement is:

Necessary: removing it makes the system meaningfully worse
Unambiguous: only one reasonable interpretation
Testable: there's a clear way to verify it's met
Complete: doesn't depend on missing context
Consistent: doesn't contradict other requirements
Atomic: one thing, not a paragraph

Few requirements are written this way naturally. The discipline produces them.

The Statement Form

A working form for functional requirements:

The system shall [action] [object] [conditions].

Examples:

"The system shall allow administrators to invite new users via email."
"The system shall return checkout results within 2 seconds at p95 latency."
"The system shall encrypt all customer data at rest using AES-256."

The "shall" is conventional and serves a purpose: it distinguishes requirements (binding) from descriptions or aspirations.

Step 1: Identify the Need

Start with the need, not the feature.

Bad: "We need a search feature."

Better: "Users with more than 50 items need to find specific items quickly."

The need is what justifies the requirement. The feature is one way to meet it.

Going to features too quickly locks in a solution before exploring alternatives.

Step 2: Identify the Actor

Who or what does the action?

Users (with specific roles: admin, member, guest)
The system itself (background processes)
External systems (integrations)

Be specific. "Users" might hide important distinctions. "Admin users with billing permissions" is sharper.

Step 3: Identify the Action

What does the actor do?

Be specific:

Bad: "manage users"
Better: "invite, edit, deactivate, and view users"

"Manage" is a placeholder. Breaking it into specific actions surfaces the actual scope.

Step 4: Identify Conditions

Under what circumstances does the requirement apply?

"When the user is signed in..."
"If the workspace has billing enabled..."
"For users with admin role..."

Conditions distinguish required behavior from default behavior. They also clarify edge cases.

Step 5: Make It Testable

A requirement is testable when you can answer: "how would I verify this was met?"

Bad: "The system shall be fast." How fast? Measured how? Under what conditions?

Better: "The system shall respond to user requests within 500ms at p95 under normal load."

The specifics let testers write tests, engineers know the bar, and stakeholders verify agreement.

Step 6: Check for Ambiguity

After writing, look for ambiguous words. The classic offenders:

"User-friendly": by what measure?
"Quickly": quantify it
"Easily": how?
"Reasonable": to whom?
"Robust": under what conditions?
"Properly": by what standard?
"As needed": by whom, when?

Each ambiguous word is a future debate. Replace with specifics or remove.

Functional vs. Non-Functional

Functional requirements: what the system does.

"The system shall allow users to upload files up to 100MB."

Non-functional requirements: how well the system does it.

"The system shall maintain 99.9% uptime, measured monthly."

Both are real requirements. Teams often over-invest in functional and under-invest in non-functional. The non-functional requirements (performance, reliability, security, accessibility) are often what make or break the product.

Each category typically warrants explicit requirements rather than being assumed.

Step 7: Connect to Acceptance Criteria

Each requirement maps to acceptance criteria — how completion is verified.

Requirement: The system shall allow users to reset their password via email.

Acceptance Criteria:
- User can request a reset by entering their email
- A reset link is sent within 60 seconds
- The link is valid for 24 hours
- Used or expired links return an error
- Successfully resetting redirects to sign-in
- The old password no longer works

The criteria break the requirement into verifiable conditions.

Step 8: Validate With Stakeholders

After writing, review with stakeholders. Two questions:

Did I capture what you meant?
Are there situations this doesn't cover?

Stakeholder review catches gaps and misunderstandings before engineering starts.

Step 9: Trace Requirements

Each requirement should have an identifier (REQ-001) and a way to trace it through:

Design documents (which design satisfies it)
Test cases (which tests verify it)
Implementation (which code addresses it)

Traceability matters for:

Verification ("does the system meet REQ-005?")
Change impact ("if I change REQ-005, what's affected?")
Audit (regulatory environments often require traceability)

For most products, light traceability is enough — IDs that allow cross-referencing. Heavy traceability (every line of code mapped to requirements) is overkill outside specific regulated contexts.

Step 10: Maintain Over Time

Requirements aren't static. As the product evolves:

New requirements get added
Old requirements get removed (mark as deprecated, don't delete)
Changed requirements get versioned

Without maintenance, the requirements document becomes fiction — describing what was wanted years ago, not what the system does today.

Patterns for Different Requirement Types

User actions: "The system shall [allow / enable / provide]..."

System behaviors: "The system shall [calculate / generate / send]..."

Constraints: "The system shall [not exceed / require / enforce]..."

Quality attributes: "The system shall [achieve / maintain / support]..."

Each pattern fits a different kind of requirement. Picking the right pattern makes the requirement easier to write.

Common Mistakes

Implementation in requirements. "The system shall use a Redis cache." That's an implementation decision, not a requirement. Requirements describe behavior; implementations realize it.

Solution-shaped requirements. Pre-specifying the UI, the database choice, the architecture. Constrains the engineering team unnecessarily.

Multi-part requirements. "The system shall allow users to sign in and view their profile and edit their settings." That's three requirements. Split.

Aspirational language. "The system should ideally..." If it's required, say shall. If it's a wish, mark it as such.

Compound conditions. "The system shall do X when Y or Z unless A or B and C." Decompose; readers can't follow.

Sizing the Requirements Set

For most products, the total requirement count is in the dozens or low hundreds. For complex products, a few hundred is normal. Thousands suggests over-decomposition.

If you have 1000 requirements, you're probably mixing requirements with design or test specifications. Pull them apart.

A Worked Example

Need: Users with multiple workspaces struggle to manage them; they currently have to sign out and back in to switch.

Requirements:

REQ-014: The system shall display the current workspace context to authenticated users in the application header.

REQ-015: The system shall allow authenticated users to switch between workspaces they have access to without signing out.

REQ-016: When a user switches workspaces, the system shall preserve the user's URL context where the destination workspace has an equivalent page.

REQ-017: When a user switches workspaces, the system shall load the destination workspace's data within 2 seconds at p95 latency.

REQ-018: The system shall not display the workspace switcher to users with access to only one workspace.

Five focused requirements. Each is testable, atomic, and unambiguous.

Key Takeaway

Good requirements are necessary, unambiguous, testable, complete, consistent, and atomic. Start with the need, identify the actor and action, specify conditions, and check for ambiguous language. Cover both functional and non-functional aspects. Connect to acceptance criteria; trace lightly. Avoid implementation details, multi-part requirements, and solution-shaped framing. The discipline of writing good requirements pays back many times over in reduced rework and disputes.

ShiftQuality