Feature Specification Template

Overview

The most expensive bugs are not in code — they are in misunderstood requirements. A feature specification is a document that aligns product, design, and engineering on what to build, why it matters, and how to know it is done. It prevents the “I thought you meant…” conversations that derail sprints and create rework. A good spec is not a contract; it is a shared understanding that evolves as the team learns.

When to Use

Use this template when:

• A feature touches multiple systems, teams, or user journeys
• Engineers and product managers have different understandings of the requirement
• The feature has non-obvious edge cases, dependencies, or rollout complexity
• You need to estimate effort before committing to a sprint
• The feature affects users, data, or billing and needs explicit sign-off

Prerequisites

Before writing a feature specification:

• The product goal is clear: what problem are we solving and for whom?
• Stakeholders (product, engineering, design, QA) are identified
• Success metrics are defined: how will we know this feature worked?
• Constraints are documented: time, budget, compliance, or technical limitations
• You have reviewed related specs to avoid duplicating or conflicting with existing work

Solution

# Feature Specification: `<Feature Name>`

> Author: ______ | Product Owner: ______ | Status: Draft / In Review / Approved
> Created: YYYY-MM-DD | Last updated: YYYY-MM-DD | Target release: ______

## 1. Summary

**Problem:** [What user pain or business opportunity does this address?]

**Proposed solution:** [One-paragraph description of the feature]

**Success criteria:** [How we measure whether this feature solved the problem]

## 2. Goals and Non-Goals

### Goals
- [Goal 1: what we will achieve]
- [Goal 2]
- [Goal 3]

### Non-Goals
- [What we are explicitly not doing in this version]
- [What is out of scope]

## 3. User Stories

| User | Need | So That | Priority |
|------|------|---------|----------|
| [Persona] | [Action] | [Outcome] | P0 / P1 / P2 |
| ______ | ______ | ______ | ______ |

## 4. Functional Requirements

### 4.1 [Requirement Area 1]
- **FR-1.1:** [Specific, testable requirement]
- **FR-1.2:** [Specific, testable requirement]

### 4.2 [Requirement Area 2]
- **FR-2.1:** [Specific, testable requirement]

## 5. Non-Functional Requirements

- **Performance:** [e.g., p99 response time < 200ms]
- **Scalability:** [e.g., support 10x current load]
- **Availability:** [e.g., 99.9% uptime during rollout]
- **Security:** [e.g., data encrypted in transit and at rest]
- **Accessibility:** [e.g., WCAG 2.1 AA compliant]
- **Compliance:** [e.g., GDPR right to deletion supported]

## 6. Design and UX

- **Figma / mockups:** [Link]
- **Copy and localization:** [Link or notes]
- **Interaction flow:** [Step-by-step or diagram]
- **Edge cases:** [Empty states, errors, loading, offline]

## 7. Technical Approach

### Architecture
[Diagram or description of how this feature fits into existing systems]

### Data Model Changes
[New tables, fields, or schema changes]

### API Changes
[New endpoints, modified payloads, backward compatibility plan]

### Dependencies
[Services, libraries, or teams this feature depends on]

### Rollout Strategy
- **Phase 1:** [Internal testing / alpha]
- **Phase 2:** [Beta with limited users]
- **Phase 3:** [General availability]
- **Rollback plan:** [How to undo if something goes wrong]

## 8. Acceptance Criteria

- [ ] [Criteria 1: specific, verifiable condition for done]
- [ ] [Criteria 2]
- [ ] [Criteria 3]

## 9. Open Questions

| Question | Owner | Due Date |
|----------|-------|----------|
| ______ | ______ | ______ |

## 10. Appendix

- **Related specs:** [Links]
- **Historical context:** [Previous attempts, related decisions]
- **Glossary:** [Terms that need definition]

Explanation

The template is organized by audience: product owns the summary and goals, design owns the UX section, engineering owns the technical approach, and QA owns acceptance criteria. Separating functional from non-functional requirements prevents the common mistake of forgetting performance, security, or accessibility until late in development. The non-goals section is particularly important: it prevents scope creep by making explicit what is out of scope.

Variants

Context	Adjustments	Notes
API-only feature	Replace UX section with endpoint design, payload schemas, and versioning plan	Internal APIs still need user stories (the user is another developer)
Data / ML feature	Add data sources, model training pipeline, and evaluation metrics	ML specs need experiment tracking and reproducibility
Security feature	Expand security requirements; add threat model and compliance mapping	Security features need explicit sign-off from security team
Platform / infrastructure feature	Replace user stories with affected teams and migration requirements	Platform work has users, but they are internal teams
Experiment / A/B test	Add hypothesis, success metrics, sample size, and rollback criteria	Experimental features need clear kill criteria

Best Practices

1. Write the spec before coding starts — the goal is shared understanding, not documentation after the fact
2. Keep the summary on one page — busy stakeholders should grasp the feature in 60 seconds
3. Make requirements testable — vague requirements like “fast” become “p99 < 200ms”
4. Include non-goals explicitly — this is your best defense against mid-sprint scope expansion
5. Review the spec with engineering before estimating — engineers catch edge cases product misses

Common Mistakes

1. Writing the spec alone — a spec written by product without engineering input becomes fiction
2. Skipping non-functional requirements — performance, security, and accessibility are not “nice to have”; they are requirements
3. Making acceptance criteria vague — “works as expected” is not acceptance criteria; “user can complete checkout in under 3 clicks” is
4. Not updating when scope changes — specs that diverge from reality mislead QA, support, and future maintainers
5. Forgetting rollout and rollback — the feature is not done when code is merged; it is done when users are successfully using it

Frequently Asked Questions

How long should a feature spec be?

Long enough to eliminate ambiguity, short enough that people will read it. A simple feature may be two pages; a complex platform change may be ten. The summary should always fit on one page. If the full spec is long, add a table of contents.

Who owns the spec?

Product owns the problem, goals, and success criteria. Engineering owns the technical approach and feasibility. Design owns the UX. The author (usually product or tech lead) coordinates revisions. Approval should require sign-off from all three disciplines.

What if requirements change during development?

Update the spec and notify stakeholders. If the change is significant, re-estimate and re-prioritize. The spec is a living document, not a contract. What is dangerous is silent divergence — when the code goes one way and the spec says another.