Spec-first vs Vibe-first

Two camps. Again.

Team Spec-first says: write the contract before you write the code. Capture intent. Make the agent — and your future self — generate against a precise document. Without the spec, you're just producing impressive-looking entropy.

Team Vibe-first says: the spec is the bottleneck. Describe what you want in plain language, let the agent build a working version, then look at it and decide what you actually wanted. Shipping reveals the spec faster than meetings ever did.

If you've spent any time on engineering Twitter or in a senior eng leadership meeting in 2026, you've watched this play out. Each camp acts like the other is committing professional malpractice. Each camp has a stack of victories to point to. And each camp has a stack of postmortems they don't talk about.

This is the second post in Don't Pick a Side. The premise of the series, in case you missed the first: a lot of the loudest debates in AI engineering look like opinions and resolve into context-dependent decisions. Treating them as identity wars is how teams pick the wrong tool, write the wrong prompts, and ship the wrong systems.

Spec-first vs vibe-first is, for me, the cleanest engineering example. Anthropomorphization was the cleanest human one. Both lead to the same conclusion: the right answer isn't a tribe, it's a rule.

A few years ago, "spec-first vs ship-first" was a methodology argument. It belonged in books about Waterfall and Agile, and you could ignore it after you graduated. In 2026, three things have made it engineering policy.

First, agents are now generators, not assistants. When the agent writes the code, your spec is no longer a coordination tool with your colleagues. It's the input to the build. A vague spec produces vague software, instantly, in volume. A precise spec produces a working artifact in minutes. The quality of the upstream document is now directly proportional to the quality of the downstream system.

Second, vibe-coding actually ships. "I described what I wanted in plain English and walked away" is not a meme. People are shipping real, useful tools that way — internal dashboards, marketing pages, automation scripts, side projects that take revenue. The barrier to "make a thing that solves the problem" has collapsed. Pretending it hasn't is just pride.

Third, the cost of being wrong has gone asymmetric. Vibe-coding a billing migration and getting it wrong is a production incident. Spec-firsting a Friday-afternoon prototype is calendar suicide and a tool that ships next quarter, by which time the problem has changed. The error in either direction is now cheaper to make than ever before, and the consequence is bigger.

So three forces, pointing different directions. None of them are crazy.

The strongest version of Spec-first is not "documentation is good." It's something more uncomfortable.

You don't actually know what you want. You think you do. You've been told you do. But the act of writing a precise spec — acceptance criteria, non-goals, edge cases, the data model — is the act of discovering the contradictions you'd otherwise discover three weeks into the build, when it's expensive to fix. The spec doesn't slow you down. It surfaces the cost early, where it's cheap.

The agent needs more than you think. Drew Breunig has a piece I keep referring to, the Spec-Driven Development Triangle: spec, code, tests, and the trick is that all three have to stay in sync, in a loop, forever. The spec drives the first generation. The code reveals what the spec missed. The tests are the durable assertion that you understood. If any of the three goes stale, the system rots. With agents, this rot happens faster than ever — because the agent will happily regenerate against the stale document and you won't notice until production.

Your code is going to be regenerated. This is the part the vibe camp hates and the spec camp keeps forgetting to say out loud. In an agentic workflow, the code is not the artifact. The spec is the artifact. The code is the regenerable output. When a new model lands, when the language evolves, when the underlying library updates — the spec is what you keep. The code is what you re-roll. Specs without implementation feedback are wishes. But code without captured intent is technical debt by definition.

The cleanest version of Spec-first is: the discipline of writing precise specs is the discipline of figuring out what you mean, and that's the engineering work — the code is just the proof that you did it.

The strongest version of Vibe-first is not "specs are dead." It's something more practical.

Most things are throwaway. A precise spec for a prototype, a one-off internal tool, a Friday demo, a quick automation that saves you twenty minutes a day — that's not engineering, that's ceremony. The cost of writing the spec is greater than the cost of building the thing and discarding it if it doesn't work. The spec camp keeps forgetting that not every artifact deserves the same overhead.

The spec is a hypothesis. What you write before you start is not what you want. It's your best current guess at what you want. The fastest way to test that guess is to build the thing and look at it. A 30-second vibe-prompt followed by a 5-minute review of the result will teach you more about what you really wanted than two days of spec workshop. The build is the test. Iterate the build, not the spec.

Specification theater is a real thing. Anyone who lived through the late 1990s remembers what happens when a culture worships its specifications: 200-page documents that nobody reads, sign-off ceremonies that take longer than the implementation, and a final product that diverges from the spec by the time it ships because nobody had the energy to update the document. The spec camp pretends this is solved. It isn't. It just looks different now, with prettier templates.

Discovery cost is the real cost. Some problems you cannot specify because you don't know what they are until you've built something close. Most exploratory work falls in this category — new products, new internal tools, new categories. Vibe-first is what happens when you accept that the discovery is the point, and the spec emerges from the discovery, not before it.

The cleanest version of Vibe-first is: the discipline of shipping fast and looking at the result is the discipline of telling the truth about what you actually wanted, and that's the engineering work — the spec is just the post-hoc record of what you learned.

I don't pick a side. I pick the appropriate side per artifact.

Spec-first when the artifact has any of these properties:

Vibe-first when the artifact has any of these properties:

The two regimes are different because the artifacts are different. The same engineer should be capable of writing a careful 12-page spec on Tuesday for a migration that will touch every customer, and prompting a working internal dashboard in five minutes on Wednesday afternoon. Pretending the same posture should apply to both is the mistake.

The error that kills teams is using the wrong mode for the artifact: vibe-coding the migration and shipping an incident, or spec-firsting the prototype and shipping nothing. Both errors have the same shape — they confuse the artifact for an identity statement about the engineer.

This is what I mean by don't pick a side. The right answer isn't a tribe. It's a rule for when each tribe is right.

The triangle most people quote is: spec, code, tests, all kept in sync, in a loop, forever. Without the loop, the system rots. I'd add a fourth corner that comes from the vibe side and that most spec-first writeups quietly skip:

The last one is the discipline the vibe camp owes the rest of us. Shipping fast is fine. Shipping fast and never going back to ask "what did I learn here that should now be written down" is how organizations accumulate hundreds of one-off tools nobody understands. The vibe is the start of the spec, not the absence of one. The retro is what closes the loop.

Spec-first works if and only if the spec stays alive. Vibe-first works if and only if the lessons get captured. Both modes require a cycle. Neither survives as a one-shot.

If you ship anything serious that uses agents, this is the version of the discussion worth having:

These are not philosophical questions. They have answers. They affect calendar time, incident rate, the quality of the system after a year, and what your engineers become after a year of practicing whichever discipline you actually instilled.

Most teams haven't answered any of them. Most teams have, instead, picked a side, and then complained that the other side keeps embarrassing them.

When I write a careful spec, it's because I have to convince my future self I knew what I was doing. When I vibe a prototype, it's because I have to convince me that I should start at all.

Both jobs are the same job, in different lighting. They are not opposed. They are the two halves of the same engineering instinct — to make the thought precise, and to make the thought real — and the only mistake is pretending one of them doesn't matter.

The debate is fake. The discipline is real. Pick the right mode for the artifact, run the loop honestly, and stop using either choice as a flag you wave at the people who chose the other one.

This is the second issue of Don't Pick a Side. The next one is about reactive vs present agents — what it means for an agent to "be there" when nothing is happening. If you build with agents and want the next post when it lands, subscribe — and tell me which tribal debate is annoying you most right now.