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:
- No structured intent. You describe what you want in the moment, and the AI has no memory of your architecture, constraints, or non-functional requirements, so each session reinvents rather than extends.
- Context drift. Every new chat is a blank slate. You re-explain the project repeatedly and get different answers each time, until the code diverges from your original decisions.
- Token hell. Loading everything into context at once distracts the model (sometimes less is more), invites hallucination, and drives up the bill.

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?
- Spec-First. Write a spec for initial clarity, generate code, then discard it, the documentation rots over time.
- Spec-Anchored. Spec and code are version-controlled and evolve together; agents use the spec as a persistent reference.
- Spec-As-Source. Humans edit only the spec; code is fully generated, with the AI acting as a compiler. This is where the market seems to be heading.

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:
- Review burden. Code is concise; natural language isn't. You may end up reviewing tens of Markdown files.
- Non-determinism. These are still black boxes. Even a perfect spec is no guarantee, like a trained dog that bolts the moment it spots a butterfly.
- Semantic diffusion. A long, detailed prompt isn't automatically a spec; SDD demands real discipline and a change of mindset.
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:
- Mary — Business Analyst; John — Product Manager; Winston — Architect
- Amelia — Senior Engineer; Sally — UX Designer; Paige — Technical Writer
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:
- Quick Flow — bug fixes, single features, POCs, minimal docs.
- BMad Method — the classic full-lifecycle flow for complete products.
- Enterprise — full products with dedicated security, compliance, and DevOps agents.
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
- Mindset over tooling. The spec-first habit is the real shift; tools like Kiro, Spec-Kit, and BMad amplify it, they don't replace it.
- Spec before code, always. Treat the spec as a living artifact, not a throwaway prompt, and start each phase with a clean context, the spec is your continuity, not the chat history.
- Trash in, trash out. A bad spec means bad code, but at least you can find the fault, fix it, and regenerate.
- You still own the output. An LLM is a hybrid of the forgetful wizard and the butterfly-chasing dog; at the end of the day, the generated code is our responsibility.

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











