Give AI a Contract, not a Conversation: Spec-Driven Development with BMad

Vibe coding is fun, brilliant code at 2 AM, tests passing, everything shipping fast, until three months later the codebase is an unmaintainable mess nobody can explain. Spec-Driven Development (SDD) is the answer: a shift from improvised conversations with AI to structured, version-controlled specifications that both humans and AI treat as the single source of truth. Our levi niner Alin Costea showed why AI code breaks down at scale, what SDD is, and how the BMad Method turns a squad of AI agents into a full software team. And his live demo of by building a fractal-rendering CLI from a single sentence was a perfect example. 

The Vibe Coding Trap

Vibe coding means letting AI generate code with no coherent strategy. It looks great and the tests pass, but you end up with a Frankenstein codebase: brilliant pieces stitched together with no consistent architecture and mounting technical debt. The problem isn’t the AI itself, it’s the process. Rather than treating a capable model as an all-knowing wizard, it pays to guide it, stay concise, and remove ambiguity. 

 

Why AI Coding Breaks Down at Scale

A useful mental model: treat the LLM not as an omniscient wizard but as a brilliant, octogenarian programmer, deeply experienced, yet prone to forgetting and to inventing stories. Three compounding problems make things worse as a project grows: 

The Answer: Spec-Driven Development

Hire ten teams to build your dream house from a vague brief and you’ll get nine different houses and a boat. Give them the same blueprints and they’ll build the same house ten times. AI works the same way: those blueprints are specifications, natural-language documents that describe what the software should do and how it should behave. Because the input is the same every session, SDD delivers consistency and predictability across sessions, agents, and teams, as far as the non-deterministic nature of LLMs allows. 

The Three Flavours of SDD

How far you take the idea defines three recognised flavours. The key question: does the spec evolve alongside the project, or not? 

Why Markdown Specs Work (Until They Don't)

Natural language is the format LLMs actually understand, and Markdown is its practical vehicle: human-readable, versionable, reviewable, and diffable, so it slots into existing engineering workflows. If something is wrong, you can find and fix it in the text rather than in opaque generated code. (This isn’t new, Model-Driven Development tried it in the 2000s and failed on rigid, formal DSLs; LLMs may finally supply the missing ingredient.) But it isn’t all rainbows: 

The Tool Landscape

Several tools implement these ideas; three represent the spectrum well. What they share: all of them use plain Markdown, the AI reads it, writes it, and is judged against the rules written in it. 

BMad in Action: An Agile Team of AI Agents

BMad (‘Build More, Architect Dreams’) is spec-anchored by design and simulates a complete software team. Its workflow is not only systematic but adversarial. A code review isn’t one agent but several competing personalities that argue it out. The core team is a cast of named specialists, each backed by an editable personality file: 

More agents arrive via modules (Test Architect, Agent Builder, Game Developer, and more). Every agent uses the specs as its source of truth and as the way team members communicate. 

Inside BMad: Flows and Phases

One size doesn’t fit all, so BMad offers three flows, and works with both greenfield and brownfield projects: 

Depending on the flow, a project moves through up to four phases, Analysis, Planning, Solutioning, and Implementation, and after each one, documents are persisted, so re-entering a session picks up exactly where the team left off. If you’re unsure which flow to pick, the built-in bmad-help skill recommends one. 

The Demo: From One Sentence to a Working Tool

Alin started from a single line of intent: a CLI that renders a random or selected fractal in text mode, from the ten best-known fractals, using colored ASCII. BMad recognized it as a small project, then, on the spec route, began writing specifications and surfacing its own open questions (language, terminal size, catalogue, animation) before generating a full PRD and an architecture ‘spine’ with Mermaid diagrams. 

 

The adversarial review:  To review the code, BMad launched what Alin nicknamed the ‘three agents of the apocalypse’, a Blind Hunter, an Edge-Case Hunter, and an Acceptance Auditor, running in parallel, each filing its own triage before patches were applied and every document kept in sync. 

 

One honest caveat: this predictability isn’t free. Because BMad leans on many files, it’s token-hungry, roughly two hours of generating documents and code cost about $14, memorably framed as ‘the price of a pizza.’ 

Lessons to Carry Forward

References 

•  docs.bmad-method.org 
•  github.com/bmad-code-org/bmad-method 
•  bmadcode.com
 

In this article:
Published:
14 October 2026

Related posts

June 26th

The Cost of Choice

Most companies spend up to 40% to much on cloud, are you? Cut spend, not options. Smart standardizations win.

Cloud cost overruns and growing technical debt rarely stem from tooling alone—they are symptoms of architectural and operational choices. This session looks at how senior technical leaders can regain control by connecting cloud spend directly to business value. We’ll explore unit‑economics thinking, ownership models, and lifecycle management practices that reduce waste while preserving delivery speed. You’ll learn how to combine FinOps principles with technical‑debt controls to create a cloud environment that is financially sustainable and technically healthy.

May 28th

AI AGENTS DESERVE AI PLATFORM

Portable patterns for Azure, AWS and GCP that survive the next upgrade

AI agents are moving rapidly from experimentation into real production use cases, but architectures vary widely across cloud platforms. In this webinar, we compare practical patterns for building and running AI agents on Azure, AWS, and Google Cloud Platform. We’ll focus on what to standardize, where to embrace cloud‑native capabilities, and how to design for security, observability, and future change. The goal is not to pick a winner, but to help leaders understand how to scale agent‑based solutions without locking themselves into fragile designs.

April 23rd

Winning on Repeat: Product Engineering in the Age of AI

Cadence, quality and outcomes over output

Delivering a successful solution once is no longer enough. In the age of AI, organizations need product engineering models that enable them to win consistently across teams, releases, and markets. This session explores how leading organizations evolve from project‑centric delivery to product‑centric execution, supported by AI‑augmented engineering practices. We’ll look at cadence, quality, and accountability, and how leadership decisions shape sustainable delivery performance over time.

April 2nd

GOVERNING AI IN PRODUCTION

Designing cloud and data platforms that survive real-world pressure

Many organizations succeed in building AI proofs of concept, far fewer succeed in scaling them safely into production. This webinar focuses on what it takes to move from experimentation to reliable, governed AI platforms. We’ll discuss platform architecture choices, model governance, security, and policy patterns that enable teams to deploy AI at scale without slowing down delivery. Designed for senior technical leaders, this session provides practical guidance on turning AI initiatives into durable capabilities that deliver value beyond the first demo

March 5th

Navigating Digital Sovereignty and Strategic Cloud Choices

How Organizations Can Balance Innovation, Compliance, and Control in a Multi-Cloud World

In today’s rapidly evolving digital landscape, organisations face increasing pressure to ensure business continuity, maintain public trust, and comply with complex regulations like NIS2, DORA, and GDPR. This webinar explores the critical concepts of digital and operational sovereignty, the strategic importance of hybrid and sovereign cloud models, and the risks of vendor lock-in.