Spec-driven development vs agile, scrum, and vibe coding

BMAD is one instance of a broader idea: spec-driven development (SDD). To use BMAD well you have to understand the idea it implements, why that idea exists specifically because of AI coding agents, and how it relates to the software process you already know. This page is the concept and the comparison; the rest of the guide is the mechanics.

On this page

• What spec-driven development is
• The problem it solves, specifically for agents
• The four eras, and where BMAD sits
• SDD vs vibe coding
• BMAD vs agile and scrum
• BMAD vs other spec-driven tools
• Hands-on: the same feature, spec-first vs vibe
• Under Claude Code: plan mode as the spec gate

What spec-driven development is

In SDD, a well-crafted specification is the primary artifact, and code is generated from it. The spec is not documentation written after the fact; it is the contract that drives requirements, design, the implementation plan, the tests, and the docs downstream. You write down what should exist and why, get that reviewed, and only then have an agent produce the code. Every line of code traces back to a line of intent.

That inverts the habit of the last two decades, where code was the source of truth and documents (if they existed) trailed behind it. SDD works because of a blunt fact about LLM coding agents: an agent amplifies whatever you give it. Hand a strong model a vague sentence and it generates confident code for some interpretation of your words, compounding the ambiguity at machine speed. Hand it a reviewed spec and the same amplification runs in your favor. The spec is context engineering: the difference between the agent guessing your constraints and reading them.

The problem it solves, specifically for agents

SDD is not new (requirements engineering is a whole discipline), but AI agents revived it because they fail in a specific, expensive way without it. This is the exact wall BMAD's creator hit, and the failure modes are worth naming because they are what a spec prevents:

• Hallucination: the agent invents APIs, files, or behavior that were never specified.
• Contradiction: two parts of the work make incompatible decisions because nothing wrote the decision down.
• Death spirals: the agent thrashes on failing tests, "fixing" one thing by breaking another, because it has no fixed target.
• Drift and discard: it wanders from the intent and eventually throws away code that no longer fits a goal it never really had.

A machine-readable spec removes the ambiguity these feed on and makes every change traceable, which is what practitioners mean by eliminating "AI drift." The whole of BMAD is an apparatus for producing, reviewing, and preserving that spec at the right level of detail for each stage.

The four eras, and where BMAD sits

It helps to place SDD against the processes it is reacting to:

SDD is often mistaken for a return to waterfall, and the critique has a name in the 2026 commentary: "the Waterfall Strikes Back," the worry that heavy up-front Markdown buries agility. It is a fair caution and a real pitfall (see page 10), but it mistakes writing a spec first for writing the whole spec once. BMAD threads the needle three ways: it is scale-adaptive (a bugfix skips almost all of it), its phases are iterative and revisable (the PRD has an Update intent; bmad-correct-course reconciles mid-sprint), and it breaks work into small stories, not one big design. The counter-view in the same commentary is that agents actually supercharge agile, because the backlog can be built and rebuilt in real time. Both are true; the discipline is to spend spec effort where uncertainty and blast radius justify it, and nowhere else.

SDD vs vibe coding

"Vibe coding" was coined by Andrej Karpathy in February 2025 to describe letting an agent generate from a loose prompt and going with the flow. About a year later he described that era as ending, giving way to "agentic engineering": orchestrating agents against detailed specs with human oversight. SDD is the disciplined form of that shift, and BMAD's creator is blunt about the relationship: "I don't consider BMad vibe coding. I think of it as the antithesis of vibe coding." Vibe coding is genuinely fine for throwaway prototypes; it is a liability for anything you have to maintain, integrate, or trust. The dividing line is whether the code has a future.

BMAD vs agile and scrum

BMAD is explicitly agile-inspired, not opposed to agile. Its personas mirror a Scrum team, an Analyst, a Product Manager, an Architect, a developer, a QA or Test Architect, and it produces PRDs and sprint-style stories tracked in a status file. What it changes is who does the work between the ceremonies: an AI agent, which needs the intent written down far more precisely than a human teammate who can ask a question at standup. So BMAD keeps agile's cadence (short cycles, working software, feedback, retrospectives) and adds the artifact rigor that keeps agents consistent across those cycles. It is agile with the implicit knowledge made explicit, because the new team member cannot read the room.

BMAD vs other spec-driven tools

BMAD is the most architecturally ambitious of the 2026 SDD tools, which makes it the strongest fit for complex, multi-team, regulated work and heavier than necessary for small, fast work. The honest comparison, by where each tool puts the spec and research:

