You probably know the scene. You open your smart code editor, throw a casual three-line prompt loosely explaining a new feature you need, and five seconds later you're staring at the screen in awe as the AI spits out two hundred lines of flawless TypeScript code. You hit accept with a massive dopamine rush. You feel like you're moving ten times faster. Everything seems to be going smoothly.
But two weeks go by and the invention starts to stutter. That initial speed was a mirage. It turns out the agent took shortcuts you didn't see, skipped the clean architecture rules you worked so hard to set up, left silent compiler warnings, and filled the repository with small logical inconsistencies. You try to fix it by throwing more "patch on patch" prompts at it, but the AI starts getting amnesia, hallucinates, and you have to manually dig into the code for hours to undo the mess.
You've just hit the wall of "Vibe Coding" (programming by vibes or intuition).
Today we're going to talk about why this inertia of programming "by feelings" is unsustainable if you're building something serious, and how Spec-Driven Development (SDD) is applied on a day-to-day basis. Don't take it as just another boring methodological trend; it's the only real governance chassis that works when you let AIs touch your code.
1. The Ferrari on the Dirt Road: Why Vibe Coding will blow up in your face
A very visual way to understand productivity with AI right now is to think of the paradox of buying a Ferrari and driving it on a muddy dirt road. The engine is an untamable beast, but your arrival time is going to be decided by the condition of the terrain.
The engine (language models) has completely changed, but our roads (how we validate, test, and organize repositories) remain the same as always. Programming "by vibes" consists of stepping on the gas pedal without paving the ground. It's a chaos where the developer accepts any code that "seems to work" without a rigorous design contract behind it.
This generates three real headaches that end up breaking any medium-sized project:
- Cognitive debt and loss of control: Code isn't just syntax that compiles; it's the reflection of a business model the team has to understand. When an agent generates code at breakneck speed, it introduces new abstractions, interfaces, and terms at a rate humans can't digest. The codebase becomes giant and complex, while the team understands less and less how their own system works.
- Unintentionally slipped vulnerabilities: Trusting that an AI writes secure code by default is having a lot of faith. Security analysis shows that over 70% of AI-generated vulnerabilities tend to be critical or blocking level if left unsupervised. Letting AI code freely without a harness to control what gets uploaded is, statistically, playing Russian roulette with production.
- Fake speed: In real projects, typing code faster on your screen doesn't mean the team delivers sooner. All you achieve is filling the repository with warnings, coupled code, and cyclomatic complexity that someone (probably ourselves) will have to clean up in the next refactoring sprint. In short: you go very fast, but straight towards the cliff.
To stop this madness, we have to move control one step to the left. We have to stop being interactive "key punchers" and start acting as Contract Engineers. And that's where SDD comes in.
2. What is Spec-Driven Development (SDD)?
SDD brings a slap of reality that makes you see things differently: source code is no longer king.
For decades, we've treated code as the "Single Source of Truth" (SSOT). Documentation, architecture diagrams, and specifications were mere papers we wrote at the beginning with much enthusiasm and then threw in the trash as soon as the real code began to deviate.
In SDD we flip the script: Markdown specifications stop being dead text and become executable, first-class contracts that govern implementation.
┌─────────────────────────────────────────────────────────────┐
│ The SDD Flow │
├─────────────────────────────────────────────────────────────┤
│ │
│ Written Specification (Markdown Design Contract) │
│ │ │
│ ▼ │
│ AI Agent Harness ◄─── Constrained by Governance │
│ │ │
│ ▼ │
│ Source Code (Ephemeral and Regenerable Byproduct) │
│ │
└─────────────────────────────────────────────────────────────┘Under this approach, source code becomes an ephemeral, transient, and continuously regenerable byproduct. If system behavior fails or we need to change something, the golden rule is strict: we never touch the code by hand. We modify the Markdown specification, let the agent understand the new contract, and regenerate the entire implementation.
3. The Three Altitudes of SDD (How deep do you want to go)
This SDD thing isn't black and white. It can be applied at different levels depending on what the team needs and the type of project at hand:
Altitude 1: Spec-First (To start without complicating things)
- The rule: The specification is your initial guide.
- How it works: You write a super-detailed Markdown file explaining the business logic, APIs, and test cases you want before asking the AI for anything. The agent reads this file in a clean session, generates the code for you, and that's it. Once the code is working and in production, it usually doesn't matter if the specification gets outdated. It has fulfilled its scaffolding role.
- When to use it: If you're alone, for quick prototypes, an afternoon's refactoring, or if you want to start testing this flow without changing the way your whole team works.
Altitude 2: Spec-Anchored (The production standard)
- The rule: Specification and code co-evolve and live together in Git.
- How it works: The Markdown specification lives permanently in the repository alongside the code. If the business asks for a change or if a technical limit is discovered while progressing, the first thing done is updating the specification. Continuous integration (CI) pipelines validate that the code hasn't deviated from the original design.
- When to use it: For professional projects, customer-facing APIs, microservices architectures, or medium teams where several people touch the same repository. Prevents the project from becoming an unmanageable monster over the months.
Altitude 3: Spec-As-Source (The radical "AI-First" horizon)
- The rule: Humans are forbidden from touching production code.
- How it works: The only file that is touched, edited, and versioned is the logical or mathematical specification in an ultra-structured format. An isolated agentic compiler reads that specification and generates 100% of the base code. In fact, if you open any code file, you'll see a giant comment that says:
// GENERATED FROM SPEC - DO NOT EDIT. - When to use it: Microservices with highly isolated mathematical or business logic, strongly typed APIs, or pure data processing engines. It's the cleanest level but requires a brutal level of technical maturity to control that the AI doesn't mess up during compilation.
4. Face to face: SDD vs. Traditional
To clearly see what we're talking about, you can compare SDD with the traditional tools and methodologies usually used in projects.
The requirements document: Classic PRD vs. Technical Design vs. SDD Spec
| Criterion | Requirements Document (PRD) | Technical Design Document | SDD Spec (Executable Contract) |
|---|---|---|---|
| Who reads it? | Humans (Product Managers, Engineers) | Team engineers to align | The AI agent and your validation tools |
| How are doubts resolved? | With endless meetings, coffees, or developer assumptions | Discussions in the doc or loose comments | With explicit logical rules and automated tests |
| How often is it updated? | Almost never. Usually outdated on day one of development | It's static. A snapshot of how you planned to do things | It's a living file. Continually changes as the project advances |
| Where does it live? | In Confluence, Notion, or similar | In shared Drive folders or an isolated PDF | Versioned in Git, right next to the repository code |
Development methodologies: TDD vs. BDD vs. Vibe Coding vs. SDD
Here is the real contrast of how daily work looks depending on the chosen methodology:
| Dimension | Test-Driven Development (TDD) | Behavior-Driven Development (BDD) | Vibe Coding | Spec-Driven Development (SDD) |
|---|---|---|---|---|
| Primary Artifact | Low-level unit tests | Conversational scenarios (Given/When/Then) | Free prompts in the IDE chat | High-fidelity Markdown specification |
| Technical Focus | That a class or function does what it should | App behavior from the user's POV | Modifying code directly as deemed fit | Integration contracts and architectural consistency |
| How it's validated | Running the test suite in console | Manual or automated top-level tests | "It works on my machine" | Static validators and continuous injection of business rules |
| AI Governance | None (a human writes the test) | None (user specs don't hold the agent back) | Non-existent (the AI decides how to solve the problem) | Constitutional constraints and error feedback loops |
| Source of Truth | The test suite | Design meetings and integration code | Chat history that gets wiped upon closing | The technical specification versioned in Git |
Conclusion: Your new role as a Contract Designer
Adopting Spec-Driven Development doesn't mean we're going back to the dark ages of the Waterfall model where we spent months writing documentation before programming. It's exactly the opposite: it's putting an iron spine into the absurd speed autonomous agents give us.
Since the cost of translating a detailed specification into functional code is now practically zero thanks to AI, the job as a developer completely changes: you stop fighting with syntax to become a designer of logical decisions.
The day-to-day won't consist of debugging a missing semicolon or typing out a repetitive CRUD service for the umpteenth time. Now the value is in designing flawless logical contracts, protecting the repository with an inviolable Constitution, and auditing the decisions agents propose before giving them permission to touch the codebase.
In the next article, The Governance Chassis: Constitution vs. AGENTS.md (And how not to drown in sync debt) we'll get deep into the mud to see how to structure the repository to cleanly separate the Project Constitution (immutable architecture rules) from specific agent configurations like AGENTS.md or CLAUDE.md. Plus, we'll analyze a real bug from the Spec Kit ecosystem that left us a golden lesson: what happens when the agentic tool forgets to read its own constitution before implementing. See you in the next installment!
📚 Spec-Driven Development (SDD) Series
- Spec-Driven Development (SDD): AI Agent Governance and the End of 'Vibe Coding'
- The Governance Chassis: Constitution vs. AGENTS.md (And how not to drown in sync debt)
- The SDD Pipeline in Practice: From EARS Syntax to Atomic Tasks
- The Requirements Interview and the 'SpecOps' Loop: How to Use AI Sparring and Rewrite Code Painlessly
- The Challenge of Existing Code (Brownfield) and Managing Multiple Specs with Jira/Git
- Google Antigravity and MCP: Sandboxing, Self-Correction and the Cloud