Feature Specification

What a feature specification is

A feature specification is the working document that defines a single feature in enough detail that a team can design, build, and verify it without guessing. It answers four plain questions for one slice of the product: what problem are we solving, for whom, what exactly will we build, and how will we know it is done and correct. Where a roadmap says that a feature is coming and a strategy doc says why it matters, the feature spec says precisely what it is.

The audience is the people who will turn the idea into shipped software — engineers, designers, and testers — plus the product owner who signs off on scope. A good spec removes ambiguity. Every reader should come away with the same mental picture of the finished feature, the same understanding of where its edges are, and the same checklist for declaring it complete.

Feature spec versus PRD

A feature specification and a product requirements document (PRD) overlap but operate at different altitudes. A PRD usually covers a whole product area, release, or initiative: it may describe several features, the personas they serve, the business goals, success metrics, and a phased rollout. It is the broader planning artefact and tends to be owned at the product-management level.

A feature spec zooms into one feature inside that picture. It inherits context from the PRD — the problem, the user, the strategic reason — but spends its words on the concrete behaviour of that single feature: the exact requirements, the precise acceptance criteria, the edge cases, and the parts deliberately left out. A useful rule of thumb: a PRD answers "what should this product do and why?" across many features, while a feature spec answers "exactly how should this one feature behave?" in testable detail. On a small team the two sometimes merge into one document, but as scope grows it pays to keep the per-feature detail in its own spec so it can be reviewed, estimated, and built independently.

What a feature spec contains

A complete feature spec covers a predictable set of parts, each doing a distinct job:

• Problem and context. The user or business problem this feature exists to solve, stated plainly. If a reader cannot see the problem, they cannot judge whether the solution fits.
• Goals and non-goals. What success looks like for this feature, paired with an explicit list of what it is not trying to do. Non-goals prevent scope creep and head off the "but shouldn't it also..." debate.
• User stories. Short, role-framed statements of what users want to accomplish, in the form "As a [role], I want [capability] so that [benefit]." They keep the spec anchored to real user value.
• Functional requirements. The specific behaviours the feature must exhibit — numbered so they can be referenced, reviewed, and traced to tests.
• Acceptance criteria. The concrete, checkable conditions that must be true for the feature to be accepted. This is the contract between product and engineering for "done."
• Edge cases. The unusual, empty, error, and boundary conditions, and how the feature should behave in each. This is where most defects hide.
• Out of scope. An explicit list of related things this feature will not include, so the boundary is a decision rather than an accident.

Dependencies, rough sizing, and open questions are common additional sections, but the seven above are the load-bearing core.

Writing good acceptance criteria

Acceptance criteria are the most valuable — and most often weak — part of a spec. They turn a vague intention into a pass-or-fail test. The single most useful technique is the Given / When / Then form: Given some starting state, When the user does something, Then a specific, observable result occurs. For example: "Given a saved filter exists, when the user selects it, then the list updates to show only matching items and the filter name appears in the active-filter bar."

Good acceptance criteria share a few traits. They are specific — they name real values, states, and messages rather than "works correctly." They are observable — a tester or a stakeholder can verify each one by looking at the product, not by reading the code. They are independent — each criterion checks one thing, so a failure points to a single cause. And they are complete enough — between the criteria and the edge-case list, every meaningful behaviour is covered. Write them before the build starts, not after; written first, they shape the implementation and double as the test plan.

Common mistakes

Several recurring problems weaken feature specs:

• No non-goals. Without an explicit out-of-scope list, every reviewer quietly assumes a slightly larger feature, and scope balloons during the build.
• Solution before problem. Jumping straight to "add a dropdown here" without stating the problem leaves no way to judge whether the dropdown is the right answer.
• Untestable acceptance criteria. "The page should be fast" or "the flow should feel intuitive" cannot be passed or failed. Replace them with measurable, observable conditions.
• Ignoring edge cases. Specs that describe only the happy path push the hard decisions onto whoever is coding at 5pm on a Friday — which is how inconsistent behaviour gets shipped.
• Mixing in implementation detail. A spec describes what the feature does and how users experience it, not which class or library to use; locking those down too early limits the engineers who know best.
• Treating it as write-once. Specs drift as questions get answered during the build. A spec that is never updated quickly stops matching the product and stops being trusted.