A rough decision heuristic from the comparison write-ups: brownfield-heavy and small, reach for something light like OpenSpec or BMAD's Quick Flow; scaling teams standardizing process, Spec Kit or BMAD full method; multi-team or regulated, BMAD. They are also interoperable at the document level: a research report or spec produced one way feeds another tool's pipeline, because they are all just Markdown.

One caveat applies to the entire category, BMAD included: none of these tools automatically keep the spec and the code in sync. Code drifts from its spec, and every tool needs a deliberate reconciliation step (BMAD's PRD Update intent and bmad-correct-course, Spec Kit's reconcile command, OpenSpec's sync). Treat spec-code divergence as a permanent maintenance task, not a solved problem; it is the single most common way SDD projects quietly rot.

Hands-on: the same feature, spec-first vs vibe

One task, two runs, on a repo that already has a limiter. Goal: rate-limit POST /login. The repo has app/ratelimit.py (a TokenBucket used by /search and /export) and an unprotected /login in app/routes/auth.py. Start both runs from the same clean tree:

git switch -c ratelimit-experiment

Run A, vibe. No plan, edits allowed, one loose prompt:

claude --permission-mode acceptEdits

Illustrative (run it in your own repo; not machine-verified here).

> add rate limiting to the login endpoint

I'll add rate limiting. Steps:
- pip install slowapi
- add Limiter middleware in app/main.py
- decorate login() with @limiter.limit("10/minute") in app/routes/auth.py
- add SLOWAPI_ENABLED to app/config.py

Edited 3 files. Done.

Three files touched, a second limiter library installed, and /login now guarded by slowapi while every other route uses the in-house TokenBucket. Two limiters, two configs, one drift you will debug later. Nothing pointed the agent at the code already in the repo.

Run B, spec-first. Same task, but gate it. Press Shift+Tab to reach plan mode (or launch claude --permission-mode plan), then ask. Claude reads first and proposes:

Plan: rate-limit POST /login

Findings
- app/ratelimit.py exports TokenBucket, used by /search and /export.
- /login in app/routes/auth.py has no limiter.

Approach
1. Reuse TokenBucket. No new dependency.
2. Guard login(): key = client_ip, 10 attempts / 60s, return 429 + Retry-After.
3. Add app/tests/test_login_ratelimit.py: 11th attempt in window -> 429.

Out of scope: no middleware, no config for other endpoints.

You disagree with one assumption and say so before approving:

Illustrative (run it in your own repo; not machine-verified here).

> key on f"{ip}:{username}", so one IP can't lock a user out. Then go.

[ExitPlanMode] approved
Edited app/routes/auth.py and added test_login_ratelimit.py. Test passes.

One file changed plus a test, the existing limiter reused, the keying decision made by you, not guessed.

The difference was not a better model. It was the ExitPlanMode approval: a five-second read that caught the wrong assumption (a fresh library, the wrong key) before a single edit landed. That checkpoint is the cheap one. The three-file cleanup in Run A is the expensive one. This is exactly the SDD trade this page argues, enforced at the tool layer.

Under Claude Code: plan mode as the spec gate

This page argues spec before code. Claude Code has a host primitive that makes the same move: plan mode. Press Shift+Tab to cycle the permission mode (manual to acceptEdits to plan to auto), or start in it with claude --permission-mode plan, which works headless in claude -p too. In plan mode Claude may read files and run search tools, but it may not edit source or run side-effecting Bash (no git push, no rm, no curl). It explores, proposes an approach, and exits only through the ExitPlanMode tool, which presents the plan for your approval before any implementation.

That approval is the spec gate. Nothing gets built until you agree the approach, which is SDD's move (agree the spec, then generate) enforced at the tool layer instead of in a document. Reject the plan and Claude refines and re-enters plan mode; the amplification stays pointed at a target you signed off on.

Two supporting pieces map cleanly. CLAUDE.md (project root or .claude/CLAUDE.md, loaded every session) is the always-on constitution, the way a BMAD project-context travels with the work; put standing constraints there so every plan starts from them. And the permission modes are a ceremony dial you turn to fit the blast radius:

Spec-heavy work sits at plan; a throwaway prototype can run at acceptEdits. It is the same discipline the four-eras table draws: spend the ceremony where blast radius earns it, and nowhere else.

With the concept in place, and BMAD located among its peers, the rest of this guide is mechanics. The next page gets you installed on your machine. 👉