Examples & Workflows

Learn from real-world examples and see the spec-driven methodology in action.

Example 1: Simple Feature

Let's walk through creating a user profile feature from start to finish.

Step 1: Create the Spec

/spec:create user-profile-page

Claude generates requirements with EARS notation:

## User Story

**As a** registered user
**I want** to view and edit my profile
**So that** I can keep my information up to date

## Requirements

- WHEN a user navigates to /profile, THE SYSTEM SHALL display their profile information
- WHEN a user clicks Edit, THE SYSTEM SHALL enable profile editing
- WHEN a user saves changes, THE SYSTEM SHALL validate and persist to database
- WHEN validation fails, THE SYSTEM SHALL display error messages inline

After approval, design is generated:

## Architecture

### Components
- ProfileView: Display user information
- ProfileEdit: Form for editing
- ProfileService: API integration

### Data Model
interface User {
  id: string;
  email: string;
  name: string;
  avatar?: string;
}

Finally, tasks are broken down:

## Tasks

### Task 1: Create ProfileView component
- [ ] Implement component with user data display
- [ ] Add edit button
- [ ] Style with existing design system

### Task 2: Build ProfileEdit form
- [ ] Create form with validation
- [ ] Implement save/cancel actions
- [ ] Add error handling

Step 2: Implement

/spec:implement .claude/specs/user-profile-page

Claude loads the spec, creates TodoWrite tasks, and systematically implements each task following test-driven development. Tasks are marked complete only when acceptance criteria pass.

Example 2: Evolving a Spec

When you need to improve an existing feature, Claude Kiro handles the evolution elegantly.

Original Spec

# .claude/specs/basic-auth/

Status: Working, but needs improvements

- Email/password authentication
- Basic session management
- No 2FA, no OAuth

Create Evolution

/spec:create enhanced-auth-with-2fa

Claude automatically:

  • Finds the original basic-auth spec
  • Includes a "Specification Heritage" section
  • Updates basic-auth/tasks.md with "EVOLVED - See: enhanced-auth-with-2fa"
  • Creates basic-auth/evolution.md documenting lessons learned
  • Builds on what worked, improves what didn't

Evolution Document

# Evolution: basic-auth → enhanced-auth-with-2fa

## What Worked
✅ Email/password flow is solid
✅ Session management is reliable
✅ Error handling is clear

## What Changed
🔄 Added 2FA support (TOTP)
🔄 Implemented OAuth providers
🔄 Enhanced session security

## Lessons Learned
- Keep core auth flow simple
- Build 2FA as optional layer
- OAuth should be pluggable

## Migration Path
1. Deploy enhanced-auth alongside basic-auth
2. Migrate users gradually
3. Deprecate basic-auth after 30 days

Example 3: Multi-Task Specification

Complex features require multiple coordinated tasks. Here's how Claude Kiro handles them.

/spec:create real-time-notifications

Generated Task Breakdown

### Task 1: WebSocket Server Setup
**Dependencies:** None
**Files:** src/websocket/server.ts
**Acceptance:**
- [ ] WebSocket server running on port 3001
- [ ] Connection handling with authentication
- [ ] Heartbeat/keepalive implemented

### Task 2: Notification Data Model
**Dependencies:** None
**Files:** src/models/notification.ts, migrations/
**Acceptance:**
- [ ] Database schema created
- [ ] TypeScript interfaces defined
- [ ] CRUD operations tested

### Task 3: Notification Service
**Dependencies:** Task 1, Task 2
**Files:** src/services/notification.ts
**Acceptance:**
- [ ] Create notification API
- [ ] Broadcast to connected users
- [ ] Persistence and retrieval

### Task 4: Client Integration
**Dependencies:** Task 3
**Files:** src/client/notification.ts
**Acceptance:**
- [ ] WebSocket client connection
- [ ] Real-time updates
- [ ] Offline queuing

Notice how dependencies are explicitly tracked. Claude implements Task 1 and 2 in parallel, then Task 3, then Task 4.

Common Patterns

📝 EARS Template

WHEN [event/condition] THE SYSTEM SHALL [behavior]

Use for all functional requirements

🎯 Task Structure

### Task N: [Name]
**Dependencies:** [Tasks]
**Files:** [Paths]
**Acceptance:**
- [ ] Criterion 1
- [ ] Criterion 2

🔄 Evolution Header

## Specification Heritage
**Evolves From:** [original-spec]
**Preserves:** [what stays]
**Supersedes:** [what changes]
**Evolution Reason:** [why]

Copy-Paste Templates

Requirements Template

# Feature: [Feature Name]

## User Story
**As a** [user type]
**I want** [goal]
**So that** [benefit]

## Requirements

### Functional
- WHEN [condition], THE SYSTEM SHALL [behavior]
- WHEN [condition], THE SYSTEM SHALL [behavior]

### Non-Functional
- Performance: [requirement]
- Security: [requirement]
- Accessibility: [requirement]

## Constraints
- [Technical constraint]
- [Business constraint]

## Out of Scope
- [Item not included]

Design Template

# Design: [Feature Name]

## Architecture
[High-level overview]

## Component Analysis

### Component 1
- **Purpose:** [what it does]
- **Interfaces:** [inputs/outputs]
- **Dependencies:** [what it needs]

## Data Models
```typescript
interface [Name] {
  [fields]
}
```

## Testing Strategy
- Unit tests: [coverage]
- Integration tests: [scenarios]
- E2E tests: [user flows]

Tasks Template

# Implementation Tasks: [Feature Name]

**Status:** Not Started
**Spec:** [requirements.md](./requirements.md) | [design.md](./design.md)

### Task 1: [Name]
**Description:** [What this task does]
**Dependencies:** None
**Files:** [file paths]
**Acceptance:**
- [ ] [Criterion 1]
- [ ] [Criterion 2]
**Estimated Complexity:** Low/Medium/High

Best Practices from Real Projects

✅ Do This

  • Be specific in requirements: "Save button disabled" is better than "handle save state"
  • Include error cases: Don't just spec the happy path
  • Estimate complexity: Helps prioritize and plan
  • Link related specs: Build a knowledge graph
  • Update specs when learning: Capture what you discover

⚠️ Avoid This

  • Vague requirements: "It should be fast" → Define performance targets
  • Skipping approval gates: Always review before proceeding
  • Implementation details in requirements: Say what, not how
  • Marking incomplete tasks done: Acceptance criteria must pass
  • Starting without a spec: The time investment pays off

Next Steps

Ready to apply these patterns in your own projects?

Get Started Learn Methodology