Free template
Feature spec and feature description template
The page engineers build from. The feature is split into parts by layer (frontend, backend, data and cross-cutting), and each part says what it does, which states it needs, what can go wrong and how long it could take.
Markdown pastes into Notion, Google Docs and Confluence. No sign-up.
In short
A feature spec describes how one feature should work before it is built: the parts by layer, their behaviour, states and edge cases, and a best, likely and worst range for each. This free template also has a one-page feature description for smaller features, with the user, the problem and what done means.
The template
Eight sections, one per layer of the work.
A feature spec sits between the PRD and the tickets. It is more specific than the PRD about behaviour and states, and it leaves the architecture to the technical design.
- 01
Overview
The feature in a few lines, and what has to be true for it to count as done.
- What does the user get when this ships?
- Which PRD or brief does this spec build on?
- What can a tester check to call it done?
TipLink the PRD instead of repeating it. Two copies of the goal soon drift apart.
- 02
Scope and not now
What this spec covers, and what it leaves out on purpose.
- Which user flows are in?
- What will people assume is included but is not?
- What is planned for a later release?
TipList the cuts with a reason each. Engineers will otherwise build what they think you meant.
- 03
Frontend parts
Each screen or component the user sees, with the states it has to handle.
- What does the user do here, and what do they see?
- Which states are needed: empty, loading, error, no access?
- Which sizes and input methods count: phone, keyboard, screen reader?
TipWrite the states as a list per screen. Empty and error states are the ones that get cut when time runs short.
- 04
Backend parts
Endpoints, jobs and rules the interface relies on, with their inputs, results and errors.
- Which calls are new or changed, and who may make them?
- Which error codes can come back, and what does the client do with each?
- Which work runs in the background, and what happens when it fails?
TipName the error cases in the spec. “Handle errors” is where a day of work hides.
- 05
Data parts
Tables, columns, indexes and migrations the feature needs.
- Which tables or columns are added or changed?
- Which lookups need an index?
- How is the migration run, and how is it undone?
TipAsk how long the migration takes on a copy of production data. A table that is fast in dev can lock in live.
- 06
Cross-cutting parts
Work that belongs to no single layer: permissions, tests, logging, limits, documentation.
- Who may do what, and where is that enforced?
- Which tests prove the feature works end to end?
- What is logged, limited or documented?
TipGive these parts their own estimate. Tests and permission rules take real days and are the first to be forgotten.
- 07
Edge cases and open questions
Situations the happy path skips, and decisions that are still open, each with an owner.
- What happens when the input already exists, expires or is wrong?
- What does a second click, a retry or two tabs do?
- Which open question would change the range if answered differently?
TipEach edge case ends up as a requirement, a part or an open question. If it is none of these, it is not handled.
- 08
Estimate
A best, likely and worst case in days for every part, and the total as a range.
- Best, likely and worst case per part, from the people who build it
- Which part has the widest spread, and why?
- Which open questions add parts if answered “yes”?
TipShow the range, not the middle. A part with a wide spread is a candidate to spike first.
Example
A feature spec for team invitations, filled in.
The same feature as the PRD example, now broken down by layer. Every part has behaviour, states and edge cases, and a range in dev-days.
1 · Overview
Owners and admins invite colleagues by email with a role. Invitees get a link that works once, for 7 days, and lands them in the right workspace. Builds on the team invitations PRD.
- An owner or admin can invite one or many people by email and pick a role
- An invitee can accept from the email link when signed out, signed in, or signed in as someone else
- Admins see pending invites and can resend or revoke them
- Invites expire after 7 days and work once
2 · Scope and not now
- In: invite, resend, revoke and accept, for owners, admins and invitees.
- Not now: Domain auto-join, needs verified domains first
- Not now: SSO and SCIM provisioning, comes with the SSO work in a later release
- Not now: CSV import of invitees, pasting many addresses at once covers it for now
3 · Frontend parts
| Part | Behaviour | States and edge cases | Best | Likely | Worst |
|---|---|---|---|---|---|
| Invite modal | One address, or many pasted at once, split on commas, spaces and new lines. The role picker offers only roles you may grant. | A bad address is flagged next to it and the valid ones still go out. At the rate limit, the modal says when it resets. | 1 | 1.5 | 3 |
| Pending invites list | Shows email, role, invited by and age, with resend and revoke on each row. | Empty, loading and error states. Revoke asks first, then updates the list without a reload. Reachable by keyboard. | 1 | 2 | 3 |
| Accept-invite page | Four states: signed out, signed in as the invitee, signed in as someone else, expired or used link. | Wrong account offers “switch account” and keeps the link alive through sign-in. Works at 375 px and with a screen reader. | 1.5 | 2 | 4 |
| Frontend total | 3.5 | 5.5 | 10 | ||
4 · Backend parts
| Part | Behaviour | States and edge cases | Best | Likely | Worst |
|---|---|---|---|---|---|
| Invitations API | Create one or many, list pending ones with pagination, revoke, accept. Every route checks membership and role. | Another workspace gets 404. A repeat invite for the same email returns the existing one. Errors: invite_expired, invite_used, invite_wrong_account. | 2 | 3 | 5 |
| Invite tokens | Random, at least 128 bits, only a hash is stored. Works once, expires after 7 days, rejected after revoke. | Checks run in constant time. Tests for expired, used and revoked tokens. | 0.5 | 1 | 2 |
| Invite email | Queued in the same transaction as the invite and sent by a worker. Shows inviter, workspace and role, with a button that carries the token. | Retries on failure. Plain-text part included. Bounces are not handled yet (open question). | 1 | 1.5 | 3 |
| Rate limit invite sendsfrom review · MAIL-02 | At most 20 invites per admin per hour, per workspace. The limit lives in config, not in code. | The 21st request returns 429 with the time to try again. Every hit is logged with workspace and admin ID. | 0.5 | 0.5 | 1 |
| Backend total | 4 | 6 | 11 | ||
5 · Data parts
| Part | Behaviour | States and edge cases | Best | Likely | Worst |
|---|---|---|---|---|---|
| invitations table | Workspace, email, role, token hash, inviter, expiry, accepted and revoked timestamps. Unique index on token hash, index on workspace and email. | Migration runs in under a second on a copy of production. A rollback script drops the table and nothing else. | 0.5 | 1 | 1.5 |
| Data total | 0.5 | 1 | 1.5 | ||
6 · Cross-cutting parts
| Part | Behaviour | States and edge cases | Best | Likely | Worst |
|---|---|---|---|---|---|
| Permission rules | Owners may invite any role. Admins may invite admins and members. Members cannot invite. | Enforced in the API and reflected in the modal. The rules table is in the repository and tested. | 1 | 1.5 | 3 |
| Tests | One browser test: admin invites, invitee accepts from the email link, lands in the workspace with the right role. | API tests for expired, revoked, used and wrong-account tokens. Runs in CI in under three minutes. | 1.5 | 2 | 3 |
| Cross-cutting total | 2.5 | 3.5 | 6 | ||
7 · Edge cases and open questions
- What if the invited email already has an account?Jonas T. · Tue
- What happens when an invite goes over the plan’s seat limit: block, warn or charge?Tom A. · Wed
- Can anyone with the link join, or only the invited address?Jonas T. · Tue
- How does the admin find out an invite bounced?Ken L. · Thu
8 · Estimate
10.5 to 28.5 dev-days, likely 16. Widest spread: Invitations API (2 to 5), because create, revoke and accept all touch the same tokens.
Existing accounts add a backend part of 1 to 2 days, and the seat limit adds 1 to 3, if each is answered “yes”. The range widens until both are decided.
For small features
Short version: a one-page feature description
In short: A feature description is the one-page version of a feature spec. It names the user and the problem, describes what the feature does, lists what done means and what is out of scope, and notes open questions. Use it for small features. Move to the full spec when parts need detail.
# [Feature name]: feature description **Owner:** [name] · **Status:** Draft · **Last updated:** [date] > Free feature description template from SprintProof: https://sprintproof.com/templates/feature-spec-template#feature-description > The one-page version of the feature spec. Replace everything in [brackets]. ## Who it is for and the problem [Who uses it, and what they cannot do today.] ## What the feature does [Three to five sentences on the behaviour, from the user’s side.] ## Done when - [ ] [A user can …] - [ ] [… still works when …] ## Not now - [Item]: [reason] ## Edge cases to decide - [Existing data, permissions, errors, limits, empty states] ## Open questions - [Question]: [owner] ## Rough size Best [ ] · Likely [ ] · Worst [ ] days. Full estimate: https://sprintproof.com/templates/software-estimate-template
Need more detail per part? Use the full spec above.
Feature description vs feature spec vs PRD
| Length | Owner | When to use | |
|---|---|---|---|
| Feature description | One page | One named person, usually whoever proposes the feature | Small features or early discussions |
| Feature spec | A few lines per part, split by layer | The people who will build it | When engineers need behaviour, states, edge cases and an estimate range to build from |
| PRD | One to three pages | Usually the product manager | To say what problem to solve, for whom, and what counts as done |
How to use it
How to fill it in, step by step.
Write the spec with the people who will build it. The ranges are only honest if the engineers set them.
- 01Start from the approved scope. Copy the done-when and not-now lists from the PRD. If there is no PRD, write them first.
- 02Split the feature by layer, then split each layer into parts a person can finish in about one to five days. A part bigger than that hides a decision.
- 03Write behaviour and states for each part. What the part does, which states it needs and what it does when something goes wrong. Keep each to a few lines.
- 04Add the cross-cutting parts. Permissions, tests, limits and logging. Give each its own range so they are not absorbed into the others.
- 05Ask the builders for best, likely and worst. Take the numbers from the person who will do the part. Record the widest spread and what causes it.
- 06Run the edge cases and send for review. Anything you find becomes a part or an open question with an owner. Then ask the owners of each area for sign-off.
- Documenting the feature once it ships? Use the technical documentation template.
Skip the blank page
Let SprintProof draft it with you.
Describe the feature and the planner asks the questions a reviewer would, then drafts the brief, done-when, not-now and parts with ranges. The check library adds the edge cases teams usually find mid-sprint.
FAQ
Feature spec and feature description questions
What is a feature spec?
What is a feature description template?
What is the difference between a feature spec and a PRD?
What is the difference between a feature spec and a technical design doc?
How detailed should a feature spec be?
Why split a feature by layer?
Related templates
Templates that go with it.
- Markdown
PRD template
The problem, who it is for, what done means, what is out, and the open questions, on one page.
- Markdown
Technical design doc and documentation template
Context, the chosen design, alternatives, data, security and rollout, for review before code, and a technical documentation template for after it ships.
- Markdown, CSV
Software estimate template
Best, likely and worst case per part, rolled up into a range you can defend.
- Markdown
User story template
Who, what and why, with the acceptance criteria and the questions to settle first.
- Markdown
Acceptance criteria template
Given, when, then for the happy path, the edge cases and the states nobody designs.
- CSV
Sprint planning template
Sprint goal, capacity, a backlog with ranges, risks and a definition of done.
Turn this into a reviewed plan with SprintProof.
Describe the feature and SprintProof turns it into a plan: checked against a library of questions reviewers ask, estimated as a range with 50, 80 and 90% dates, and signed off before anyone starts.