| name | feature-specification |
| description | Write a detailed feature spec with requirements, edge cases, and technical constraints. Use when a feature needs formal documentation before engineering begins. |
Feature Specification
Detail a feature from concept to builder-ready spec in 30-60 minutes. Claude enumerates the requirements, edge cases, error states, and integration points that humans typically miss. You provide the user context and make the trade-off calls on complexity vs. value.
When to Use
- A feature within an epic needs detailed specification before development
- Engineers or AI coding tools need unambiguous requirements to start building
- The feature touches multiple systems and needs explicit integration requirements
- Design and engineering need a shared reference for what "done" looks like
- A feature is being handed off to another team or contractor
When NOT to Use
- The work is small enough for a single user story — use Story Writing
- You need the full initiative-level document — use PRD Writing
- You're defining the strategic wrapper around multiple features — use Epic Definition
The AI-Native Approach
| Step | Time | Claude Does | You Do |
|---|
| Define the feature | 10 min | Structure the feature description, user value, and context | Confirm the framing matches intent |
| Detail requirements | 15 min | Draft functional and non-functional requirements | Validate with engineering, flag unknowns |
| Enumerate edge cases | 10 min | Systematically identify edge cases and error states | Decide which to handle in v1 vs. defer |
| Define acceptance criteria | 10 min | Write testable acceptance criteria for each requirement | Confirm they match what "done" means |
| Document integration points | 10 min | Map API contracts, data flows, and system dependencies | Verify with engineering leads |
Process
Step 1: Define the Feature (10 minutes)
I need to spec out a feature: [feature name]
Context:
- Epic it belongs to: [epic name/link]
- User segment: [who uses this]
- User value: [what job it does for the user — in their words]
- Business value: [why the business cares]
Current state:
- What exists today: [current experience or workaround]
- What changes: [what's new or different]
Constraints known upfront:
- [Technical constraints, platform limitations, compliance requirements]
- [Timeline constraints — when does this need to ship?]
Step 2: Detail Requirements (15 minutes)
Draft the requirements for this feature:
Functional requirements (what it must do):
- [Requirement 1] — [why]
- [Requirement 2] — [why]
- [Requirement 3] — [why]
For each requirement, specify:
- Input: what triggers this behavior
- Output: what the user sees or what the system does
- Rules: business logic, validation, calculations
Non-functional requirements:
- Performance: [latency, throughput targets]
- Scale: [expected usage volume, growth projections]
- Security: [authentication, authorization, data handling]
- Accessibility: [WCAG level, specific accommodations]
- Compatibility: [browsers, devices, OS versions, screen sizes]
Step 3: Enumerate Edge Cases (10 minutes)
This is where AI adds disproportionate value. Humans tend to spec the happy path. Claude catches the rest.
For each functional requirement, enumerate edge cases:
- Empty states: what does the user see before any data exists?
- Error states: what happens when the request fails, times out, or returns unexpected data?
- Boundary conditions: what happens at the minimum, maximum, and zero values?
- Permission states: what happens when the user doesn't have access?
- Concurrent states: what happens when two users modify the same data?
- Interruption states: what happens when the user abandons mid-flow, loses connection, or navigates away?
- Migration states: what happens for existing users vs. new users?
- Degraded states: what happens when a dependency is slow or unavailable?
For each edge case: what should the user see, and what should the system do?
Step 4: Define Acceptance Criteria (10 minutes)
Write acceptance criteria for each requirement and key edge case:
Format:
Given [precondition]
When [action]
Then [expected result]
Rules:
- Every criterion must be testable — if you can't write a manual or automated test, rewrite it
- Include both positive cases (it works) and negative cases (it handles failure)
- Specify exact values where possible, not "appropriate" or "reasonable"
- Include performance criteria where relevant (e.g., "responds within 200ms")
Step 5: Document Integration Points (10 minutes)
Map the integration points for this feature:
For each system this feature touches:
- System: [name]
- Integration type: [API call, event, webhook, database query, file transfer]
- Direction: [reads from / writes to / both]
- Contract: [endpoint, payload format, authentication]
- Failure mode: [what happens when this integration fails]
- Owner: [team responsible for the other side]
Data flow:
- What data does this feature create, read, update, or delete?
- Where does it come from and where does it go?
- What's the source of truth?
- Any data retention or privacy implications?
Output
- Feature description with user and business value
- Functional and non-functional requirements
- Edge cases and error states enumerated
- Testable acceptance criteria (Given/When/Then)
- Integration map with contracts and failure modes
Common Pitfalls
- Happy path only. The feature works great when everything goes right. What about when it doesn't? Edge cases and error states are where user trust is built or broken.
- "Intuitive" as a requirement. Delete the word "intuitive" from your spec. Replace it with specific, measurable criteria for what the user can accomplish and how.
- Missing the migration case. Existing users with existing data will encounter this feature differently than new users. Spec both paths.
- No performance criteria. "Fast" is not a requirement. "Responds within 200ms at p95 under 1000 concurrent users" is. Get numbers from engineering.
- Specifying implementation. The feature spec describes what and why, not how. Leave the technical approach to engineering unless there's a constraint that forces a specific implementation.
Related Skills
- Epic Definition — for the strategic wrapper around multiple features
- Story Writing — for breaking this feature into developer-ready stories
- PRD Writing — when you need the full initiative-level document
- Reference: TEMPLATES.md — Feature template for formatting