What Is Spec-Driven Development for Vibe Coders?

There is a specific moment that almost every vibe coder hits. Around prompt 30 or 40, something that was working fine just... breaks. You fix it. Something else breaks. You fix that. The first thing comes back. The AI seems to have forgotten what it already built.

This is the vibe wall, and a spec is the thing that stops you from running into it.

The Vibe Wall: When AI Coding Stops Working

If you're new to vibe coding — building apps by describing what you want in plain English and letting an AI generate the code — the first few sessions feel almost magical. You describe a login screen, it appears. You ask for a database connection, it happens.

The magic starts wearing off around the time your project has real complexity: multiple pages, a data model with several tables, UI state that depends on backend logic.

What actually happens at 30–40 prompts

Every prompt you send uses context — the AI's working memory for a conversation. In longer sessions, earlier decisions get pushed out of that window. The AI doesn't forget completely, but it starts reconstructing your app from partial information.

The result: it writes code that contradicts a decision made 20 prompts ago. A variable gets renamed. An API endpoint changes shape. A UI component gets rebuilt from scratch instead of reused.

Why the AI starts breaking things it already built

This is called context rot — the slow degradation of the AI's understanding of your project as the conversation grows. The AI isn't malfunctioning. It genuinely cannot hold everything in mind at once, especially in a long, exploratory session.

Without a spec, each prompt is a fresh negotiation. With a spec, the AI has a fixed reference document it can check against before writing anything. The spec is the antidote to context rot.

If you're currently suffering this problem, the fix-first guide is at how to fix AI-generated code. But the longer-term solution is to build spec-first from the start.

What a Spec Is (in Plain English)

A spec — short for specification — is a one-page document you write before you start prompting. It describes what you're building, who it's for, what it does, and what the rules are.

That's it. You're not writing a 50-page enterprise PRD. You're not describing technical architecture. You're writing the kind of document you'd give a smart human contractor so they understood the job before starting.

The five things every spec covers

1. What it is — one sentence, plain English. "A daily habit tracker where users log whether they completed each habit today."
2. Who uses it — one user type for a small project. "Solo users. No teams, no sharing."
3. The core feature list — 5–8 bullet points. What must exist for the app to be useful? Not the full roadmap, just the must-haves.
4. What it doesn't do — explicitly out of scope. "No push notifications. No data export. No social features." This is the most important section for preventing scope creep in AI sessions.
5. Key rules and constraints — things the AI must always respect. "Authentication uses email/password only. All data is per-user and never shared."

A real example: spec for a simple habit tracker app

# Habit Tracker — Project Spec

## What it is
A web app where one person logs daily habits and sees a streak count.

## User
Single user, personal use only. No accounts, no sharing.

## Must-have features
- Add a habit (name only)
- Mark a habit as done for today
- See a streak count per habit (consecutive days completed)
- Delete a habit

## Out of scope
- Reminders or push notifications
- Social features or sharing
- Data export
- Multiple users or login

## Rules
- All data stored locally in the browser (no backend required)
- Streak resets if a day is missed — no grace periods
- UI is minimal, no animations

That document took five minutes to write. Pasted at the start of every Claude Code or Cursor session, it acts as a persistent contract. The AI can't "decide" to add a login screen because the spec says no backend is required.

Spec vs CLAUDE.md: What's the Difference?

If you've read about CLAUDE.md files, you might wonder whether a spec is the same thing. It isn't.

CLAUDE.md is about the tool; a spec is about the project

A CLAUDE.md file is instruction for how Claude Code should behave — your preferred coding style, which commands to run for testing, which files to avoid touching. It's a configuration layer for the tool itself.

A spec is a description of what you're building. It's project documentation, not tool configuration.

They work together — you need both

The best setup is to have both. Keep tool behavior in your CLAUDE.md. Keep project decisions in a separate SPEC.md (or paste the spec at the top of your first prompt). Claude Code will use whichever is in scope.

The how to write CLAUDE.md guide covers what belongs in each section — the project background part of CLAUDE.md is where many beginners end up accidentally writing spec content.

Spec vs Prompt Chaining: Complementary, Not the Same

Prompt chaining is the practice of breaking a big task into a sequence of smaller prompts, each one using the output of the last. It's a technique for managing complexity within a session.

