How to Write Good Software Requirements: 10 Rules with Examples

Writing software requirements is not simply a matter of documenting what a stakeholder asks for. A good requirement must communicate the intended behavior clearly, establish boundaries, and provide enough objective detail for developers to implement it and testers to verify it.

Consider this statement from a stakeholder:

The monitoring device should alert the nurse quickly when a patient's condition becomes critical.

The intention is understandable, but several questions remain unanswered. What constitutes a critical condition? How quickly must the alert appear? What happens if the primary alert mechanism fails? How will a tester determine whether the requirement has been satisfied?

These unanswered questions are where ambiguity enters software development. If different people interpret the same statement differently, the resulting implementation may not meet the original need.

This guide presents ten practical rules for writing better software requirements, using an illustrative patient-monitoring system to demonstrate the principles.

What Makes a Software Requirement Good?

A good software requirement describes a necessary capability, constraint, or quality attribute in a way that relevant stakeholders can understand and objectively evaluate.

For practical purposes, assess each requirement against these characteristics:

• Clear: It has one understandable interpretation.
• Complete: It contains the information necessary to understand the expected behavior.
• Consistent: It does not conflict with other approved requirements.
• Feasible: It can be implemented within the applicable technical, operational, and regulatory constraints.
• Verifiable: Its satisfaction can be demonstrated through inspection, analysis, demonstration, or testing.
• Traceable: It can be connected to its source, related requirements, and verification evidence.

These characteristics are complementary. A requirement may be easy to read but impossible to verify, or measurable but inconsistent with another requirement. Understanding the distinction between functional and non-functional requirements helps clarify the different types of obligations a system must satisfy. Read our guide to functional vs. non-functional requirements for practical examples.

10 Rules for Writing Better Software Requirements

1. Describe the Required Outcome, Not Just the Solution

Requirements often become unnecessarily restrictive when they specify an implementation before the underlying need is understood.

Weak requirement:

The application shall use a red pop-up window to notify the nurse.

This statement prescribes a particular interface without explaining the problem it must solve. A red pop-up may be unsuitable for a small display, inaccessible to some users, or ineffective when the application is not in the foreground.

Improved requirement:

When a configured critical-condition threshold is crossed, the monitoring application shall present a visible alert identifying the affected patient and the triggering condition.

The improved statement focuses on the required outcome while leaving implementation choices open, provided they satisfy the requirement.

When to specify the solution: Prescriptive requirements are appropriate when an interface, technology, protocol, or design constraint is mandated by an approved architecture, external interface, safety control, or other justified constraint.

2. Use One Primary Requirement per Statement

A requirement that combines several independent obligations is difficult to review, trace, and test.

Weak requirement:

The application shall authenticate the nurse, display the patient dashboard, record the login time, and send a notification when the session expires.

This sentence contains several behaviors. One may work correctly while another fails, making the overall pass/fail result unclear.

Improved decomposition:

• AUTH-001: The application shall authenticate a user before granting access to patient records.
• UI-001: After successful authentication, the application shall display the dashboard associated with the authenticated user's authorized role.
• AUD-001: The application shall record the timestamp of each successful authentication event.
• SEC-001: When an authenticated session expires, the application shall prevent further access to protected functions until the user authenticates again.

Each requirement can now be reviewed and verified independently.

However, do not split a requirement mechanically whenever it contains the word "and." Some conditions and actions belong together because they describe one indivisible behavior. The objective is independent verification, not shorter sentences at any cost.

3. Replace Vague Words with Observable Criteria

Words such as "fast", "easy", "reliable", "appropriate", and "user-friendly" express intentions but rarely establish an objective acceptance threshold.

For example:

Vague statement	More verifiable statement
The dashboard shall load quickly.	Under the approved test workload, the dashboard shall finish rendering within 2 seconds for at least 95% of measured requests.
The system shall retain sufficient history.	The system shall retain monitoring records for at least 365 days.
The application shall support many users.	The application shall support 500 concurrent authenticated users under the approved workload profile.

