Feature Spec Template

When to use this template

• New feature delivery with unclear acceptance boundaries.
• Refactors that may change user-visible behavior.
• Cross-team changes where API, DB, and UI must stay aligned.
• AI-assisted coding tasks that need strict scope control.

How to fill it correctly

The Goal section should be one sentence describing the user or business outcome. Non-goals set explicit boundaries to prevent scope drift. Acceptance Criteria are binary Given/When/Then statements. The Edge Cases section covers nulls, duplicates, permission and concurrency paths. Deliverables list the exact code areas, tests, and rollback notes.

Write so a reviewer can derive test cases without asking clarifying questions.

Common mistakes

• Using vague language like "handle properly" or "optimize experience".
• Listing implementation tasks but skipping acceptance outcomes.
• Not documenting error and permission behavior.
• Shipping state changes without rollback instructions.

Pre-implementation review checklist

• Every criterion maps to a test case.
• Out-of-scope items are explicit and agreed.
• API/DB impact is documented and backward-compatible.
• Rollout and rollback conditions are actionable.

Need examples? See spec template examples and spec review checklist.

Real-world example: user notification preferences

Here is what a filled-in version of this template looks like for a real feature — letting users control which notifications they receive.

## Goal
Allow users to opt in/out of individual notification channels
(email, push, in-app) per event type, reducing unsubscribe rates
by giving granular control.

## Non-goals
- Notification delivery infrastructure changes
- Admin-level notification overrides
- Frequency capping or digest mode

## Acceptance Criteria
- [ ] Given a logged-in user on /settings/notifications
  When they toggle "Marketing emails" off and save
  Then no marketing emails are sent to that user
- [ ] Given a user with all channels disabled
  When a critical security alert fires
  Then the alert is still delivered (security is non-optional)
- [ ] Given an API consumer calling PATCH /users/:id/preferences
  When the payload omits a channel key
  Then that channel preference is unchanged (partial update)

## Edge Cases
- null/empty: user has no existing preferences → default all ON
- duplicates/idempotency: toggling the same setting twice is a no-op
- concurrency/race: two tabs saving simultaneously → last-write-wins
- permissions/visibility: users cannot modify other users' preferences

## Output / Deliverables
- API: PATCH /users/:id/notification-preferences
- DB: add notification_preferences JSONB column to users table
- UI: toggle grid component on settings page
- Test checklist: unit tests for partial update, integration test
  for security override, E2E test for toggle persistence
- Rollback: feature flag `notification_prefs_v2` → revert to
  global on/off toggle

Related resources

• Acceptance Criteria Examples — reusable Given/When/Then patterns
• Edge Case Checklist — systematic edge case identification
• API Spec Template — when your feature includes API changes
• What Is Spec-First Development? — the complete methodology guide