Phase 1: Spec-Driven Development · 45 min · Claude Code · Python

Writing Your First Spec

A spec describes what must be true. The moment it describes how, it stops being durable.

Hiring signal: Writing a spec that survives a technology change (database swap, framework migration) without needing a rewrite is a concrete, demonstrable skill — and one hiring managers can verify by asking you to spec a feature live.

What you will learn

Structure a spec into problem statement, acceptance criteria, constraints, and test cases
Apply the 'don't mention the implementation' rule to keep a spec durable across technology changes
Distinguish a testable, measurable acceptance criterion from a vague one
Write and lint a real spec for your own course-long product

Introduction

Writing Your First Spec

An engineer writes what she believes is a solid spec for a "don't hit the database twice for the same lookup" feature: "Use a Redis cache with a 5-minute TTL, keyed by request parameters." Six weeks later, the team decides the service is small enough that Redis is overkill — an in-memory LRU cache would do the job with one less piece of infrastructure to operate. Except now they can't just swap the implementation, because the spec is the Redis decision. Every acceptance criterion references Redis-specific behavior (eviction semantics, TTL precision) that an in-memory cache handles differently. The "spec" has to be rewritten before the "simpler" change can even be evaluated properly, which defeats the entire point of writing a spec that was supposed to outlive implementation decisions.

This is the single most common mistake in a first attempt at spec-driven development: writing how instead of what. A spec should describe behavior an implementation must satisfy, not the implementation itself.

The don't-mention-the-implementation rule

Compare the two versions of the same requirement:

Implementation-coupled (wrong): "Use a Redis cache with a 5-minute TTL, keyed by request parameters."
Behavior-first (right): "A repeated request for the same resource within 5 minutes of a prior request must not trigger a second database read. Cached results must never be served past 5 minutes old."

The second version says nothing about Redis, in-memory dictionaries, or any other mechanism. It's testable — you can write a test that makes two identical requests 30 seconds apart and asserts only one database read occurred — without the test caring how caching is implemented. Swap Redis for an in-memory cache, for Memcached, for anything else that satisfies the behavior, and the spec doesn't change, because the spec was never about the mechanism.

The test for whether you've broken the rule
If your acceptance criterion would need to change because you swapped one library or database for another that produces the same observable behavior, you wrote an implementation detail, not a spec. A real acceptance criterion survives that swap unchanged.

Unlock the full lesson

You've read the first 2 sections. The rest of this lesson covers The four sections, and what belongs in each, Testable versus vague acceptance criteria, Build It — plus a hands-on lab, quiz, and project artifact.

Create a free account to unlock Phase 0 and Phase 1 of every course — no credit card.