The numerical values above are illustrative project targets, not universal standards or recommendations for medical devices. Actual thresholds must be derived from stakeholder needs, risk analysis, architecture, and performance evaluation.

Notice that the first improved requirement also specifies a measurement condition and percentile. A response-time target without a defined workload or measurement method can still produce misleading results.

4. Make Conditions, Actions, and Outcomes Explicit

Many requirements describe a general capability without identifying when it applies or what the system must do in response.

Weak requirement:

The application shall lock inactive sessions.

How long is a session allowed to remain inactive? Does the lock apply to all roles? What happens to unsaved information?

Improved requirement:

When an authenticated user's session remains inactive for 15 consecutive minutes, the application shall lock access to protected functions and require reauthentication before restoring access.

This defines a trigger, a measurable condition, an expected action, and a recovery rule.

The 15-minute interval is an example only. The appropriate timeout must be determined from the system's security requirements and operating context.

5. Define Boundaries and Exceptional Conditions

Requirements frequently describe only the normal operating scenario. Real systems must also handle invalid inputs, unavailable services, communication interruptions, and unexpected user actions.

Writing use cases with alternate and exceptional flows is a practical way to uncover these conditions before they become missing requirements.

Consider a patient-monitoring application that receives data from a sensor.

Incomplete requirement:

The application shall display the patient's heart rate.

What happens when the sensor disconnects? Should the application continue displaying the last measurement as if it were current? How does the user distinguish a valid reading from stale data?

Improved requirements:

• MON-001: The application shall display the latest valid heart-rate measurement received from the configured sensor.
• MON-002: If no valid heart-rate measurement is received within the configured data-freshness interval, the application shall indicate that the displayed measurement is unavailable or stale.
• MON-003: The application shall display the timestamp associated with the latest valid heart-rate measurement.

The data-freshness interval must be specified separately or referenced through a controlled configuration requirement.

For safety-related systems, failure behavior must be derived from hazard analysis and the system's risk controls. A generic error message is not necessarily an adequate safety response.

6. Define Terminology and Units Consistently

Ambiguous terminology creates defects even when every sentence appears grammatically correct.

For example, the terms "user," "operator," "administrator," and "clinician" may refer to different roles. Likewise, "response time" might mean the time until a request is accepted, a screen is rendered, or a result is available.

Establish a project glossary for important terms and define measurement units explicitly.

Weak requirement:

The device shall report temperature at regular intervals.

Improved requirement:

While continuous monitoring is enabled, the device shall record one valid temperature measurement every 5 seconds.

This example defines the measurement frequency. The project should also specify the unit, accuracy, operating conditions, and behavior when a valid measurement cannot be obtained, wherever those details are necessary to meet the intended need.

7. Distinguish Requirements from Design Decisions

A requirements document can become difficult to maintain when it mixes externally observable behavior with internal implementation details.

Compare the following statements:

• Requirement: The application shall retrieve authorized patient records using the approved patient-record service.
• Design decision: The application shall implement the patient-record client using a particular internal class and caching algorithm.

The first defines a system obligation and an interface constraint. The second describes an implementation approach.

Implementation details can be legitimate requirements when they are mandatory—for example, when a protocol, architecture decision, or platform constraint has been approved. Otherwise, keep design choices in the appropriate architecture or design documentation.

This separation makes it easier to evaluate alternative designs without changing the underlying stakeholder need.

8. Make Requirements Independently Verifiable

A requirement should support an objective verification decision. Reviewers should be able to determine what evidence is needed and what constitutes a pass or fail.

Weak requirement:

The application shall provide secure access to patient information.

"Secure access" covers multiple security properties and does not establish measurable verification criteria.

Improved decomposition:

• SEC-101: The application shall deny access to patient records when the authenticated user's role does not include the required permission.
• SEC-102: The application shall terminate an authenticated session when its configured inactivity timeout is exceeded.
• SEC-103: The application shall record successful and failed authentication attempts in the security audit log.

