Complete Specification Breakdown

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) → Project-wide rules
• 📋 Feature Spec (this lesson) → 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.

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:

# 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.

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.

This section explains what the component or feature is for, in one sentence.

## 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.