Vibe Coding works until production. Then you need a Spec

Pull request open, builds green, code review approved by the agent and by two humans. The feature ships and support starts getting tickets about weird login behavior. You open the code, everything is syntactically correct, tests pass. The problem is that the business rule never made it into the code. It stayed in your head when you wrote the prompt.

That is the point pasquadev raises in a recent video about Vibe Coding, and it is worth unpacking. Vibe Coding works. But there is a layer of professional usage it does not cover, and ignoring that is costing teams real money.

What is happening

Vibe Coding is the informal name for how most devs ask AI to do things today. You open Cursor, Claude Code, Copilot, and type “implement user authentication with email and password”. The AI ships 500 lines, it looks clean, you commit it.

The problem is structural. An LLM (Large Language Model) picks the next token based on probability. It has no ground truth about which contract you expect. It infers. Take the same vague prompt, run it 10 times, you get 10 different implementations. Some will use JWT, others sessions. Some will validate before hitting the database, others after. Some will reveal whether the email exists in the error message, exposing a user enumeration vulnerability.

Here is the detail few people notice: the more capable the model, the worse this gets. Two years ago, a vague prompt broke early. Code did not compile, a test failed, you noticed in minutes that you had to be more specific. Today, the same vague prompt produces 500 lines that compile, have passing tests, and still violate the business rules you had in mind.

Why you should care

The industry has evolved what the primary artifact of development is. In the traditional model, code was what mattered. You wrote code based on intuition, documentation came later (when it came at all). With TDD (Test-Driven Development), the primary artifact became the test: you write the test first, watch it fail, implement until it passes.

Spec-Driven Development (SDD) goes one level up. The primary artifact is the behavioral specification. You describe the contract before writing any line of code or test. From the spec you derive the design. From the design you derive the tests. From the tests you derive the code.

This is not academic theater. It makes practical sense in the AI era for one simple reason: AI is excellent at executing specific instructions and terrible at guessing intent. Probability is not a business rule. When you delegate to the AI the decision of “which status to return when the email does not exist”, you are asking it to decide a rule of your product. It will pick the statistically most likely option, not the one that is correct for your domain.

The cost of skipping SDD is not code that looks worse. It is code that looks correct and is silently wrong.

How to apply this tomorrow

A spec is not a long prompt. That is the most common mistake. You can write 800 characters of vague prompt and still have no spec. What defines a spec is the contract, not the length.

A minimum viable spec for an authentication feature has four elements:

Input contract. Which endpoint, which HTTP method, which body schema, which required headers.
Output contract. For every possible case (200, 401, 422, 429), what the response body looks like. Include the error type as a code (account_locked, invalid_credentials, email_not_found_obfuscated).
Edge cases. What happens when the email does not exist? The correct answer in most cases is the same as wrong password, to avoid leaking user enumeration. You have to decide this explicitly.
Business rules. Lockout after 5 attempts, time window, password hashing, token expiration. Things that are your call, not the AI’s.

These four elements fit on one page. You pass that document to the AI along with the implementation request. The difference in the output is absurd.

Vibe Coding: building in practice

Here is the same goal (email-and-password authentication) written both ways.

Approach 1: Pure Vibe Coding

Vibe Coding prompt

Implement user authentication with email and password. Use JWT. Show an error if it fails. Lock the account after a few attempts.

Typical output: the AI picks the framework, decides the error status code, chooses whether to validate before or after the database, sets the token expiration, and leaks (or not) the email existence in the error message. Each of those is an implicit business rule. You made none of those decisions.

Approach 2: Spec-Driven

Spec-Driven prompt

Implement the POST /auth/login endpoint following the spec below. INPUT CONTRACT - POST /auth/login - Body: { email: string, password: string } - Content-Type: application/json OUTPUT CONTRACT - 200: { token: string, expiresIn: 3600 } - 401 invalid_credentials: { error: "invalid_credentials" } (used for both nonexistent email and wrong password, to prevent enumeration) - 423 account_locked: { error: "account_locked", retryAfter: number } - 422 invalid_input: { error: "invalid_input", fields: string[] } BUSINESS RULES - Lockout after 5 failed attempts within a 15-minute window - Lockout lasts 30 minutes - JWT token expires in 1 hour, signed with HS256 - Password hashed with Argon2id before comparison - Validate email format before querying the database DO NOT - Reveal whether the email exists in error messages - Return 404 when the email does not exist - Log the password in plaintext anywhere

Output: the AI implements exactly what you described. Zero guessing. If it has to decide something outside the spec, it asks or marks a TODO. Production behavior is predictable.

Efficiency comparison

Abordagem	Tokens	Custo	Qualidade	Tempo
Pure Vibe Coding	~80	$0.001		8s
Spec-Driven	~450	$0.006		22s

Spec-Driven costs 6x more in tokens and takes about 3x longer to generate. In return, you get no rework, no business-rule bugs in production, no late-stage code review surprises. The ROI is absurd.

Glossary

Vibe Coding: AI-assisted programming style where the developer describes the task briefly and vaguely, letting the AI infer the rest. Works for prototypes, fails in production.
Spec-Driven Development (SDD): approach where the formal specification of behavior is the primary artifact, written before the design, tests, and code. Natural evolution of TDD and BDD.
TDD (Test-Driven Development): cycle of writing the test first, seeing it fail, implementing the minimum to pass, refactoring.
BDD (Behavior-Driven Development): variation of TDD where tests describe expected behaviors in language close to the business domain.
SDLC (Software Development Life Cycle): traditional development cycle, with phases of planning, requirements, design, implementation, testing, and maintenance.
LLM (Large Language Model): large language model, such as GPT-5 or Claude 4.7. Generates text by picking the most probable next token, not by querying a ground truth.

Your next move

Pick a feature you are shipping this week. Before opening your editor, open a .md file and write the four blocks: input contract, output contract, edge cases, business rules. Spend 15 minutes on it. Then pass that document to the AI. Compare the result to your last Vibe Coding feature. The difference will be obvious on the first try.

Fontes

Vibe coding não é suficiente — pasquadev