Each statement can be associated with a verification method and corresponding evidence.

For example, SEC-101 can be verified by attempting to access a patient record using an authenticated account without the required permission and confirming that access is denied.

Security requirements should be developed from the system's threat model, applicable obligations, and risk assessment rather than assuming that these three examples provide complete security coverage.

9. Give Every Requirement a Stable Identity and Traceable Source

Requirement identifiers make it possible to discuss changes precisely and connect requirements to their sources, related records, and verification evidence.

For example, a requirement record might contain:

• ID: PERF-014
• Name: Patient dashboard response time
• Requirement statement: Under the approved workload profile, the dashboard shall finish rendering within 2 seconds for at least 95% of measured requests.
• Source: Approved clinical workflow performance need
• Verification method: Performance test
• Verification evidence: Performance test report
• Status: Approved

This is an illustrative record structure. The source reference should identify the actual approved stakeholder need or other authoritative origin in a real project.

Stable identifiers are particularly useful when requirements change. A test case, design element, or downstream requirement can refer to PERF-014 even if its display name is revised.

For a detailed explanation of how requirements connect to their sources, design elements, and test cases, read our guide to requirements traceability.

10. Review Requirements with Developers, Testers, and Stakeholders

Requirements quality improves when review is treated as a collaborative engineering activity rather than a final proofreading exercise.

Each discipline contributes a different perspective:

• Business analysts: Confirm that the requirement reflects the intended business or user need.
• Systems engineers and architects: Evaluate interfaces, constraints, feasibility, and system-level consistency.
• Developers: Identify missing details, technical constraints, and conflicting assumptions.
• QA and test engineers: Assess verifiability, boundary conditions, negative scenarios, and test coverage.
• Risk and compliance specialists: Review applicable safety, security, regulatory, and quality obligations.

A useful review question is: "Could two competent people implement or test this requirement differently while both believing they followed the specification?"

If the answer is yes, the requirement may need clarification, additional constraints, or a reference to an approved definition.

Review comments should be resolved and recorded before a requirement is baselined. Unresolved assumptions should not silently become implementation decisions.

Worked Example: From a Vague Need to Verifiable Requirements

Consider this fictional stakeholder request for a patient-monitoring application:

The application must help nurses identify patients who need immediate attention and should work reliably even when connectivity is interrupted.

This statement expresses two important needs, but it is not sufficiently precise to serve as a complete specification.

Step 1: Identify the underlying needs

• Users must be able to recognize conditions that require attention.
• The application must communicate the status and freshness of incoming measurements.
• Loss of connectivity must not create a misleading impression that monitoring is functioning normally.

Step 2: Identify unanswered questions

• Which conditions trigger an alert?
• What is the required alert latency?
• What information must the alert contain?
• How is stale data identified?
• Which functions must remain available during a network interruption?
• What recovery behavior is required when connectivity returns?

Step 3: Draft candidate requirements

ID	Candidate requirement	Verification approach
ALR-001	When a configured alert condition is detected, the application shall display an alert identifying the affected patient and triggering condition.	Functional test using a controlled alert condition.
ALR-002	The application shall display the alert within the approved maximum latency after receiving a valid measurement that satisfies the configured alert condition.	Timed test under the approved operating conditions.
DAT-001	When the configured data-freshness interval is exceeded, the application shall visibly indicate that the measurement is stale.	Test with controlled delays in measurement delivery.
NET-001	When the monitoring data connection is interrupted, the application shall indicate the connection-loss condition and prevent affected data from being presented as current.	Network interruption and data-display tests.

These are candidate requirements for illustration, not a complete medical-device specification. The actual latency, freshness interval, alert logic, and safe-state behavior must be established through approved system requirements and risk management.

Step 4: Establish traceability

Each candidate requirement should be linked to its originating stakeholder need. Where applicable, it should also be linked to system or software design elements, risk controls, test cases, and verification results.

This creates a chain of evidence showing why a requirement exists, how it is implemented, and how its satisfaction is demonstrated.

