The End of Vibe Coding: Plan First

You said one sentence to Claude Code. Two minutes later, a registration page is running.

Forms can be submitted. Validation has hints. The UI is clean and tidy.

You’re about to pop the champagne, but then you glance at that yellow warning box——

“Password must be unique. This password is already in use by user r***88. Please choose a different password.”

The Agent built you a registration system that exposes other users’ password information.

It didn’t write a single line of code incorrectly. The form validation triggers perfectly, the hints are clear and friendly. The problem isn’t the code—it’s that the “registration page” in your head and the “registration page” the Agent understood are completely different things. You didn’t tell it passwords should be hashed one-way. You didn’t tell it error messages shouldn’t distinguish between “user doesn’t exist” and “wrong password.” You didn’t tell it to never expose any information about another user in the UI.

You saved one hour of requirement description time. You spent three hours searching through all the code for bugs like this, fixing them one by one.

This isn’t a bug. This is what vibe coding really looks like in 2026.

Describing Requirements ≠ Defining Them

The term “vibe coding” was born in late 2024. At the time, it meant “tab-completing on vibes until the program runs” in Cursor—Andrej Karpathy’s famous phrase “fully give in to the vibes” painted a picture: developers no longer thinking, just constantly pressing Tab.

Two years on, vibe coding has leveled up. You no longer need to spam Tab—you just open Claude Code or Codex and say one sentence to the terminal. The Agent analyzes your codebase, generates the implementation, runs tests, and creates a PR. You don’t even need to know exactly what it wrote. This is what Andreessen Horowitz recently described as the shift “from keyboard-first to intent-first”: you express your intent, and the Agent executes.

But there’s a fundamental confusion here: Describing what you want to do and defining what you should do are two completely different things.

OpenAI, in A Practical Guide to Building Agents, defines an Agent as “a system that can independently complete an entire workflow for you.” The problem lies precisely in the word “independently”: the Agent is independent, but its judgment is still based on all the assumptions implicit in your brain when you typed that sentence—those assumptions you never said out loud and the Agent could never guess.

You thought you said “registration page.” The Agent thought you said “a form page that can receive email and password, validate format, show errors, and complete registration.”

It perfectly implemented the version it understood. It just didn’t know—and you didn’t tell it—that passwords can’t be compared in plaintext, error messages can’t distinguish between users, and emails can’t be exposed to other users’ sessions.

DeepLearning.AI put it bluntly in their SDD course: “Vibe coding is fast, but it often produces code that doesn’t match what you asked for. Spec-driven development is the disciplined alternative.” It’s not that the Agent isn’t smart enough. It’s that natural language itself is not a precise interface.

Ambiguity Isn’t a Bug, It’s the Default State of Natural Language

Every natural language is built on shared context. When two people talk, they draw on decades of living in this world together to fill in the unspoken parts. You say “let’s eat,” and the other person knows you don’t mean breakfast. You say “turn off the light,” and the other person knows you’re referring to the brightest light in this room. The deeper the shared context, the more concise the language.

You have no shared context with the Agent.

When you say “help me build a registration page,” the only reference the Agent has is the average of tens of thousands of “registration pages” in its training data. That average has an email input, a password field, a confirm password field, and a register button—but it doesn’t have a rule like “don’t expose other users’ passwords.” Because most registration pages in the training data don’t consider that either—they’re just UI demos, not real security systems.

This isn’t a vulnerability of the Agent. It’s a systemic property of natural language: every sentence you speak omits countless details. When talking to a human, those details are automatically filled in by your shared experience. When talking to an Agent, those details are automatically filled in by the average of the Agent’s training data—but that average is not your experience, nor your project’s standards.

The requirement clarification time you saved hasn’t disappeared. It has been deferred. Deferred until after the code runs.

When you go back to fix bugs, patch security holes, and correct business rules that “look fine but are completely wrong logically,” you’re repaying the requirement description time you saved in your prompt with debugging time. The cost of debugging is much higher than requirement description—not only because you have to dig through code, locate issues, and verify fixes, but because you’ve already built something in the wrong direction. That something becomes sunk cost for future rework.

A more precise way to put it: you have shifted the “understanding cost” from before the Agent starts to after the Agent produces output. The unit price of the latter is far higher than the former.

A Counterintuitive Comparison: Slow at the Start, Fast All the Way

Let’s return to that registration page case. If, when you got this task, you first spent fifteen minutes turning the pitfalls you’ve fallen into, the lessons you’ve learned, and the unwritten rules in your project—those things that used to live only in your head and your team’s Slack chat history—into a structured specification. You could write it yourself, or you could say to Claude Code, “Help me organize a set of security constraints and acceptance criteria for the registration feature,” then review its output, modify what you disagree with, and add what you missed. After that, you’d have something like this:

