Complete Specification Breakdown

Introduction: The Role of Complete Specifications

Welcome back! In Unit 2's lesson, you established your project-level constitution with CLAUDE.md. That defines how your entire project works. This lesson teaches feature-level specifications — detailed blueprints for individual features that reference your constitution. The hierarchy: 🏛️ CLAUDE.md (Lesson 2) \to Project-wide rules 📋 Feature Spec (this lesson) \to Rules for one feature Now let's learn what goes into a complete feature specification. A complete specification is like a detailed blueprint for your code. It tells you exactly what needs to be built, how it should behave, and what to watch out for. This is especially important when working with APIs, where clear communication between different parts of a system is critical. By the end of this lesson, you will know how to break down a feature into a full specification, use AI to help generate specs, and review real examples to see what a good spec looks like.

Quick Recall: Key Elements of a Specification

Let's quickly remind ourselves what a specification is. A specification, or spec, is a document that describes what a feature or component should do. It does not describe how to implement it, but rather what the expected behavior is. In the last lesson, you saw a simple spec for an API endpoint. Here's a quick reminder of what a basic spec might look like: Markdown # Endpoint: /hello ## Purpose Returns a greeting message. ## Interface Inputs: None Outputs: message: string ## Behavior Returns a JSON object with a greeting message. ## Constraints None ## Edge Cases None ## Error Conditions None ## Examples Input: (none) Output: {"message": "Hello, world!"} This is a simple example, but as features get more complex, specs need to be more detailed. That's what we'll focus on next.

Dissecting the Specification Template

A complete specification has several key sections. Let's go through each one, using the User Profile feature (with avatar, bio, and location) as our running example.

1. Purpose

This section explains what the component or feature is for, in one sentence. Markdown ## Purpose Stores and displays user profile information, including avatar, bio, and location. Explanation: The purpose should be clear and concise. It helps everyone understand why this feature exists.

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

Markdown

## Interface
Inputs:
- avatar_url: string (valid URL, optional)
- bio: string (max 160 characters, optional)
- location: string (max 50 characters, optional)

Outputs:
- profile: object (contains avatar_url, bio, location)

Markdown

## Behavior
When a user updates their profile, the system saves the new avatar, bio, and location. If any field is missing, the previous value is kept.

Markdown

## Constraints
- Avatar URL must be a valid URL if provided.
- Bio must not exceed 160 characters.
- Location must not exceed 50 characters.

Markdown

## Edge Cases
- All fields are empty (profile remains unchanged).
- Bio or location at maximum length.
- Avatar URL is invalid.

Markdown

## Error Conditions
- If avatar_url is not a valid URL, return an error.
- If bio or location exceeds the maximum length, return an error.

Markdown

## Examples
Input:
{
  "avatar_url": "https://example.com/avatar.png",
  "bio": "Hello, I love coding!",
  "location": "San Francisco"
}
Output:
{
  "profile": {
    "avatar_url": "https://example.com/avatar.png",
    "bio": "Hello, I love coding!",
    "location": "San Francisco"
  }
}

Input:
{
  "bio": "A" * 161
}
Output:
{
  "error": "Bio must not exceed 160 characters."
}

Markdown

# [Feature Name]

**Version:** [X.Y.Z]

## Purpose
[One sentence describing what this feature does]

## Interface
**Inputs:**
- [input_name]: [type] ([constraints, e.g., "required", "optional", "max 50 chars"])
- ...

**Outputs:**
- [output_name]: [type] ([description])
- ...

## Behavior
[Describe what happens when the feature is used, without implementation details]

## Constraints
- [Rule that must always be true]
- ...

## Edge Cases
- [Unusual or boundary situation]
- ...

## Error Conditions
- [Condition that causes failure]: [Error response]
- ...

## Examples
**Example 1: [Description]**
Input:
```
[input data]
```
Output:
```
[output data]
```

**Example 2: [Description]**
Input:
```
[input data]
```
Output:
```
[output data]
```

Markdown

