Requirements Specification

Agent Prompt Snippet

Ensure the project has a requirements specification that translates user needs into verifiable engineering requirements with explicit acceptance criteria.

Purpose

A requirements specification translates the “what” of a Product Requirements Document into the “must be verifiably true” of engineering acceptance criteria. Where the PRD describes user needs and business outcomes, the requirements specification states the system’s required behaviors in terms that can be tested, measured, and objectively accepted or rejected.

Requirements specifications prevent the most expensive failure mode in software: building the wrong thing to completion. Without explicit acceptance criteria, a feature is “done” when the developer says it is. With them, a feature is done when every acceptance criterion is verifiable. This shifts quality assurance from subjective to objective.

There are three types of requirements. Functional requirements specify what the system must do: “when a user submits a valid email address, the system must send a confirmation email within 30 seconds.” Non-functional requirements specify quality attributes: “the confirmation email must deliver within 30 seconds for 99.5% of sends.” Constraints specify what the system must not do or what boundaries it must operate within: “no email address may be used to register more than 5 accounts.”

Well-written requirements specifications use the language of verifiability: “must,” “shall,” “will not” (for requirements), not “should,” “may,” “might consider” (for suggestions). Each requirement should be traceable to a specific user scenario in the PRD and to a specific test case in the test plan.

Who needs this document

Persona	Why they need it	How they use it
Sam (Indie Dev)	Prevents building feature-complete but requirement-incomplete software	Writes acceptance criteria before implementation; uses them as a personal definition of done
Claude Code (AI Agent)	Needs testable criteria to know when a feature is correctly implemented	Reads requirements spec before implementing features; generates test cases from acceptance criteria
Priya (Eng Lead)	Manages scope, resolves ambiguity, drives QA; unambiguous requirements prevent endless debates about “done”	Reviews requirements for testability before sprint begins; uses acceptance criteria to close feature debates
DevOps (CI Operator)	Non-functional requirements (latency, availability) inform infrastructure configuration	Reads NFRs to configure health checks, autoscaling triggers, and SLA monitoring alerts

What separates a good version from a bad one

Criterion 1: Requirements are verifiable, not aspirational

✓ Strong: “REQ-042: The search endpoint must return the first page of results within 200ms (p99) for queries of up to 1000 characters on an index of up to 1 million documents. Verification: load test with k6, 100 concurrent users, 10-minute duration, asserts p99 < 200ms.”

✗ Weak: “REQ-042: The search must be fast.” (Not verifiable. “Fast” is a judgment, not a measurement. No test can confirm or deny this requirement.)

Criterion 2: Each requirement is atomic — one behavior per requirement

✓ Strong: “REQ-101: A session token must expire after 24 hours of inactivity. REQ-102: An expired session token must return HTTP 401 on any authenticated request. REQ-103: A new session token must be issued upon successful re-authentication after expiry.”

✗ Weak: “REQ-101: Sessions must work correctly with proper expiry and re-authentication.” (Three distinct verifiable behaviors compressed into one requirement. When one fails and two pass, the requirement is simultaneously passed and failed.)

Criterion 3: Constraints are distinguished from functional requirements

✓ Strong: “Constraints: (1) The system must operate within AWS us-east-1 exclusively (data residency requirement). (2) All PII must be stored in RDS — no PII in S3, CloudFront, or CloudWatch logs. (3) The binary must be under 20 MB to fit Homebrew distribution guidelines. These constraints cannot be relaxed without a change control process.”

✗ Weak: Constraints mixed with functional requirements in the same numbered list. Mixing types makes prioritization impossible: you can deprioritize a functional requirement; you cannot deprioritize a constraint.

Criterion 4: Non-functional requirements are quantified with measurement method

✓ Strong: “NFR-05: Availability. The API service must achieve ≥ 99.9% monthly uptime, measured as the fraction of 1-minute intervals where the /healthz endpoint returns HTTP 200 within 5 seconds. Monitoring: CloudWatch synthetic canaries, 1-minute interval. SLA credit triggered at < 99.5%.”

✗ Weak: “NFR-05: The system must be highly available.” (No target, no measurement method. Impossible to verify and impossible to alert on.)

Common mistakes

Requirements that specify implementation. “REQ-055: User passwords must be stored using bcrypt with cost factor 12” mixes requirement (secure password storage) with implementation choice (bcrypt, cost 12). The requirement should state the security property; the implementation should be chosen in the TDD. Implementation requirements break abstraction and make the spec brittle.

Orphaned requirements. Requirements that exist in the spec but don’t trace to a user story in the PRD are red flags. They may be gold-plating, historical artifacts, or requirements for features no one asked for. Every requirement should have a parent user scenario.

No change management process. Requirements specs written once and never updated are the most dangerous kind—they tell the team what was agreed, not what is current. Establish a process: requirements can change, but changes must be reviewed, tracked, and communicated to all stakeholders.

Conflating “must” and “should.” In requirements language, “must” is mandatory (non-compliance is a defect), “should” is a recommendation (best effort). Using “should” everywhere produces a requirements spec with no firm commitments and no clear acceptance criteria.

How to use this document

When to create it

Write the requirements specification after the PRD is approved but before implementation begins. Requirements gathering and PRD writing often happen together. The requirements spec is the engineering artifact that emerges from that process.

Who owns it

The engineering lead or product manager, with input from engineers. The requirements spec is a joint product of product and engineering—neither alone produces a complete specification.

How AI agents should reference it

get_standard_docs(type="backend_service", features=[])
→ requirements_spec in documents[]
→ agent reads requirements spec before implementing features
→ agent generates test cases from acceptance criteria
→ agent verifies implementation against each REQ before declaring work complete

The prompt_snippet — “Ensure the project has a requirements specification that translates user needs into verifiable engineering requirements with explicit acceptance criteria” — tells the agent to verify requirements are testable, not just descriptive.

How it connects to other documents

The Requirements Specification is downstream of the PRD (user needs → verifiable requirements) and upstream of the Technical Design Document (requirements constrain implementation), test plan (each requirement has a test case), and Architecture Overview (non-functional requirements shape architectural choices).