Registration Feature Spec

Overview: Provide email-based registration entry for the platform. Users create an account via email + password. After successful registration, redirect to login page. This iteration only covers email registration; social login and email verification are planned for future versions.

User Flow: Visit /register → fill in email + password + confirm password → frontend validates format → POST /api/auth/register → backend validation → write to database → return success, frontend redirects to login page.

Data Fields

• email: string, required, RFC 5322 format validation (both frontend and backend)

• password: string, required, minimum length 8 characters (product decision: no uppercase/lowercase/special character complexity requirements to reduce registration friction)

• created_at: auto-generated

Security Requirements

• Passwords stored with bcrypt, cost factor ≥ 10, one-way hashing

• Error messages are not overly vague: distinguish between “this email is already registered” and “password too short”—both are situations the user can fix, so hiding them isn’t necessary. However, do not expose any associated account information (e.g., registration time, last IP, etc.)

• API responses must not return other users’ data, even in anonymized form

API

• POST /api/auth/register, request body { email, password }

• Success → 201, body { message: "Registration successful" }

• Failure → 400 (validation failure) or 409 (email conflict), body { error: string }, only containing user-actionable messages

Edge Cases

• Empty fields → 400, specify which fields are required

• Leading/trailing spaces in password → auto-trim

• Duplicate submission (race condition) → database unique index as fallback

Out of Scope (Current Iteration)

• No verification email

• No social login (Google / GitHub / WeChat)

• No CAPTCHA / registration rate limiting (launch first, add monitoring for abuse later)

Acceptance Criteria

• New email + valid password → 201, database password field is bcrypt hash

• Already registered email → 409, prompt “This email is already registered”

• Password < 8 characters → 400, prompt password length insufficient

• Invalid email format → 400, prompt email format incorrect

• Any required field empty → 400

• No other user’s identifying information appears in API responses

Those fifteen minutes felt “slow.” You weren’t writing code; you were writing what looked like a requirements document. Fifteen minutes passed, and you hadn’t written a single line of functional code.

But after the Agent read this spec—it got it right in one shot. It didn’t take shortcuts on password comparison. It didn’t get over-friendly with error messages. It didn’t append “oh, by the way, the user next door has the same password as you, want to change yours?” to the response. Because you wrote those constraints into the spec.

In the scenario without a spec, you typed that one-line prompt in seven seconds, and the Agent started chugging away—the fourteen minutes and fifty-three seconds you saved will be repaid over the next three days as: locating the “password uniqueness” prompt that leaked other users’ passwords ≈ 30 minutes, investigating why passwords are stored in plaintext ≈ 1 hour, refactoring error message logic ≈ 2 hours, writing security patches + tests ≈ half a day, explaining to your tech lead “why the last code review didn’t catch this”: incalculable.

Seven seconds saved, three days to repay.

You Think This Is Methodology Promotion; It’s Actually Survival Instinct

Philippe Haldermans is a technical lead in Belgium. In 2025, he wrote an article that went viral on Medium—Building Software with AI Agents: A Practical Guide Using OpenAI Codex. He opened with a blunt truth: “The difference between a demo and something production-worthy is mostly discipline: clear specs, tests, and boundaries. Without that, you move quickly but drift into rework.”

His team wasn’t taught SDD by some consulting firm. They fell into the pit themselves and climbed out. They started with pure prompt-driven development—saying to Codex, “Help me build an X.” Codex built it. It looked good. They shipped it. Problems arose. Rework. After repeating this several times, the team naturally evolved a workflow of “write the spec first, then hand it to the Agent.” Haldermans called this evolution “from prompting to process.”

The article was updated in June 2026. In the update, Haldermans said something that might be more telling than the original: “My thinking has moved on since I wrote this.” Meaning, the methodology is still evolving—because the AI Agent itself is still evolving. But one direction he’s more certain of: documentation is not secondary. It’s not something you “write after the code is done.” It’s not bureaucracy. Documentation is the infrastructure of the Agent workflow.

This isn’t an isolated story. The widely cited article From Vibe Coding to Spec-Driven Development on Towards Data Science records a nearly identical evolution path: the author started with vibe coding—“describe a feature, and the Agent gives you a working version”—then gradually found the code drifting constantly, with each new feature creating unexpected interactions with old ones. He began writing a constitution and a spec before every coding session, then handing it to the Agent. The result: using the SDD approach, he completed a full fitness app MVP in 4.5 hours—from spec to a runnable prototype.

4.5 hours for a fitness app. If he’d taken the vibe coding route, the code might have taken 2 hours—and two weeks to fix the bugs.

