SPEC WRITINGTEMPLATE
Feature Specification
A PRD describes the product; a feature spec describes one change to it, tightly enough that an agent can build it without interviewing you first. The discipline is in the edges: inputs, outputs, error states, and what is explicitly out of scope. If writing it feels slower than just asking the agent, count the round trips your last vague request cost you.
markdown
# Feature Spec: [Feature Name]
## Overview
One paragraph describing the feature, its purpose, and how it fits
into the larger product.
## User Stories
- As a [user type], I want to [action], so that [outcome].
- As a [user type], I want to [action], so that [outcome].
## Detailed Behavior
### [Sub-feature 1, e.g., "Customer login"]
**Inputs:**
- Field 1 (type, validation rules).
- Field 2 (type, validation rules).
**Outputs:**
- Success: [what the user sees, what gets stored, what events fire].
- Failure: [error states and what each looks like].
**Rules:**
- Rule 1.
- Rule 2.
**Edge cases:**
- Empty input: ...
- Malformed input: ...
- Duplicate submission: ...
- Permission denied: ...
**Error handling:**
- User-facing error: [message text].
- Logged: [what gets logged].
- Notified: [who, if anyone, gets notified].
### [Sub-feature 2]
(Repeat the structure above.)
## Data Model
### Tables touched
- `table_name`: read [columns], written [columns].
### New tables required
```sql
CREATE TABLE example (
id SERIAL PRIMARY KEY,
field_1 TEXT NOT NULL,
field_2 INTEGER,
created_at TIMESTAMP NOT NULL DEFAULT NOW()
);
```
## Permissions
- Role X: can [actions].
- Role Y: can [actions].
- Role Z: cannot access this feature at all.
## API Endpoints
(If this feature exposes API endpoints, list them with the format
from section 5.6.)
## UI Notes
- Layout: [reference to the layout from section 5.2].
- Components: [reference to components from section 5.3].
- Design tokens: see `design-tokens.md`.
## Verification Checklist
- [ ] Happy path 1: ...
- [ ] Happy path 2: ...
- [ ] Edge case 1: ...
- [ ] Edge case 2: ...
- [ ] Failure mode: ...
## AFD Check
Per §1.4: is any part of this feature AFD? If yes, name the human
expert reviewing it: ____________
## Out of Scope (this feature)
- ...