There is that moment at the beginning of a new feature where everything is still open. No legacy code, no constraints, no unexpected dependencies. Just you, an empty directory and an AI tool that promises to deliver results in minutes.
In moments like that, vibe coding is incredibly tempting. Just start. Prompt in, code out, next prompt. No planning, no specifying, no thinking about architecture. Just do it.
I did that. I paid for it.
What vibe coding really means
The term "vibe coding" – coined by Andrej Karpathy – describes an approach where you use AI tools without having clearly defined what you are actually building. No schema, no design system, no explicit rules. You "vibe" your way through the feature.
That is not fundamentally wrong. For a quick prototype, a throwaway demo, a first feasibility check it works well. Within an hour you have something running on screen. The feeling is great.
The problem comes later.
The bill
Over the past months I have seen projects – my own and others' – that started with vibe coding. The pattern is always similar: the first sprint runs surprisingly smoothly. Then sprints two and three arrive. And suddenly you are fighting code that technically works but is architecturally a mess.
Specifically: components that know too much. State management spread across three different approaches because the AI chose a different path with each prompt. Inconsistent naming. Duplicated code, because the AI on the second prompt did not know it had already built something similar on the first.
And the worst part: when you try to fix it afterwards, you are not fighting the AI – you are fighting the accumulated decisions of twenty previous prompts, each locally sensible but globally inconsistent.
Those of us working as senior developers or freelancers with real architectural influence notice this particularly fast. You have the experience to see where it is heading. And that experience tells you: this is going to be expensive.
The difference that specification makes
Anyone who read Context engineering: why your prompt is the smallest problem and The ticket as a thinking tool – before the first line of code from this series will recognize the pattern: CLAUDE.md for overall context, ticket for task-level context. Spec-driven development is the application of the same idea at the architecture level.
The principle is simple: before I let the AI write even a single prompt, I have defined what I am building, how it should be structured, and by which rules the code gets written. Not as a hundred-page requirements document, but as a living document – a CLAUDE.md, a component library, an explicit design system.
What changes because of this: the AI no longer makes architectural decisions. I made those beforehand. It just implements them.
That is the decisive shift. Vibe coding lets the AI decide which path to take. Spec-driven development tells it which path to take.
What this looks like in practice
A concrete example from my own website. When I built the blog section, I had two options:
Option A – vibe: Tell Claude Code "build me a blog" and see what comes out.
Option B – spec: First define which frontmatter fields a blog post needs, which components get used, how routing works, how i18n integrates – and then let Claude Code handle the implementation.
I chose option B. The result was consistent code, fewer revisions, and I never had to explain "no, not like that" – because "like that" was clear from the start.
The specification as single source of truth
# CLAUDE.md
## Frontmatter schema
title, slug, translationSlug, date, category, description, readingTime, tags, featured, draft
## Components
- GbCard: default / project / highlight variants
- GbButton: primary / ghost / cta-inverted variants
- No new markup before checking existing components
## Coding rules
- Composition API only
- Tailwind only
- No hardcoded text
That sounds like bureaucracy. But it is the opposite: it is the foundation on which I can work quickly without constantly looking back.
What this means for senior developers and freelancers
I think vibe coding is a particular problem when you – like me – work as a freelancer and carry full architectural responsibility. As a junior developer in a large team there are guardrails: existing codebases, team conventions, architects who make decisions. The structure is already there – you simply work within it.
As a freelancer, you are the architect. If you do not define the structure, nobody does – and then the AI "defines" it implicitly, prompt by prompt. That sounds more efficient than it is.
The real strength of AI tools is not that they can write code fast. It is that they work consistently and reliably within clear boundaries. Those boundaries have to be set by a human.
The compromise I found
I am not writing this because I think vibe coding is fundamentally wrong. Sometimes a quick prototype is exactly the right thing. A throwaway experiment, a proof of concept for a client, a feature demo – there you can vibe.
But as soon as something goes to production, as soon as other developers need to work on it, as soon as maintainability matters: then I need the specification first.
The difference in my day-to-day: I sometimes vibe prototypes. I always spec projects.
What happens when even with a good spec things still go wrong – because the context is documented but incorrect, or because the AI still violates an implicit assumption – that's what the next post is about.
Vibe coding gives you something running fast. Spec-driven development gives you something that runs – and that someone will still understand six months from now.