Vibe Specs: Vibe Coding That Actually Works

"It doesn't matter how quickly you can create something if it's useless"

0. Quick Start (2 minutes)

Just wanna try it? Here's the fastest path:

## Development Workflow: Spec → Code

THESE INSTRUCTIONS ARE CRITICAL!

They dramatically improve the quality of the work you create.

### Phase 1: Requirements First

When asked to implement any feature or make changes, ALWAYS start by asking:
"Should I create a Spec for this task first?"

IFF user agrees:

- Create a markdown file in `.cursor/scopes/FeatureName.md`
- Interview the user to clarify:
- Purpose & user problem
- Success criteria
- Scope & constraints
- Technical considerations
- Out of scope items

### Phase 2: Review & Refine

After drafting the Spec:

- Present it to the user
- Ask: "Does this capture your intent? Any changes needed?"
- Iterate until user approves
- End with: "Spec looks good? Type 'GO!' when ready to implement"

### Phase 3: Implementation

ONLY after user types "GO!" or explicitly approves:

- Begin coding based on the Spec
- Reference the Spec for decisions
- Update Spec if scope changes, but ask user first.

### File Organization

\`\`\`

.cursor/
├── scopes/
│ ├── FeatureName.md # Shared/committed Specs
│ └── .local/ # Git-ignored experimental Specs
│ └── Experiment.md

\`\`\`

**Remember: Think first, ask clarifying questions, _then_ code. The Spec is your north star.**

(source: https://lukebechtel.com/blog/vibe-speccing)

"Help me add user authentication to my app"

If pasting AI rules from random strangers makes you uncomfortable, read on for some background.

I. Vibe Coder's Lament

Consider the modern predicament: You sit before your IDE, cursor blinking expectantly. The task is clear enough in your mind: implement a widget. You open your AI Agent of choice, and begin typing:

Create a widget that...

30 minutes later, you're ten modules deep, with 49 files changed, and have iterated through six separate widget architectures, each one replete with handlers for edge cases you'll never encounter and optimizations for scale you'll never reach.

You close the chat window. You open a new one.

Let me be more specific...

Sound familiar?

LLMs will happily expand a vague prompt into paragraphs of plausible code. Hundreds of memes make fun of the low-quality "slop software" that comes from lazy prompting -- but even the best-intentioned programmers still run into issues where the AI spends a lot of time building features that didn't align with their original intentions:

@karpathy: Noticing myself adopting a certain rhythm in AI-assisted coding (i.e. code I actually and professionally care about, contrast to vibe code).

...

The emphasis is on keeping a very tight leash on this new over-eager junior intern savant with encyclopedic knowledge of software, but who also bullshits you all the time, has an over-abundance of courage and shows little to no taste for good code. And emphasis on being slow, defensive, careful, paranoid, and on always taking the inline learning opportunity, not delegating. Many of these stages are clunky and manual and aren't made explicit or super well supported yet in existing tools. We're still very early and so much can still be done on the UI/UX of AI assisted coding.

There are many folk remedies for this; longer prompts, stricter system messages, chains / trees of thought, endless "you are an expert" preambles. These remedies have their place. But they're all nuanced, flaky, and complicated to implement. The average developer just wants something fire-and-forget -- and who can blame them?

AI was supposed to be easier!

Besides, these are all bandaids. The real problem, the real reason that so much AI-generated software kinda sucks is much simpler: the AI doesn't understand the problem you're solving, because you didn't adequately explain the problem's context.

Context Engineering

source, @karpathy to @tobi on X

There's a growing understanding that "prompt engineering" isn't a sufficient term for what working with LLMs actually requires. As Andrej Karpathy recently noted in response to Tobias Lütke, "Context Engineering" better captures the sophisticated orchestration involved.

Karpathy Elaborates:

People associate prompts with short task descriptions you'd give an LLM in your day-to-day use. When in every industrial-strength LLM app, context engineering is the delicate art and science of filling the context window with just the right information for the next step. Science because doing this right involves task descriptions and explanations, few shot examples, RAG, related (possibly multimodal) data, tools, state and history, compacting... Too little or of the wrong form and the LLM doesn't have the right context for optimal performance. Too much or too irrelevant and the LLM costs might go up and performance might come down. Doing this well is highly non-trivial. And art because of the guiding intuition around LLM psychology of people spirits.

source, @karpathy to @tobi on X

Too little context and the LLM flails. Too much and it gets lost, or expensive. It's about finding that sweet spot.

Perhaps what Karpathy is saying here about LLM Applications could also improve our day-to-day use.

And art because of the guiding intuition around LLM psychology of people spirits.

"People Spirits"... it is kinda like that, isn't it?

Hmmm... maybe this problem isn't really so new?

Manager Brain

The very same issues come up when delegating tasks to human workers, too.

The way we solve this with humans, is to write a concise set of specs (AKA requirements / PRDs), answering basic questions:

• What is the objective?
• What determines success?
• What tools should we use to achieve the objective?
• What is out-of-scope?
• How will we know when we're finished?

And indeed, with AI, it turns out that this older, humbler practice is still the cure: write the specs first.

Give the AI a crisp spec, and you get crisp, consistent output; give it a vibe, and you get a vibe back.

"But specs are hard to write!" -- you complain.

Ah yes, they used to be... until recently...

II. The Modest Proposal

I know what you're thinking:

Ugh, great, more documentation I have to write. Just what I needed.

But here's the thing - you don't write the Spec; the LLM does.

Your job is to critique, tweak, and clarify.

The multi-turn Spec construction process naturally guides you toward giving the LLM exactly what it needs. The Vibe Specs pattern helps you fall into the pit of success with context engineering.

And here's the best part: you don't even have to remember to do it. Just paste my cursor rules (below) once, and your AI will automatically ask to create a Spec before writing any code.

Make your LLM write a spec before it codes.

That's it. That's the whole trick.

The first thing you do with your LLM should be to write a Spec, not Code.

Workflow

## Development Workflow: Spec → Code

THESE INSTRUCTIONS ARE CRITICAL!

They dramatically improve the quality of the work you create.

### Phase 1: Requirements First

When asked to implement any feature or make changes, ALWAYS start by asking:
"Should I create a Spec for this task first?"

IFF user agrees:

- Create a markdown file in `.cursor/scopes/FeatureName.md`
- Interview the user to clarify:
- Purpose & user problem
- Success criteria
- Scope & constraints
- Technical considerations
- Out of scope items

### Phase 2: Review & Refine

After drafting the Spec:

- Present it to the user
- Ask: "Does this capture your intent? Any changes needed?"
- Iterate until user approves
- End with: "Spec looks good? Type 'GO!' when ready to implement"

### Phase 3: Implementation

ONLY after user types "GO!" or explicitly approves:

- Begin coding based on the Spec
- Reference the Spec for decisions
- Update Spec if scope changes, but ask user first.

### File Organization

\`\`\`

.cursor/
├── scopes/
│ ├── FeatureName.md # Shared/committed Specs
│ └── .local/ # Git-ignored experimental Specs
│ └── Experiment.md

\`\`\`

**Remember: Think first, ask clarifying questions, _then_ code. The Spec is your north star.**

(source: https://lukebechtel.com/blog/vibe-speccing)

1. Add a new rule for your AI Code Helper of Choice (Cursor, Windsurf, Claude Code, etc)
2. Make sure the rule is "Always Attached"
3. Start a New AI Chat
4. Let the AI guide you through Spec creation
5. ???
6. Profit

Example

What does this do? Here's a before and after:

BEFORE (Immediate Code Generation)

AFTER (Spec-First)

My original instructions kind of sucked, didn't they?

But because we were vibe speccing, it didn't matter!

In the Spec-First approach, we account for this type of under-specified problem. The LLM will ask us follow up questions, and ensure it's building the right thing, before it jumps in.

The contrast is striking. In the first screenshot, the assistant immediately dives into implementation, spending 5 minutes generating code that may not match the user's actual needs. In the second, it pauses to understand requirements first.

The Spec-first approach doesn't just produce better code, it respects your time and cognitive load.

Benefits

Why do this? Doesn't this just take a lot of extra time on the front end?

Aren't we trying to move fast & break things?

Well, no. Slow is smooth, and smooth is fast.

It doesn't matter how quickly you can create something if it's useless.

Here are the key problems I've noticed with traditional LLM workflows, and how a Spec-first approach solves them:

1. Chat Drift → Stable Documentation

   • Problem: Exploratory Chat histories necessarily include the exploration and correction of many blind alleys. These turns of conversation would confuse anyone -- and LLMs are no exception.

   • Solution: A Spec document remains stable, even as the chat context changes. Reset the chat window. Change models. Switch IDEs. It doesn't matter; the Spec is just a document in your codebase, like any other file. You're providing structured, dense information that the LLM can parse efficiently (Batarseh et al., 2021).

2. Solo Coding → Team Sport

   • Problem: LLM development is often a solo endeavor because chat histories are ephemeral and personal. You can't easily hand off work to a colleague or pick up where someone else left off without lengthy explanations.

   • Solution: With a Spec, suddenly it's not single-player anymore. You can close your chat, go to lunch, come back, and hand the same Spec to a completely fresh context window — or to a human colleague. The work persists beyond the ephemeral chat session.

3. No Version Control → Git-Tracked Requirements

   • Problem: Git doesn't track your AI conversations. It can't diff your chat history. When requirements evolve or team members need context, there's no systematic way to track the evolution of your thinking.

   • Solution: Git can track WidgetFeature.md, and more importantly, it can track how WidgetFeature.md evolves as your understanding deepens. You can push up the git branch with the Spec and let another colleague begin work immediately, with full context about what needs to be built and why.

4. Feature Creep → Defined Scope

   • Problem: Natural language can be very ambiguous. There's a reason that legalese exists. When you tell an LLM "make a search feature," it might reasonably assume you want fuzzy matching, autocomplete, search history, and real-time updates, or it might assume you want none of these.

   • Solution: When your Spec specifies "basic string matching on user names only," you skip the feature creep entirely. Structured requirements are less ambiguous than conversational requests.

5. Lost Context → Instant Resume

   • Problem: Projects go off course and feel like they require too much effort to get back on track, leading to abandonment.

   • Solution: With Specs, you can return to a project after a week and understand immediately not just what you were building, but why you made specific architectural decisions.

6. Blank Page Paralysis → Structured Start

   • Problem: That terrifying moment of not knowing how to start a feature or project.

   • Solution: The LLM becomes your documentation assistant first, your coding assistant second. It's much easier to critique a proposed Spec than to draft one from scratch.

7. Token Waste → Efficient Context

   • Problem: Burning precious context tokens on exploratory conversation instead of focused implementation.

   • Solution: You're providing structured, dense information that the LLM can parse efficiently, leading to more focused and relevant responses.

III. The Evidence

I have three sources of evidence that this is the most effective way to use LLMs -- personal anecdata, academic research, and industry examples.

Personal Results

My Interview With the CTO

I recently had a fun interview with the CTO of a leading bay area AI Startup.

Part of the interview process was an open-ended real-world coding task, to assess how well I could use AI coding tools. (Which was so much more fun and realistic than leetcode...)

I had 45 minutes to write a fairly complex webserver. Spending the first 5 minutes writing a Spec let me finish 20 minutes early, with a perfect implementation.

Here's roughly how I spent my time:

• 5 minutes writing the Spec with the LLM.
• 10 minutes writing the code with the LLM.
• 5 minutes validating the code.
• 20 minutes asking the CTO questions.

Not bad, eh?

My Day-To-Day

In my own development:

• Before Spec: I would often spend 2-3 hours implementing something, then realizing I built the wrong thing
• After Spec: I spend about 10-20 minutes planning each feature, and 1 hour implementing correctly
• Time saved: I estimate that I have a ~60% reduction in feature development time, and I come out with a better result far more often.

In my personal experience, implementing my simple cursorrule has saved me literally days of back-and-forth with LLMs.

Academic Evidence

Academia seems to be catching on -- Recent research on LLM-assisted development emphasizes that specifications are "the missing link" in making LLM code generation reliable (Pullum et al., 2020).

Industry Validation

If you prefer an industry example, how about OpenAI? They seem to have noticed this pattern too. Their new Deep Research mode pauses to ask clarifying questions, tightening the problem definition before spending extra compute. Instead of torrenting answers, it builds understanding first. Imagine your coding assistant doing likewise: a quick interrogation that locks down scope, constraints, and must-haves, so the next burst of code is laser-focused instead of encyclopedic.

This differs from conventional AI-assisted development wisdom, which treats LLMs as code generators to be used when you're uncertain. "I need to implement X, let me ask Claude to write it." But this approach misunderstands both LLMs and good software development.

The magic isn't in avoiding the LLM until you have requirements. The magic is in using the LLM to help you discover what your requirements actually are.

As another example, Shopify's approach to their Auto Write feature began with a comprehensive Spec that aligned AI capabilities with merchant needs.

The pattern is becoming clear: successful AI features start with clear requirements, not clever prompts.

IV. The Critique

"gotta go fast"

A common objection, "But I'm prototyping/in a hackathon/need to move fast!"

Even for prototypes, 5 minutes of Spec saves hours of refactoring.

*It doesn't matter how quickly you can create something if it's useless.**

Garbage-in, Garbage-out

Of course, this does require you to give valid input.

It requires you to be somewhat present at the wheel.

But that's precisely why the conversation matters. The LLM doesn't write your Spec in isolation; it interviews you, challenges assumptions, and iterates based on your feedback.

V. Final Thoughts

In the age of AI-assisted development, every dev will become their own product manager.

The hardest part isn't writing the code anymore -- it's knowing what code to write. LLMs are incredibly powerful at the former. The Vibe Specs pattern ensures we don't abdicate responsibility for the latter.

Start your next feature with a Spec. Let your AI help you write it. Watch as your development velocity increases, your code quality improves, and—most importantly—your ability to context-switch without losing your mind returns.

The future of AI-assisted development isn't about better code generation. It's about better requirement articulation. LLM -> Spec -> Code. This is the way.

Share Your Story

Tried vibe speccing? I'd love to hear about it:

• 🐦 Tweet your experience: @linkbechtel #VibeSpecs
• 📧 Email: luke@lukebechtel.com

The best stories will be featured in a follow-up post (with permission).

.cursor/
├── scopes/
│   ├── feature-name.md      # Committed specs
│   └── .local/              # Git-ignored experiments
│       └── experiment.md

References & Further Reading

Academic Research:

• Dreossi, T., et al. (2024). "Specifications: The missing link to making the development of LLM-based software more trustworthy". arXiv preprint.
• Pullum, L., Freeman, L., & Huang, C. (2020). "Verification and Validation of Systems in Which AI is a Key Element". Systems Engineering Body of Knowledge.
• Batarseh, F. A., Freeman, L., & Huang, C. H. (2021). "A survey on artificial intelligence assurance". Journal of Big Data, 8(1), 1-30.
• Hand, D. J., & Khan, S. (2020). "Validating and Verifying AI Systems". Patterns, 1(3), 100037.

Industry Resources:

• Downie (2024). "Product requirement document generation using LLM task oriented". GitHub Gist.
• Alward, R. (2024). "Master the Blueprint: LLM Prompts for Perfect Product Requirements Documents (Spec)". Medium.
• Shoffstall, S. (2025). "Revolutionizing Product Development: How AI is Transforming the Spec Process". Medium.

Tools & Frameworks:

• Magical PM - AI-powered product management platform
• GoGPractice.io - LLM-assisted product development guide
• Mustafa Kapadia's Substack - Writing product requirements with AI