DeepLearning.AI said the same thing in a different language. They called the course Spec-Driven Development with Coding Agents, which translates directly to “coding with Agents using specifications.” The core argument of the course is extremely simple: vibe coding is fast but unreliable; SDD is a repeatable engineering method. You write a Markdown spec, the Agent implements it, you review it—this cycle is controllable, iterable, and verifiable.

“Many of the best developers already work this way.” That sentence isn’t a course slogan. It’s a fact that’s happening: the best developers have spontaneously moved to documentation-driven workflows, not because someone wrote a white paper, but because they can’t survive otherwise.

The most-cited article—Andrej Karpathy’s own famous long tweet-thread from 2025—while talking about vibe coding, also gave a key self-correction: “I found that when I started giving the AI more detailed constraints and goals, the output quality improved dramatically. Essentially, I was writing specs in natural language.”

Even the inventor of the term “vibe coding” is secretly writing specs.

You’re Not Writing Documentation; You’re Establishing Alignment Anchors

The name “Spec-Driven Development” is easy to misunderstand. It sounds like a heavy process: you have to write lots of documents, fill out many forms, and go through a long approval chain before you start coding.

It’s not.

The core operation of SDD is: before you let the Agent start working, you spend a little time structurally defining three things—

• What success looks like (acceptance criteria: what level of completion counts as “done”)

• What the lines are (constraints: what the Agent absolutely must not do, no matter how much better it thinks its way is)

• What the boundaries are (scope: where this task ends—the Agent should not extend itself into adjacent features)

These three things don’t need to be long. The registration page spec didn’t even fill a page. The template Haldermans demonstrated in his article—AGENTS.md, containing project overview, commands, repository layout, spec file locations, coding conventions, and domain rules—totals less than a thousand words. A thousand words. In exchange for the Agent avoiding five fewer traps.

Its essence is not “writing documentation”; it’s establishing alignment anchors—a shared understanding that both you and the Agent can reference. At the moment you type your prompt, you have a complete picture in your head: passwords must be hashed, messages must be vague, emails must not be leaked, formats must be validated—but the Agent can’t see that picture. The spec is the text version of that picture. It turns the 100 implicit constraints you didn’t say out loud into explicit conditions the Agent can read and follow.

Academic research confirms the same thing. A 2025 arXiv paper analyzed 253 CLAUDE.md files across 242 real repositories—a project description file placed in the project root directory specifically for Claude Code to read. The study found that these manifest files are becoming the Agent’s runtime context: they define the project’s identity, operational boundaries, what can and cannot be done. Another paper covering five tools—Claude Code, GitHub Copilot, Cursor, Gemini, and Codex—further found that the AGENTS.md file format is becoming a cross-tool industry standard: project documentation is shifting from “human collaboration document” to “Agent configuration layer” [arXiv:2509.14744, arXiv:2602.14690].

This isn’t a future trend. It’s a fact that has already happened. The CLAUDE.md in your project isn’t for humans—it’s for the Agent. It reads it every time it starts. You’re not writing documentation; you’re programming—programming the Agent.

Next Time You Open Claude Code, Don’t Rush to Speak

Haldermans has a passage at the end of his article that might be the most worth remembering: “When you hand Codex a spec, you’re not asking it to ‘build something.’ You’re handing it a contract and saying: this is what success looks like.”

Think of the spec as a contract. You don’t need a long essay. You don’t need perfection. You just need, before the Agent starts working, to write down the most important constraints clearly and put them where the Agent can read them.

This won’t slow you down. This will make you truly fast—not the speed of “the first version appearing,” but the speed of “the final version being delivered.” The former is the illusion of vibe coding; the latter is the true rhythm of engineering.

Next time you open Claude Code and want to say “help me build a registration page,” take 10 minutes to write a spec first. You’re not saving 10 minutes.

You’re saving 3 days.

References

• Haldermans, P. (2025). Building Software with AI Agents: A Practical Guide Using OpenAI Codex. Medium.

• DeepLearning. AI. (2025). Spec-Driven Development with Coding Agents. Short course, taught by Paul Everitt (JetBrains).

• Towards Data Science. From Vibe Coding to Spec-Driven Development. Describes the 4.5-hour fitness app MVP case study.

• OpenAI. (2025). A Practical Guide to Building Agents. Official documentation.

• On the Use of Agentic Coding Manifests: An Empirical Study of Claude Code (arXiv:2509.14744). Analysis of 253 CLAUDE.md files across 242 repositories.

• Configuring Agentic AI Coding Tools: An Exploratory Study (arXiv:2602.14690). Covers AGENTS.md as an emerging cross-tool standard across Claude Code, Copilot, Cursor, Gemini, and Codex.

This article was automatically formatted from Markdown by YouMind.