Vibe Coding Meets Spec-Driven Development: The Best of Both Worlds

If you've been coding with AI assistants lately, you've probably experienced both extremes.

On one side: vibe coding, you open a chat, describe what you want in plain English, and let the model run. It feels like magic. You ship fast, you stay in flow, and the dopamine hits are real.

On the other side, there's a nagging feeling. The codebase starts to drift. A component does three things it shouldn't. A bug appears that you swear you didn't introduce. You ask the AI to fix it, and it breaks something else. The vibes turn chaotic.

Enter Spec-Driven Development (SDD), the idea that before you write (or generate) a single line of code, you write a specification: a clear, structured document that defines what you're building, why, and how it should behave. It's not a new concept, but it's having a renaissance in the age of AI coding.

The good news? You don't have to pick one. In fact, combining them is arguably the most productive way to build software today.

The term was popularized by Andrej Karpathy in early 2025: "There's a new kind of coding I call vibe coding, where you fully give in to the vibes, embrace exponentials, and forget that the code even exists."

It's characterized by:

Vibe coding shines for prototyping, exploration, and solo projects where speed matters more than maintainability. It's a legitimate and powerful workflow, but it has a ceiling.

SDD is the practice of writing a machine-readable (and human-readable) specification before implementation begins. A spec typically includes:

In an AI-assisted workflow, the spec becomes the single source of truth you feed into every prompt. Instead of re-explaining context each time, you anchor the model to a document it can reference.

You: "Build me a user authentication system"
AI: *generates 300 lines of code*
You: "Actually add role-based access control"
AI: *refactors half the codebase*
You: "Wait, why is the session logic in the component?"
AI: "Good point, let me move it..."
You: *three hours later, untangling spaghetti*

Without a spec, the AI optimizes for your last message, not your actual goal. Every new prompt is a new negotiation with the model, and context drift is inevitable.

Heavy specification processes can kill momentum. Writing a 10-page PRD before you know if an idea even works is a trap. You over-engineer requirements for problems you haven't validated. The spec becomes a bureaucratic artifact nobody reads.

The sweet spot is a lightweight spec that guides rapid AI-assisted implementation. Here's how it works in practice:

Before touching any AI coding tool, spend 15–30 minutes writing a short spec. It doesn't need to be formal, a markdown file works perfectly.

## Goal
Allow users to register, log in, and manage sessions securely.

## Scope
- IN: Email/password registration, JWT sessions, logout
- OUT: OAuth, 2FA (next iteration)

## Data Model
User { id, email, passwordHash, createdAt, role: "user" | "admin" }
Session { token, userId, expiresAt }

## API Contracts
POST /auth/register  → { token, user }
POST /auth/login     → { token, user }
POST /auth/logout    → { success: boolean }
GET  /auth/me        → { user }

## Acceptance Criteria
- Passwords hashed with bcrypt (min 12 rounds)
- JWT expires in 7 days
- Invalid credentials return 401, never expose which field failed
- Logout invalidates the token server-side

That's it. Two hundred words that prevent hours of confusion.

Every AI prompt now starts with context from the spec:

Given this spec: [paste relevant section]

Implement the POST /auth/register endpoint. Use bcrypt for 
hashing and return a signed JWT. Follow the data model defined above.

The model is no longer guessing your intent, it's executing against a contract.

Once the structure is in place, let the vibes flow. Need to add error handling? Optimize a query? Style a component? You can move fast because the foundation is solid. The spec sets the walls; the vibe coding furnishes the room.

This is the discipline that separates good hybrid workflows from bad ones. When scope changes (and it will), update the spec first, then regenerate or refactor the code. Don't let the spec become stale documentation, it's a living contract.

Step 1: Edit spec.md → add OAuth section
Step 2: Prompt AI with updated spec section
Step 3: Let it implement

Let's say you want to build a simple task manager. Here's how the hybrid approach plays out:

Pure vibe approach:

"Build a task manager with React and Node"

You'll get something, but what database? What auth? What data model? You'll spend the next hour correcting assumptions.

Hybrid approach:

Write a 10-minute spec:

## Stack: React + Express + SQLite (simple, no Docker needed)
## Auth: None for MVP (single user, local app)

## Data Model
Task { id, title, status: "todo"|"in_progress"|"done", createdAt }

## UI Requirements
- List view grouped by status
- Add task via inline input
- Drag or click to change status
- No delete (archive instead)

## Out of Scope
- Multi-user, tags, due dates, notifications (v2)

Now your AI prompts are laser-focused:

"Using this spec, generate the Express API with SQLite. Only implement the endpoints needed for CRUD on tasks."

The result? Clean, predictable code that matches what you actually want.

The spec-then-vibe approach pairs beautifully with AI tools that support long context or file-based prompting:

The key is making your spec accessible to the AI at all times, not just in the first prompt.

The biggest change isn't technical, it's philosophical. Vibe coding tempts you to treat the AI as an oracle: just ask and receive. Spec-driven development reminds you that you are still the architect. The AI is an extraordinary executor, but it needs direction.

When you combine both, you get something powerful: the speed of vibe coding without the chaos, and the structure of specs without the bureaucracy.

Think of it this way: specs are the map, vibe coding is the engine. You can drive fast, but you still need to know where you're going.

You'll be surprised how much less time you spend fixing AI hallucinations, and how much more time you spend shipping things that actually work.

Have you tried combining vibe coding with specs? What's your workflow? Drop a comment below, I'd love to hear how others are navigating this.