Feature Spec Template (Copy-Paste + Example)

Overview

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 isn’t a contract; it’s a shared understanding that evolves as the team learns.

Requirements problems are expensive: the classic finding on defect cost is that a requirement error found during implementation costs roughly an order of magnitude more than one caught during specification, and rework is commonly cited at 30–50% of software project effort (Standish CHAOS Report). Ten pages of spec are cheaper than ten days of rebuilding the wrong thing.

Specs are also becoming inputs to AI coding agents. A well-structured spec with explicit requirements, acceptance criteria, and rollout plans is exactly the kind of prompt a tool like GitHub Spec Kit or an agent-driven workflow consumes best — the same structure that helps humans helps agents implement what you actually meant.

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
• You plan to feed the spec to an AI coding agent and want structure it can follow

For earlier work in the lifecycle, use the feature request template to capture the idea and user stories to shape requirements. For the engineering-level design that follows approval, see the technical specification template.

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: ______
> Changelog: YYYY-MM-DD — [what changed and why]

## 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. Approvals

| Role | Name | Decision | Date |
|------|------|----------|------|
| Product | ______ | Approved / Rejected | ______ |
| Engineering | ______ | Approved / Rejected | ______ |
| Design | ______ | Approved / Rejected | ______ |
| QA | ______ | Approved / Rejected | ______ |

## 11. 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 your best defense against scope creep: it makes explicit what is out of scope before anyone assumes otherwise.

The lifecycle matters as much as the sections. A spec moves through states — draft, review, approved — but it never becomes frozen. When scope or decisions change, the spec is updated and the change is logged. That is what “living document” means in practice:

Approval is where most specs quietly fail: a feature built on implied consent becomes the product owner’s problem the first time a stakeholder says “that’s not what I asked for.” The Approvals table forces an explicit yes or no from each discipline before the status moves to Approved.

How to Fill the Template

Work through the sections in order, but draft the summary last — you can’t compress something you haven’t worked out yet.

Summary (§1). Two to three sentences for the problem, one paragraph for the solution, and measurable success criteria. “Reduce support tickets about X by 30%” works; “improve user experience” doesn’t. A busy stakeholder should grasp the feature in sixty seconds.

Goals and non-goals (§2). Three goals is usually enough — more means the feature is probably two features. Non-goals should name the requests someone will inevitably ask for; saying “mobile push is a separate feature” now saves the argument later.

User stories (§3). Keep the As a [persona], I want [action] so that [outcome] format strict and prioritize ruthlessly. P0 means the feature fails without it. If everything is P0, nothing is.

Requirements (§4–§5). Functional requirements should be numbered and testable — a QA engineer must be able to derive a test case from each FR without asking you. Non-functional requirements aren’t “nice to have”: vague words like “fast” become measurable targets like “p99 < 200ms”.

Design and technical approach (§6–§7). Link to design artifacts rather than embedding them so they stay in sync. The technical approach stays at architecture level — detailed design belongs in the technical spec that follows this document.

Acceptance criteria (§8). Each criterion should be binary: a tester can mark it passed or failed without interpretation. “User can complete checkout in under 3 clicks” passes that test; “works as expected” doesn’t.

Open questions and approvals (§9–§10). Every open question needs an owner and a due date, otherwise it becomes an open risk. Fill the Approvals table in a review meeting — walk through the summary, goals, and key requirements aloud, then collect explicit sign-off.

Feature Spec Example

# Feature Spec: Real-time Order Notifications

## Summary
Add real-time order status notifications to the user dashboard
using WebSocket connections. Users will see order updates
immediately without page refresh.

## Goals
- Reduce support tickets about order status by 30%
- Improve user engagement with the dashboard
- Provide sub-second notification delivery

## Non-Goals
- Mobile push notifications (separate feature)
- Email notifications (already implemented)
- Order history search (separate feature)

## User Stories
1. As a buyer, I want to see order status updates in real-time
   so I do not need to refresh the page.
