I vibe-coded my way through three months of Claude Code projects before I admitted something was off. The code worked, mostly, but I kept losing hours to the same problem: Claude and I would drift from the original intent mid-session, and by session two or three, neither of us remembered why we'd made half the decisions in the codebase.

I'd been watching the BMAD Method since v3 introduced its orchestrator concept, but it felt like overhead I didn't need. Then v4 landed with a real architectural overhaul (NPM distribution, modular agents, multi-IDE support) and I gave it a real shot. It clicked almost immediately. I've spent years working on teams with PMs, architects, scrum masters, QA. The full SDLC cast. BMAD maps those same roles onto AI agents, so the workflow felt familiar instead of foreign. I wasn't learning a new process. I was running the one I already knew, just with different team members. That was roughly nine months ago. I don't build without it now.

BMAD in 60 Seconds

BMAD (Breakthrough Method for Agile AI-Driven Development) is an open-source framework that structures AI-assisted coding around specifications, role-based agents, and phased workflows. The spec is the source of truth. Code is the output.

As of v6, the project has 19+ specialized agents (PM, Architect, Scrum Master, Developer, QA, and others), 50+ named workflows, and a module system that hooks into Claude Code natively through skills, commands, and hooks. It's crossed 40,000 GitHub stars and the ecosystem has spawned several third-party Claude Code plugins.

Numbers aside, does it actually change how you work? For me, yes. Substantially.

How I Set It Up

I use BMAD across several active projects. Bridgely, CoinFolio, FiveCrowns, and Vela are all built this way. Different domains, same workflow.

On CLAUDE.md

A lot of BMAD guides will tell you to set up a CLAUDE.md file alongside it. I actually don't bother. BMAD's own agent configurations, skills, and workflow definitions carry enough context on their own. Adding a CLAUDE.md on top of that is redundant at best, and at worst you end up with conflicting instructions. Your CLAUDE.md says one thing, BMAD's agent config says another, and Claude Code picks whichever it sees last.

I keep project-level conventions (file naming, directory structure, don't-commit-secrets type rules) in BMAD's own config. One source of truth, not two.

The Actual Workflow

A feature goes through four phases. I'll walk through what this looks like on a real task, building a Dev.to publishing skill for my blog pipeline.

Spec first. I describe what I want. BMAD's PM agent writes a PRD. The Architect agent reviews it and produces a technical design. Both end up as markdown files in docs/specs/ that persist across sessions.

> "I need a skill that publishes blog posts to Dev.to via their API,
>  handles draft mode, and manages frontmatter validation."

The PM agent gives me user stories, acceptance criteria, and scope boundaries. The Architect maps that to file structure, dependencies, and integration points. No code yet. Just the blueprint.

Story breakdown. The Scrum Master agent splits the spec into implementable stories, each with clear done-criteria, each in its own file under docs/stories/. This is the part that replaced my old habit of writing one giant implementation prompt. Smaller chunks mean each piece is actually testable.

Implementation. Claude Code writes code against the spec and story files, not against a vague prompt I typed twenty minutes ago. The Dev agent pulls in the story file, the architecture doc, and project conventions from BMAD's config. Decisions trace back to a spec instead of disappearing into chat history.

Validation. The QA agent checks work against acceptance criteria, runs tests, and flags gaps. Vibe-coding skips this step entirely, which is exactly why vibe-coded projects accumulate the kind of debt they do.

What's Different Now

The context-drift problem I mentioned at the top? Gone. Spec files give Claude Code something persistent to anchor to, so I'm not re-explaining decisions from last Tuesday. Features that used to take two or three sessions now finish in one because the spec does the remembering.

The other shift was subtler. I used to treat "it runs" as done. Now done means the QA agent signed off against acceptance criteria. It sounds like a small distinction but it changes how much rework I do later. A lot less.

Refactoring got easier too. When you need to restructure something, having the original intent documented next to the implementation means you can tell Claude Code what the code was supposed to do, not just what it currently does.

I won't overstate it. The biggest improvement isn't raw speed. It's that I can predict what I'm going to get at the end of a session, because I defined it before I started.

Where It Falls Short

Context window pressure is real. On bigger projects, BMAD specs plus architecture docs plus story files eat context fast. I've gotten better at keeping specs concise, but there's a tension between "enough detail to be useful" and "not so much that Claude Code forgets the beginning by the time it reads the end."

Agent handoffs can be rough. The Architect agent sometimes makes assumptions that don't line up with what the PM agent specified. I've started adding explicit handoff checklists in my story files to catch this, but it's a manual workaround for what should probably be a tighter integration.

And for small stuff (a typo fix, a CSS tweak, a one-line config change) the full BMAD workflow is overkill. I skip it for anything that touches fewer than three files or doesn't involve a real design decision.

Trying It Out

The GitHub repo has install instructions. My advice: start with BMM Core (the base module) and don't install everything at once. Pick a real feature on a real project and spec it before you write any code.

The thing that took me longest to internalize is that the process matters more than the prompts. I spent months tweaking how I asked Claude Code to do things. BMAD shifted that energy toward defining what I wanted Claude Code to build, and the prompts mostly took care of themselves.

Spec-Driven Dev Is Bigger Than BMAD

BMAD isn't the only framework pushing this direction. Kiro, GSD, and RALPH-LOOP are all built on variations of the same thesis: AI-generated code is only as good as the structure you feed it.

BMAD works for me because it maps directly onto Claude Code's extension model. Skills, hooks, commands. It's not a wrapper around Claude Code. It's a playbook for the tools Claude Code already has.