What Spec-Driven Development Is (and Why We Left Vibe Coding Behind)

There is a way of working with AI that feels productive but isn't. You tell the model "build me a signup form," you look at what it returns, you don't like it, you say "no, not like that," you look again, you fix it again. You move forward in fits and starts. It's called vibe coding: asking the machine to see what comes out and haggling with the result. It works for a toy. It falls apart the moment something real is at stake.

The failure isn't in the model or in your prompt. It's in the order. You started with execution without ever having written down what "correct" was. Without that upfront contract, any output is defensible and none is verifiable. At Qirava we abandoned that way of working and adopted another: the specification first, execution afterward. It's called Spec-Driven Development, SDD.

01 · the shiftSpecification first, execution afterward

Spec-Driven Development means exactly what it says: development is steered by the specification, not by impulse. Before an agent or a person touches anything, there is a document that fixes what is wanted, for whom, within what limits, and how you'll know it turned out right. That document isn't paperwork: it's the source of truth that governs everything that comes after.

The difference from basic prompting runs deep. A basic prompt describes a loose task and waits for an output. The spec describes the expected result and the acceptance criteria, and then execution is measured against it. In vibe coding, you are the criterion (whatever you like passes). In SDD, the criterion is written beforehand and is independent of your mood on any given day.

In vibe coding, the criterion for "correct" is you. In SDD, it's written down before you start.

This isn't a new idea from the AI era. For more than two decades Amazon has worked "backwards" (working backwards): before a product is built, the press release and the frequently asked questions it would have on launch day are written first [1]. The result is drafted first, and only if that result convinces does anyone build it. SDD takes that discipline and puts it at the front of model-assisted development.

02 · governanceThe spec governs the agents, and the gates hold back anything premature

At Qirava the spec isn't a file someone reads and forgets. It's what governs the agents. Every agent is born under governance: on startup it loads a universal skill (qirava-llm-governance) plus the skill for its role. Nobody executes "at their own discretion."

Roles are skill packages with a fixed structure: a universal one everyone shares, a primary one specific to the role, supporting secondary ones, and a list of skills forbidden for that role. So natalia.marketing.ai writes campaigns but doesn't approve architecture; santiago.architect.ai defines structure but doesn't certify quality; sofia.qa-sprint.ai validates; martin.legal.ai, beatriz.ciso.ai and marcos.scrum.ai cover their own ground; and libaniel.ceo.human approves. Every agent knows what it can do and what is off-limits before it lifts a finger.

But writing the spec isn't enough: you have to keep anything green from getting far. That's what the maturity gates are for. Nothing advances without passing its own. An element is born G0 (specified). Only if it passes validation does it reach G1 (draft). Only with CEO approval does it reach G2 (operational). And whatever aspires to decide on a broad scale rises to G3 (council). There are no shortcuts: each gate is a real filter.

03 · the mechanicsHow it holds up day to day: the index, the skills, and QA with regression

A spec without a source of truth scatters into versions that contradict each other. That's why the method rests on a DOCUMENT_INDEX: the documentary index that says which document is the valid one for each thing. The skills live in a toolkit; governance lives in a vault; and projects consume them by symlink, without copying or forking. One place rules; everything else points to it.

The last piece is quality. In SDD, QA isn't pressing a button until it "passes." It's a loop with professional regression: you test, you log findings, you fix them, and you re-test the whole set, not just what failed, until it's certified. No tailored retests just to turn things green. You certify against the spec or you don't certify. Because the spec fixed beforehand what "correct" was, QA has a pattern to measure against, and that's precisely the piece vibe coding never had.

Without a spec, QA has nothing to measure against. With a spec, "correct" stopped being an opinion.

Put the three parts together and the full change comes into view. The spec fixes the result before you start. Governance bounds what each agent can do, and the gates hold back whatever isn't mature. The index keeps a single truth and QA certifies against it with regression. None of that exists when you ask a model to "see what comes out."

That's why we left vibe coding behind. Not because AI is bad at writing, but because a result without a specification can't be governed, verified, or repeated. The next time you're about to ask a model for something, try writing first, in two lines, what "done" would look like. That line, not the prompt, is what changes what comes out.