Agentic coding tools like Claude Code or OpenAI Codex are fascinating. An AI that reads your code, understands your project structure, and makes changes directly. Features that would take days appear in hours.
You control the coding agents by prompting. That’s what’s widely known as Vibe Coding. During my first sessions with Claude Code I did exactly that: go from prompt to prompt. But after a while I lost track of where I was going. And so did the coding-agent. I call it “the vibe coding hangover”.
The vibe coding hangover#
As my projects grew, the agent lost track of components it had built. It duplicated functionality, contradicted earlier design decisions, and solved the same problem three different ways.
I was going from prompt to prompt with no clear start and no clear end. No artifact captured what I wanted. Every conversation started from near-zero context. The AI was writing code, but nobody was writing down the requirements.
Vibe coding is building without blueprints. It works for small things, but it falls apart in larger projects or codebases.
So what to do about the hangover? Spec-driven development: write down what you want to build before the AI writes code. Use those specifications to guide and constrain implementation. I have written a blog post on spec-driven development that explains the methodology and compares three open-source projects in the space.
With this blog post, I want to share six takeaways from using SDD with Claude Code:
Lessons Learned#
Lesson 1: vibe coding doesn’t scale#
It’s fine for prototypes, experiments, and small scripts. But without formalizing intent, you accumulate technical debt with every prompt. The AI fills gaps with assumptions and does not know about other features or constraints that have been built with previous prompts.
After a few vibe coding prompts, I had a working prototype and no clear understanding of what it was supposed to do. The code worked, but the why behind decisions disappeared. Refactoring meant re-explaining everything from scratch.
Lesson 2: AI agents need constraints#
The same capability that makes agents powerful—their ability to make decisions and fill in details—is also their weakness. Without constraints, output drifts from your intent. How should the coding agent know what to build if the intent is not communicated?
Think of specs as guardrails. Not bureaucratic overhead, but a way to prevent the agent from “helping” in directions you didn’t want. The more explicit the spec, the better the output.
Lesson 3: a long-living spec library is essential#
A well-maintained spec library becomes the memory that AI agents lack. It answers “what did we build and why?”
Without evolving specs, the agent loses the overview. It can read your code, but code doesn’t capture intent. Why was this trade-off made? What edge cases were considered? Specs hold that context.
Lesson 4: start with a project mission#
Create a project mission, e.g., a mission.md file, within your project. The mission lays the foundation for the project and guides the agent’s decisions.
Mine typically includes: project purpose, target personas, tech stack, development tools, how the agent should test, project structure, high-level architecture, and security/performance constraints.
The best part: the agent will help you create it. Add that list of topics to your prompt and ask it to build the mission file with you. You’ll have a solid foundation in minutes.
With a proper mission file, you stop repeating yourself. The agent knows the tech stack. It knows important constraints and patterns for your project. Your feature specs can focus on what to build.
I instruct the agent to read the mission file before starting to iterate on a new or existing feature spec.
Lesson 5: clarifying intent is the real work#
The most valuable part of SDD isn’t the format or the tooling. It’s the forcing function: you must articulate what you want before implementation begins.
The intent doesn’t need to be technical. Describe behavior and requirements as users would experience the software. Be aware that the agent will fill in gaps which may differ from what you actually want. To avoid this, I now add “Ask me clarifying questions” to every prompt that iterates on a spec. This surfaces areas where my own thinking is vague. The questions the AI asks often reveal requirements I hadn’t considered.
Lesson 6: structure makes you faster#
Here’s what surprised me most: adding structure made me faster, not slower.
Planning before coding feels like overhead when you have an AI that can generate code in seconds. But the time I “lost” iterating on specs, I gained back tenfold by avoiding rework, confusion, and dead ends.
Conclusion#
The cure for the vibe coding hangover is more discipline. Spec-driven development provides that discipline:
- It captures the intent in a structured and systematic way so that both humans and coding agents can not only understand but also reference it.
- A long-living spec library prevents drift and preserves decisions and requirements throughout the coding sessions.
- A project mission sets the foundation and summarizes the guardrails for the project.