2. As a seller, I want to know when an order is placed so I can
   prepare the shipment immediately.
3. As a support agent, I want to see the same notifications so I
   can answer customer questions accurately.

## Functional Requirements
- WebSocket connection on dashboard page load
- Reconnection with exponential backoff on disconnect
- Notification payload includes: order ID, status, timestamp
- Notifications appear as toast messages and in a notification panel

## Non-Functional Requirements
- Notification delivery latency: p95 < 500ms
- WebSocket connections: support 10,000 concurrent
- Fallback to polling if WebSocket fails after 3 retries
- Accessibility: notifications announced via ARIA live region

## Technical Approach
- WebSocket gateway: AWS API Gateway WebSocket
- Message broker: Redis Pub/Sub
- Auth: JWT token passed in connection query params
- Frontend: native WebSocket API with reconnection wrapper

## API Changes
- New endpoint: GET /api/v1/notifications/stream (WebSocket upgrade)
- New endpoint: GET /api/v1/notifications (REST fallback, polling)
- No breaking changes to existing endpoints

## Rollout Strategy
- Phase 1: Internal testing with 10 users (1 week)
- Phase 2: Beta with 5% of users (2 weeks)
- Phase 3: General availability (monitor for 1 week)
- Rollback: Disable WebSocket feature flag, users fall back to polling

## Acceptance Criteria
- [ ] WebSocket connects on dashboard load
- [ ] Order status changes appear within 500ms
- [ ] Connection recovers automatically after network interruption
- [ ] Notifications are accessible via screen reader
- [ ] System handles 10,000 concurrent connections in load test

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’re internal teams
Experiment / A/B test	Add hypothesis, success metrics, sample size, and rollback criteria	Experimental features need clear kill criteria
Spec for AI coding agents	Emphasize numbered FRs, explicit acceptance criteria, and file paths over prose	Agent-driven workflows (e.g., GitHub Spec Kit) implement what the spec literally says — ambiguity gets compiled in

What Works

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 aren’t “nice to have”; they’re requirements
3. Making acceptance criteria vague — “works as expected” isn’t 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 isn’t done when code is merged; it’s done when users are successfully using it
6. No owner, no review cadence — an orphaned spec goes stale fast; assign an owner and revisit it at the end of every sprint the feature touches
7. Skipping sign-off — building on implied approval means the first “that’s not what I asked for” lands on whoever wrote the code

Troubleshooting

These are the failure modes specs actually hit — not bugs, but process problems:

• Nobody reads the spec. Walk through it in a 30-minute review meeting instead of posting a link. Keep the spec where the team already looks — the project wiki or linked from the ticket — and reference it in every PR that implements it.
• The spec and the implementation diverge silently. Require the changelog entry in the template header whenever scope changes, and make “check the spec still matches the code” part of the definition of done.
• Approval stalls. Open questions without an owner and due date die in the table. Timebox review to one meeting; if a stakeholder doesn’t attend, collect their sign-off in writing the same week.
• Scope grows mid-sprint. Point to the non-goals section — that’s what it’s for. If the addition is genuinely needed, update the spec, re-estimate, and log the change rather than letting it slip in.
• The spec gets written after the code. That is documentation, not specification. It still has value for support and onboarding, but schedule a real spec next time — the retrospective cost is real.

Key Takeaways

• A spec’s job is shared understanding, not paperwork — write it before coding and keep it updated while shipping.
• Non-goals and explicit approvals are the two sections that prevent the most expensive arguments.
• Numbered, testable requirements and binary acceptance criteria are what make a spec usable for QA, estimation, and AI coding agents.
• A living spec with a changelog beats a perfect spec that goes stale.

See Also

• ISO/IEC/IEEE 29148 — Requirements Engineering — the standard covering what good requirements look like
• Standish CHAOS Report — the research behind requirements-related rework cost
• GitHub Spec Kit — spec-driven development for AI coding agents
• Companion repository — downloadable template and the filled example from this page