A spec operates at a different level. It's not about how you break up the work — it's about defining what the work is before you start. You can use prompt chaining to build a spec-driven project, and doing both is generally better than doing either alone.

Think of the spec as the blueprint and prompt chaining as the construction method. Blueprints don't tell you whether to lay bricks one at a time or in batches. They tell you what you're building.

How to Write Your First Spec in 20 Minutes

You don't need a template tool or a special format. Open a plain text file and answer five questions.

The five-question template

1. What does this app do? (One sentence.)
2. Who is the single primary user?
3. What are the 5–8 features it must have to be useful?
4. What will it explicitly NOT do? (List at least 3 things.)
5. What are the non-negotiable rules? (Data model, auth, constraints.)

Fill in the answers in plain English. Don't use technical terms you'd have to explain to the AI. Write it the way you'd explain the project to a friend over coffee.

What to include (and what to leave out)

Include:

• Anything the AI could reasonably guess differently from what you want
• Constraints that affect every feature (no backend, no user accounts, mobile-only)
• The single most important UI rule if you have one

Leave out:

• Implementation details — the AI decides those
• Your technology preferences (unless they're hard constraints) — put those in CLAUDE.md instead
• Nice-to-haves — keep the spec to must-haves only. Nice-to-haves go in a separate "future ideas" section at the bottom, clearly labeled

If your spec is longer than one page, cut it in half.

Which Tools Read Your Spec Automatically?

Kiro (spec is built into the IDE flow)

Kiro is the tool most directly built around spec-driven development. Before Kiro writes any code, it walks you through generating a structured spec — requirements, design decisions, and implementation plan — and stores it in your project. Its autonomous agents then check all code against that spec before committing.

Kiro stores the spec as structured files in a .kiro/specs/ directory in your project — not a single SPEC.md, but three linked documents: requirements.md, design.md, and tasks.md. There is also a .kiro/steering/ directory for project-wide guidance files.

You don't paste anything manually. The spec is part of the IDE's native workflow.

Our full Kiro review covers how this works in practice.

Claude Code and Cursor (paste it in; or drop it in CLAUDE.md's project section)

Claude Code and Cursor don't have a built-in spec step. But both will respect a spec if you give it to them — you just have to provide it yourself.

Two approaches:

• Paste at session start: Copy your SPEC.md into your first prompt. Prefix it with "Here is the project spec. Follow it throughout our session." This works well for single-session work.
• Embed in CLAUDE.md: For longer projects, add a ## Project Spec section to your CLAUDE.md. Claude Code loads CLAUDE.md automatically at session start, so the spec is always in context.

Cursor users can store the spec as a rule in the .cursor/rules/ directory — create a .mdc file there and set it to "Always Apply." The older .cursorrules file at the project root still works but is deprecated and Cursor recommends migrating to the new format.

The One-Page Spec Template (Copy and Fill In)

# [Project Name] — Spec

## What it is
[One sentence describing the app and its core purpose.]

## Primary user
[Who uses this? One type of user. If it's just you, say so.]

## Must-have features
- [Feature 1]
- [Feature 2]
- [Feature 3]
- [Feature 4]
- [Feature 5]

## Out of scope
- [Thing the AI might reasonably add but should not]
- [Thing the AI might reasonably add but should not]
- [Thing the AI might reasonably add but should not]

## Rules and constraints
- [Non-negotiable constraint 1]
- [Non-negotiable constraint 2]
- [Non-negotiable constraint 3]

## Future ideas (do not build yet)
- [Nice-to-have that you don't want to lose track of]

Copy this, fill it in before your next project, and paste it at the start of your first session. That's the whole practice.

When You Don't Need a Spec

A spec adds value as soon as your project has more than one feature and more than one session. Below that threshold, it's overhead.

Skip the spec if:

• You're experimenting — genuinely exploratory, throwaway work
• The entire project fits in a single prompt ("make me a color picker")
• You're prototyping to discover the spec (fine, but write the spec once you know what you're building)

If you're not sure whether your project needs one, write it anyway. Twenty minutes upfront saves hours of untangling context rot later.

Once you have a spec and understand what you're building, the next skill is prompting well inside that structure. How to write better prompts for AI coding tools covers the techniques that make the biggest difference once you have direction.