Step 5: Review and baseline

Before approval, confirm that the requirements are unambiguous, feasible, consistent with the system architecture, appropriately risk-controlled, and objectively verifiable. Record open decisions and obtain approval from the responsible stakeholders.

Common Mistakes to Avoid

• Using subjective adjectives: Replace "fast," "easy," or "robust" with defined criteria wherever measurable performance is required.
• Combining unrelated behaviors: Separate obligations when they need independent verification or traceability.
• Ignoring failure conditions: Specify relevant behavior for invalid inputs, unavailable services, and interrupted communication.
• Confusing requirements with design: Avoid imposing implementation details unless they are justified constraints.
• Writing requirements without tests in mind: Ask what evidence would demonstrate satisfaction before approving the statement.
• Leaving assumptions undocumented: Record decisions, definitions, units, and referenced configuration values.
• Failing to manage changes: Evaluate the impact of requirement changes on dependent requirements, designs, tests, risks, and released versions.
• Treating a checklist as proof of quality: A requirement can pass a writing checklist and still be wrong, unnecessary, unsafe, or inconsistent with stakeholder needs.

A Practical Requirements Quality Checklist

Use this checklist during requirement reviews. A "No" answer indicates that the requirement may need clarification or further analysis.

• Does the requirement have a unique, stable identifier?
• Is its source or justification recorded?
• Does it describe a necessary behavior, constraint, or quality attribute?
• Is the expected behavior clear and unambiguous?
• Are important conditions, boundaries, and failure behaviors addressed?
• Are units, thresholds, and referenced definitions explicit where needed?
• Can the requirement be implemented within known constraints?
• Can its satisfaction be objectively verified?
• Is it consistent with related and higher-level requirements?
• Are applicable risks and external obligations addressed?
• Can it be traced to relevant design elements and verification evidence?
• Has it been reviewed by the appropriate stakeholders?

Passing this checklist is a useful starting point, not a substitute for domain-specific review, risk analysis, or formal verification planning.

Frequently Asked Questions

What is the difference between a good requirement and a user story?

A user story typically expresses a user need or desired outcome in an Agile development context. A requirement specifies an obligation, capability, constraint, or quality attribute that the system or a component must satisfy. User stories may be supported by detailed functional requirements, non-functional requirements, and acceptance criteria. For a worked example of mapping a user story to functional requirements, see our guide to writing an SRS for Agile teams.

Should every software requirement be measurable?

Every requirement should be verifiable, but not every requirement needs a numerical threshold. A requirement may be verified by inspection, demonstration, analysis, or testing. Numerical criteria are particularly useful when specifying performance, capacity, timing, accuracy, and other measurable properties.

How long should a software requirement be?

There is no universal word limit. A requirement should be concise enough to understand and detailed enough to establish its intended meaning. If it contains several independently verifiable obligations, consider decomposing it into separate requirements.

Can AI help write software requirements?

AI tools can help identify ambiguous language, suggest missing boundary conditions, improve readability, and generate candidate test scenarios. However, generated requirements must be checked against authoritative stakeholder needs, technical constraints, safety and security considerations, and project standards. AI output should not be treated as approved requirements without appropriate review.

How do requirements relate to test cases?

Requirements define what the system must satisfy; test cases define procedures, inputs, expected results, and conditions used to verify specified behavior. Traceability between requirements and test cases helps identify requirements without adequate verification coverage and tests without a clear requirement basis.

Conclusion

Good software requirements are produced through disciplined analysis, not merely careful wording. They connect stakeholder needs to implementable obligations and provide a defensible basis for design, testing, and acceptance.

Start by clarifying the intended outcome, remove ambiguity, define measurable criteria where appropriate, address important boundary conditions, and establish traceability. Then review the requirements with the people responsible for implementing, verifying, and approving the system.

These practices are useful for ordinary business applications and become especially important in complex systems where failures can affect safety, security, compliance, or operational continuity.

Related Articles