## HTTP Status Codes
- 200: Success (resource retrieved/updated)
- 201: Created (new resource)
- 204: No Content (successful deletion)
- 400: Bad Request (validation failed)
- 401: Unauthorized (authentication required)
- 403: Forbidden (insufficient permissions)
- 404: Not Found (resource doesn't exist)
- 422: Unprocessable Entity (business rule violation)

## Error Response Format
TaskMaster uses FastAPI's HTTPException with the `detail` field:

```json
{
  "detail": "Human-readable error message"
}
```

**Examples:**
- 404: `{"detail": "Task not found"}`
- 403: `{"detail": "Not authorized to access this task"}`
- 400: `{"detail": "Title is required"}`
- 422: `{"detail": "Cannot transition from completed to pending"}`

text

Generate complete specification for: [feature description]

Template:
- Purpose: One sentence
- Interface: Inputs/outputs with types
- Behavior: What happens (not how)
- Constraints: Rules that must be true
- Edge Cases: Boundary conditions
- Error Conditions: When to fail
- Examples: Concrete cases

text

Generate complete specification for: User Profile (avatar, bio, location)

Template:
- Purpose: One sentence
- Interface: Inputs/outputs with types
- Behavior: What happens (not how)
- Constraints: Rules that must be true
- Edge Cases: Boundary conditions
- Error Conditions: When to fail
- Examples: Concrete cases

Markdown

Purpose: Stores and updates user profile information (avatar, bio, location).
Interface: 
  Inputs: avatar_url (string, optional, valid URL), bio (string, optional, max 160 chars), location (string, optional, max 50 chars)
  Outputs: profile (object with avatar_url, bio, location)
Behavior: Updates user profile fields; keeps previous values if not provided.
Constraints: avatar_url must be a valid URL; bio ≤ 160 chars; location ≤ 50 chars.
Edge Cases: All fields empty; max length fields; invalid URL.
Error Conditions: Invalid URL; bio/location too long.
Examples: 
  Input: { "bio": "Hello!" } 
  Output: { "profile": { "bio": "Hello!" } }

Markdown

# Model: User

**Version:** 1.0.0

## Purpose
Authenticated user with secure credential storage.

## Fields
- **id**: UUID (primary key)
- **email**: string (unique, lowercase)
- **username**: string (unique, 3-50 chars)
- **password_hash**: string (bcrypt)
- **is_active**: boolean (default true)
- **created_at**: timestamp (UTC)
- **updated_at**: timestamp (UTC)

## Behavior

### set_password(password: str)
Hash and store password using bcrypt (12 rounds).

### verify_password(password: str) -> bool
Verify password against stored hash.

## Constraints
- Email must be valid format
- Username: alphanumeric + underscore only
- Password minimum 8 characters
- Email and username case-insensitive unique

## Errors
- `ValueError`: Invalid email/username/password
- `IntegrityError`: Duplicate email/username

Markdown

# API: Authentication

**Version:** 1.0.0

## Base URL
`/api/auth`

## Endpoints

### POST /api/auth/register
Create new user account.

**Request:**
```json
{
  "email": "user@example.com",
  "username": "johndoe",
  "password": "SecurePass123"
}
```

**Response (201):**
```json
{
  "id": "uuid",
  "email": "user@example.com",
  "username": "johndoe",
  "is_active": true,
  "created_at": "2024-01-15T10:30:00Z"
}
```

---

### POST /api/auth/login
Authenticate and receive JWT token.

**Request:**
```json
{
  "email": "user@example.com",
  "password": "SecurePass123"
}
```

**Response (200):**
```json
{
  "access_token": "eyJhbGc...",
  "token_type": "Bearer",
  "expires_in": 900
}
```

## Security
- JWT tokens expire in 15 minutes
- Passwords hashed with bcrypt (cost 12)
- All endpoints except register/login require authentication

Introduction: The Role of Complete Specifications

Quick Recall: Key Elements of a Specification

Dissecting the Specification Template

1. Purpose

Join the 1M+ learners on CodeSignal

2. Interface

3. Behavior

4. Constraints

5. Edge Cases

6. Error Conditions

7. Examples

Complete Specification Template

Generating Specifications with AI

Reviewing Real-World Examples

Example 1: User Model Specification

Example 2: Authentication API Specification

Summary And What's Next