What is Spec-Driven Development?

Spec-Driven Development (SDD) is a practice where you write a detailed specification before writing any code. The spec acts as a contract: it describes what a feature should do, what the inputs and outputs are, what edge cases need to be handled, and what constraints apply.

This is not a new idea. It shares DNA with Test-Driven Development and Design-by-Contract. What has changed is that AI tools can now consume these specifications and produce working code from them — making the practice dramatically more valuable than it was even two years ago.

Why SDD Works Better With AI

When you prompt an AI model without context, you get generic output. When you give it a detailed spec, you get something much closer to what you actually need.

The spec forces you to think through the problem before the AI touches it. That thinking is the most valuable part. A poorly specified feature generates hallucinated interfaces, incorrect edge case handling, and code you will have to rewrite anyway. A well-specified feature generates code you can review and ship.

The other benefit is consistency across a codebase. A spec becomes a reusable artifact. New team members, AI assistants, and even future you can understand what a component is supposed to do — and why — without reading its implementation.

The Workflow

1. Brainstorm

Start by understanding the problem. This is where AI is genuinely useful as a thinking partner.

Prompt: I need to add rate limiting to our public API. What are the tradeoffs
between token bucket, leaky bucket, and fixed window algorithms for a Rails app?

Use the response to inform your design decisions. Ask follow-up questions. The goal is not to generate code yet — it is to understand the solution space.

2. Write the Spec

Now write the specification. This is plain text or markdown describing what you are building:

## Feature: API Rate Limiting

**Goal**: Limit authenticated API requests to 1,000 per hour per user.

**Algorithm**: Token bucket, implemented via Redis.

**Behavior**:
- Each user starts with a full bucket (1,000 tokens).
- Each request consumes 1 token.
- Tokens refill at 1,000/hour (continuous, not batch).
- Requests exceeding the limit receive a 429 response with a Retry-After header.
- Unauthenticated requests are not rate limited at this stage.

**Headers returned on every request**:
- X-RateLimit-Limit: 1000
- X-RateLimit-Remaining: <current tokens>
- X-RateLimit-Reset: <unix timestamp when bucket refills>

**Edge cases**:
- Redis unavailable: fail open (allow the request, log the error).
- Clock skew: use Redis server time, not application server time.

This took 10 minutes to write. It will save hours of back-and-forth.

3. Plan

Before writing code, use the AI to produce a technical plan:

Prompt: Based on this spec, outline the classes, methods, and Redis key structure
needed to implement this in a Rails API. List any dependencies.

Review the plan. Push back on anything that does not fit your architecture. This is the moment to catch misunderstandings before they become bugs.

4. Generate Code

Now let the AI write the implementation:

Prompt: Implement the RateLimiter class from the plan above. Use the redis-rb gem.
Include unit tests using RSpec and mock Redis calls.

You will get code you can actually use. Because the spec was clear, the AI had enough context to make reasonable decisions.

5. Review

Read the generated code critically. Check:

  • Does it match the spec?
  • Are the edge cases handled (Redis unavailability, clock skew)?
  • Is the Redis key structure sane?
  • Are there any security issues (key injection, timing attacks)?

The AI will not catch everything. Your job as the engineer is to review, not to rubber-stamp.

Benefits

Speed: Moving from spec to working draft in minutes, not hours, changes the economics of a project. Features that would have been deferred get built.

Documentation: The spec is documentation. Unlike comments in code, it does not drift — it represents the intended behavior at the time of design.

Onboarding: A new developer handed a spec-plus-implementation can understand the feature in 15 minutes.

Prompt quality: Writing specs makes you better at prompting. The habits are the same: be specific, define boundaries, describe behavior not implementation.

Common Pitfalls

Treating AI output as finished code. It is a draft. Always review. AI models can produce plausible-looking but subtly incorrect code, especially for concurrency, security, and edge cases.

Under-specifying. A one-line spec produces a one-line answer. If the spec is vague, the code will make assumptions — and those assumptions may not match your system.

Skipping the plan step. Going directly from spec to code increases the chance of an architectural mismatch. The plan step surfaces these before the code is written.

Not testing the output. Generated code should be tested like any other code. If the spec includes behavior expectations, those translate directly into test cases.

Spec Kit: SDD as an open source toolkit

GitHub released Spec Kit — an open source toolkit that formalizes SDD into a structured process with three clear phases and ready-to-use commands for AI agents like Copilot, Claude Code, and Gemini CLI.

The 3 phases of Spec Kit

1. Specify (/speckit.specify): Transforms vague ideas into comprehensive requirements documents. Focuses on business needs and user value, no implementation details. Ambiguities are explicitly marked with [NEEDS CLARIFICATION].

2. Plan (/speckit.plan): Converts specifications into technical implementation plans. Maps requirements to architectural decisions with documented rationale. Generates data models, API contracts, and test scenarios.

3. Tasks (/speckit.tasks): Derives executable task lists from the plan. Identifies parallel work opportunities and produces concrete deliverables ready for code generation.

The power inversion

Spec Kit’s core philosophy is that specifications don’t serve code — code serves specifications. The PRD isn’t a guide for implementation; it’s the source that generates implementation. When the spec drives everything, there’s no gap between intent and execution — only transformation.

In practice, this means Spec Kit treats natural language as an executable artifact. Structured templates constrain AI output toward higher-quality specs, and constitutional principles (like “test-first” and “library-first”) ensure generated code maintains consistency.

Why this matters

Before Spec Kit, every team improvised their SDD workflow. Now there’s a standardized process with validated templates and built-in quality gates. If you work with AI agents for development, it’s worth trying.

Tools

  • Spec Kit — SDD framework with structured phases and templates
  • Claude Code (Anthropic) — Works well with long, detailed specs and large context windows
  • Cursor — IDE-integrated AI with good awareness of your existing codebase
  • GitHub Copilot — Best for inline completion and smaller, well-defined tasks

SDD Is a Discipline, Not a Tool

The tools change. Claude will be replaced by something better. Cursor will gain new features. Spec Kit may evolve into something different. The underlying practice — think carefully, specify precisely, then build — remains valuable regardless of what the AI stack looks like.

Spec Kit from GitHub formalized this process into something replicable and open source. If you already write good specs before coding, adding AI to the workflow is straightforward. If you don’t, SDD is worth adopting on its own merits. The AI integration is just the accelerant.

References