Spec Driven Development

Spec-Driven Development

Build comprehensive specifications through structured interviews before writing any code. Captures requirements, constraints, edge cases, and acceptance criteria upfront.

When to Use

• Starting a new feature with unclear requirements
• Planning complex changes that span multiple components
• Onboarding to an unfamiliar codebase
• Creating documentation for future reference
• Establishing clear acceptance criteria before implementation

Core Concepts

Spec File Structure

Specs are stored in .spec/ at the project root:

.spec/
├── user-auth.spec.md       # The specification document
├── user-auth.tasks.md      # Task breakdown with checkboxes
└── user-auth.log.md        # Implementation notes and decisions

Spec Document Format

# Spec: User Authentication

## Status: draft | active | completed | archived
## Created: 2026-02-05
## Updated: 2026-02-05

## Overview
One-paragraph summary of what this feature does and why.

## Functional Requirements
- User can register with email and password
- User can log in and receive a session token
- User can log out and invalidate their session

## Technical Constraints
- Language: TypeScript
- Framework: Express.js
- Database: PostgreSQL
- Must integrate with existing user model

## Data Model
- User: id, email, password_hash, created_at, updated_at
- Session: id, user_id, token, expires_at

## Edge Cases & Error Handling
- Invalid email format → 400 with validation message
- Duplicate email → 409 Conflict
- Wrong password → 401 with generic message (no info leak)
- Expired session → 401 with refresh guidance

## Security Considerations
- Passwords hashed with bcrypt (cost factor 12)
- Session tokens are UUIDs, not JWTs (revocable)
- Rate limiting on login endpoint (5 attempts/minute)
- No password in logs or error messages

## Testing Strategy
- Unit tests: validation logic, password hashing
- Integration tests: full auth flow with test database
- E2E tests: login/logout via API
- Coverage target: 80%

## Non-Functional Requirements
- Login response time < 500ms
- Support 1000 concurrent sessions
- Session cleanup job runs daily

## Implementation Approach
1. Database schema and migrations
2. User model and repository
3. Auth service (register, login, logout)
4. Auth middleware for protected routes
5. Rate limiting middleware
6. Tests for each layer

## Acceptance Criteria
- [ ] User can register with valid email/password
- [ ] User can log in and receive session token
- [ ] Protected routes reject unauthenticated requests
- [ ] Rate limiting prevents brute force attacks
- [ ] All tests pass with 80% coverage

Interview Process

The 8 Categories

The interview covers 8 categories to build a complete spec:

Interview Flow

1. Start with functional requirements — understand the "what"
2. Move to technical constraints — understand the "how"
3. Define the data model — understand the "with what"
4. Explore edge cases — understand the "what if"
5. Address security — understand the "how safe"
6. Plan testing — understand the "how verified"
7. Non-functional requirements — understand the "how well"
8. Implementation approach — understand the "in what order"

Adaptive Questioning

Not all categories need equal depth. Adapt based on the feature:

Integration with Other Tools

During Planning

During Implementation

Task Tracking

Tasks are tracked in {slug}.tasks.md:

# Tasks: User Authentication

## Progress: 3/8 complete (37%)

### Phase 1: Foundation
- [x] 1.1 Create database migration for users table
- [x] 1.2 Create database migration for sessions table
- [ ] 1.3 Create User model with repository pattern

### Phase 2: Core Implementation
- [x] 2.1 Implement AuthService.register()
- [ ] 2.2 Implement AuthService.login()
- [ ] 2.3 Implement AuthService.logout()
- [ ] 2.4 Create auth middleware

### Phase 3: Hardening
- [ ] 3.1 Add rate limiting
- [ ] 3.2 Add input validation
- [ ] 3.3 Add comprehensive tests

Implementation Log

Track decisions and notes in {slug}.log.md:

# Implementation Log: User Authentication

## 2026-02-05 — Started implementation

### Task 1.1: User table migration
- Created migration with bcrypt for password hashing
- Decided on UUID primary keys for security
- Added unique constraint on email

### Task 2.1: AuthService.register()
- Used repository pattern from existing UserRepository
- Added email validation with Zod
- Password validation: min 12 chars, requires number and special char

Commands

Best Practices

1. Interview before coding — resist the urge to jump into implementation
2. Keep specs updated — update when requirements change
3. Link specs to PRs — reference spec slug in PR descriptions
4. Review completed specs — retrospective for process improvement
5. Share with team — specs are documentation for future maintainers

Checklist

• All 8 categories addressed (or explicitly N/A)
• Acceptance criteria are testable
• Edge cases include error responses
• Security considerations documented
• Testing strategy matches feature complexity
• Task breakdown is ordered by dependencies