Writing Good Requirements
Good requirements are clear, unambiguous, verifiable, and traceable. This guide covers characteristics, patterns, and common mistakes.
Characteristics of Good Requirements (SMART)
| Characteristic |
Meaning |
Check |
| Specific |
Clear and precise, no ambiguity |
Could two people interpret differently? |
| Measurable/Verifiable |
Can be tested or inspected to confirm satisfaction |
How would we prove this is met? |
| Achievable/Attainable |
Technically and economically feasible |
Realistic given constraints? |
| Relevant/Appropriate |
Traces to a need, appropriate level of detail |
Does this solve the stated need? |
| Traceable/Time-bound |
Can be traced and has clear scope |
Linked to parent need/requirement? |
The "Shall" Rule
Use "shall" for mandatory requirements. Avoid:
- "will" - often states facts, not requirements
- "should" - implies preference, not binding
- "may" - implies optional, unclear if required
- "must" - acceptable but "shall" is more common in standards
Example: "The system shall authenticate users via OAuth 2.0 before granting access."
Requirements Writing Patterns
| Pattern |
When to Use |
Example |
| Action-Oriented |
Functional requirements |
"The system shall validate user input against schema X" |
| Performance |
Quantifiable performance needs |
"The system shall respond to search queries in < 200ms at p95" |
| Interface |
Defining interfaces |
"The system shall expose a REST API at /api/v1/..." |
| Constraint |
Non-negotiable constraints |
"The system shall not store plaintext passwords" |
| Condition |
Behavior under conditions |
"If authentication fails 3 times, the system shall lock the account for 15 minutes" |
Common Anti-Patterns
| Anti-Pattern |
Bad Example |
Good Example |
| Vague |
"The system shall be fast" |
"The system shall load the dashboard in < 2 seconds on 4G" |
| Unverifiable |
"The system shall be user-friendly" |
"The system shall pass usability testing with SUS score > 80" |
| Solution in requirement |
"The system shall use Redis for caching" |
"The system shall cache frequently accessed data with < 10ms retrieval" (unless Redis is a constraint) |
| Multiple requirements |
"The system shall login users and log all activity and send emails" |
Split into separate requirements |
| Negative-only |
"The system shall not crash" |
Better to state positive behavior or specific reliability requirement |
| Escape clauses |
"The system shall... if possible" |
Remove or make explicit as a constraint/trade-off |
Types of Requirements
| Type |
Description |
Example |
| Functional (FR) |
What the system does |
"The system shall generate a summary of uploaded documents" |
| Performance |
How well it performs |
"The system shall process 1000 requests/minute" |
| Interface |
How it interacts |
"The system shall integrate via MCP protocol" |
| Security |
Security-related needs |
"The system shall encrypt data at rest using AES-256" |
| Reliability/Availability |
Uptime, fault tolerance |
"The system shall achieve 99.9% uptime excluding scheduled maintenance" |
| Usability |
User experience |
"A new user shall complete onboarding in < 3 minutes" |
| Maintainability |
Ease of changes |
"The system shall have automated tests with > 80% coverage on critical paths" |
| Portability |
Deployment flexibility |
"The system shall run on Linux x86_64 and ARM64" |
| Regulatory/Compliance |
Legal/compliance |
"The system shall comply with GDPR data deletion requirements" |
Requirements Checklist
For each requirement, verify:
- [ ] Clear: No ambiguous words (fast, easy, user-friendly, robust)
- [ ] Singular: One requirement per statement
- [ ] Verifiable: Can be verified by test, analysis, inspection, or demonstration
- [ ] Feasible: Achievable within constraints
- [ ] Necessary: Traces to a stakeholder need
- [ ] Correct: Accurately reflects the need
- [ ] Complete: Sufficient for design
- [ ] Consistent: No conflicts with other requirements
- [ ] Traceable: Has unique ID and trace links
Verification Methods
| Method |
Description |
When to Use |
| Inspection |
Visual examination of design/documents |
Documents, interfaces, code structure |
| Analysis |
Mathematical/modeling analysis |
Performance predictions, safety analysis |
| Demonstration |
Operation of system to show requirement met |
Functional behavior, user workflows |
| Test |
Controlled testing with measured results |
Quantitative requirements (latency, accuracy) |
Example: Agentic System Requirements
REQ-001: The agent shall authenticate using the configured identity provider before executing tools.
REQ-002: The agent shall log all tool invocations with timestamp, user, tool name, and parameters.
REQ-003: The system shall return responses within 5 seconds at p95 for simple queries.
REQ-004: The agent shall refuse requests classified as harmful per the safety policy.
REQ-005: The system shall provide source citations for RAG-generated answers.
- Needs Vs Requirements — From needs to requirements
- Requirements Analysis Traceability — Traceability matrices
- Verification Methods — How to verify
- Test Pyramid — Mapping to tests
- Metrics — Eval metrics as requirements
Sources
- ISO/IEC/IEEE 29148:2018
- INCOSE Systems Engineering Handbook
- NASA Systems Engineering Handbook
- MITRE Systems Engineering Guide
- Kossiakoff et al. - Systems Engineering Principles and Practice
