Skip to contentComing soon: SprintProof for ChatGPT and Codex

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.

feature-spec-template.md
blank, with guidance
  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

  6. 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.

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

  8. 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.

team-invitations-feature-spec.md
example, filled in
INV · FEATURE SPEC · OWNER MARIA K. · IN REVIEWTeam invitations: feature spec

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

PartBehaviourStates and edge casesBestLikelyWorst
Invite modalOne 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.11.53
Pending invites listShows 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.123
Accept-invite pageFour 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.524
Frontend total3.55.510

4 · Backend parts

PartBehaviourStates and edge casesBestLikelyWorst
Invitations APICreate 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.235
Invite tokensRandom, 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.512
Invite emailQueued 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).11.53
Rate limit invite sendsfrom review · MAIL-02At 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.50.51
Backend total4611

5 · Data parts

PartBehaviourStates and edge casesBestLikelyWorst
invitations tableWorkspace, 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.511.5
Data total0.511.5

6 · Cross-cutting parts

PartBehaviourStates and edge casesBestLikelyWorst
Permission rulesOwners 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.11.53
TestsOne 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.523
Cross-cutting total2.53.56

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-spec-template-short.md
one page
# [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 and when to use a feature description, a feature spec and a PRD
Feature descriptionOne pageOne named person, usually whoever proposes the featureSmall features or early discussions
Feature specA few lines per part, split by layerThe people who will build itWhen engineers need behaviour, states, edge cases and an estimate range to build from
PRDOne to three pagesUsually the product managerTo 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.

  1. 01Start from the approved scope. Copy the done-when and not-now lists from the PRD. If there is no PRD, write them first.
  2. 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.
  3. 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.
  4. 04Add the cross-cutting parts. Permissions, tests, limits and logging. Give each its own range so they are not absorbed into the others.
  5. 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.
  6. 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.

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.

Turn this into a reviewed plan

FAQ

Feature spec and feature description questions

What is a feature spec?
A feature spec describes how one feature should behave, part by part: what each screen, endpoint and table does, the states it handles, the edge cases and how long it could take. It is the document engineers build from.
What is a feature description template?
A one-page template for describing a single feature: who it is for, the problem, what it does, what done means, what is out of scope and the open questions. It is lighter than a PRD or a full feature spec, and suits small features or early discussions.
What is the difference between a feature spec and a PRD?
A PRD says what problem to solve, for whom, and what counts as done. A feature spec takes that scope and describes behaviour in more detail, split by layer, with states, edge cases and an estimate range. Small teams often combine them in one document.
What is the difference between a feature spec and a technical design doc?
The spec describes what the feature does in each part. The technical design doc describes how it is built: architecture, data model, alternatives and rollout. A spec can link to a design doc for the parts that need one.
How detailed should a feature spec be?
Detailed enough that two engineers would build the same behaviour and that a tester can write checks from it. If a part needs more than a few lines to describe, split it into two parts.
Why split a feature by layer?
Layers tend to have different owners and different risks, and work in one layer often waits for another. Splitting by layer shows the dependencies, lets each owner estimate their own part, and makes it easy to see what is missing, such as tests or permissions.

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.