Taming AI-Generated Code: Why Spec-Driven Development Beats Vibe Coding

Introduction

In early 2025, AI developer Andrej Karpathy sparked a lively debate with a post on X (formerly Twitter) about a new programming approach he called “vibe coding.” He described a workflow where developers rely entirely on large language models, such as Cursor Composer with Sonnet, to write code without reviewing it. According to Karpathy, this method involves asking for trivial changes, blindly accepting all suggestions, and pasting error messages directly into the chat. He admitted it works “mostly” for throwaway weekend projects, but the phrase “mostly works” is far from a ringing endorsement.

The Hidden Dangers of Vibe Coding

While vibe coding might be acceptable for quick prototypes or personal experiments, applying it to serious software projects introduces significant risks. The primary concern is the creation of hidden bugs that can surface later, making debugging a nightmare. Because developers rarely read the generated code or understand its structure, these bugs can remain undetected for long periods.

Another major issue is the inevitable accumulation of technical debt. Code produced by AI models often lacks coherent architecture, consistent naming conventions, or proper error handling. Over time, this sloppy foundation makes the codebase harder to maintain and extend. Even if a competent programmer later attempts to clean up the AI’s output, the effort required to refactor the code is often greater than writing it manually from scratch. This paradox means that vibe coding can actually reduce overall productivity, defeating its original purpose.

Karpathy himself acknowledged the limitations, noting that he used vibe coding only for low-stakes projects. He also expressed frustration with having to “work around” bugs or ask for random changes until the problem disappears. Such tactics are clearly unsuitable for production environments where reliability and maintainability are paramount.

Enter Spec-Driven Development

Fortunately, there is a middle ground between the chaos of vibe coding and the rigidity of traditional manual coding. This approach, known as spec-driven development (SDD), aims to harness the power of AI while maintaining control over the outcome. Spec-driven development is not about creating exhaustive requirements documents or following a waterfall process. Instead, it provides a lightweight, readable, and concise specification that guides both human developers and AI agents.

Spec as Version Control for Thinking

Den Delimarsky, a principal engineer at Microsoft, describes a spec as “version control for your thinking.” In his introduction to Spec Kit, he elaborates: “This is a contract for how your code should behave and becomes the source of truth your tools and AI agents use to generate, test, and validate code. The result is less guesswork, fewer surprises, and higher-quality code.” By having a clear specification, developers can communicate exactly what the code must do, reducing ambiguity and the risk of misinterpretation by large language models.

A Lighter-Weight Alternative to Waterfall

Spec-driven development should not be confused with traditional heavy documentation. It is deliberately lightweight—often a single page or a few paragraphs—written in plain language that both humans and machines can understand. Unlike waterfall planning, which requires upfront detail that may become obsolete, SDD evolves with the project. The spec is updated iteratively, much like code, and serves as a living contract between the developer’s intent and the AI’s output.

This method directly addresses the pitfalls of vibe coding. With a spec in place, the AI is less likely to produce code that deviates from the desired behavior. When it does make mistakes, the wrong output is easier to detect because it violates the contract. Furthermore, the spec makes it simpler for human developers to validate the generated code, reducing the hidden bug problem.

Birgitta Böckeler of Thoughtworks has also explored how specs can be divided into logical units that map to specific components of an application. This modular approach allows developers to focus on one piece at a time, making the overall development process more manageable and less error-prone.

Conclusion

Vibe coding may be fun and fast for side projects, but its risks—hidden bugs, technical debt, and wasted cleanup time—make it unsuitable for professional software development. Spec-driven development offers a practical alternative that retains the productivity gains of AI code generation while imposing the discipline needed for high-quality results. By treating a spec as a contract for behavior, teams can enjoy the best of both worlds: faster code generation and reliable, maintainable systems.

If you are considering using AI to write code, start by writing a clear spec. It will save you from the troubles of vibe coding and ensure your project doesn’t just “mostly work” but works correctly, every time.