Everybody vibe codes now. In case the term passed you by the way it almost passed me by: you describe what you want, the model writes it, you paste the error back, and you repeat until it runs. The vibe is the spec. For a prototype or a weekend script this is genuinely great. For anything that has to survive contact with a real codebase, it falls apart in a way that is hard to notice until it is expensive.
I hit that wall enough times that I went looking for structure, and I ended up on the BMAD Method. This post is the explainer I wish someone had handed me: what it actually is, why it works, and when it is overkill.
The problem is not the model
Vibe coding fails in a predictable way. The first prompt produces something impressive. The tenth prompt contradicts the third. By the thirtieth, the model has forgotten decisions it made, invented new ones, and your architecture is whatever the last conversation happened to imply. There is no plan outside the chat, so there is nothing to check the work against.
Notice that none of this is a model capability problem. A smarter model drifts more politely, but it still drifts, because the missing piece is not intelligence. It is shared, persistent structure: a spec, an architecture, and a unit of work small enough to hold in context at once.
Which is, not coincidentally, what software teams figured out decades ago.
What BMAD actually is
BMAD (Breakthrough Method for Agile AI Driven Development) is a free, MIT licensed framework that puts a team of specialized agent personas between you and the code. It is one of the most starred agentic development projects on GitHub, and the core idea is almost boringly simple: instead of one generalist AI you prompt for output, you get a workflow of roles, each with a defined job and a written deliverable.
The cast will be familiar to anyone who has worked on a real team. There is an Analyst who helps you figure out what you are even building. A Product Manager who turns that into a PRD. An Architect who fights the PRD and produces a technical design. A UX specialist, a Scrum Master, a Developer, and a QA role that tries to break what the Developer built.
The point is not roleplay. The point is that each handoff produces a document, and the documents are the memory that a chat window cannot be.
The BMAD agent roster inside a coding CLI: analyst, product manager, architect, UX designer, scrum master, developer and QA, each listed with the single job it owns. Screenshot from the install running on my machine.
The two phases
Phase one is planning. You work with the Analyst, PM, and Architect agents to produce a PRD and an architecture document. This is human in the loop the whole way. The agents ask uncomfortable questions, you make actual decisions, and the decisions get written down. This phase is where most of the value is, because it forces the thinking that vibe coding lets you skip.
Phase two is development, and it has one genuinely clever trick. The Scrum Master agent takes the PRD and architecture and shards them into story files. Each story is a small, self contained file with everything the Developer agent needs: acceptance criteria, the relevant schema snippets, the API definitions, the design notes. The Dev agent then implements one story at a time.
Why this matters: the Dev agent loads a few KB of exactly relevant context instead of your entire project documentation. Context is the scarcest resource in AI assisted development, and sharding is context engineering disguised as agile process. The agent always knows what to build, how to build it, and why, because the story file tells it.
Then QA reviews, findings get fixed, and you move to the next story. It is a loop a real engineering org would recognize, which is the entire point.
The little brain part: which skill when
Here is the part the install page does not spell out. BMAD drops a full menu of agents and workflows into your editor, and the first instinct is to close the menu and go back to prompting. Resist. You only ever need one entry at a time, and the whole method reduces to picking the right one for the moment you are in.
- If you cannot yet say what you are building, you start with brainstorming or a product brief, and you let the Analyst interrogate the idea until it survives or dies cheaply.
- If you know what you are building but not where it ends, you write the PRD, because scope you cannot read is scope you cannot check.
- If the requirements exist, you produce the architecture, which is where the Architect picks fights with the PRD before the code has to.
- If the thing has a user facing surface, UX planning happens now, not after the Developer agent invents a layout at two in the morning.
- Once the documents exist, you shard them into stories and hand them to the Developer one at a time, then let QA try to break each result.
That is the complete trick. The menu is long, but the moments are few, and matching one to the other is the entire little brain requirement.
The BMAD brainstorming composer open in a browser tab: the full technique catalog laid out as a dashboard, with a copy prompt button that hands the composed session back to the chat. This is what the install drops into your project.
Trying it takes one command
npx bmad-method install
Run it inside a project and it wires the agents into your editor of choice (Claude Code, Cursor, and friends). From there you can start at the very beginning with brainstorming and a product brief, or drop straight into a PRD if you already know what you are building. It handles brownfield projects too: there is a workflow that documents an existing codebase first, so the agents plan against what you actually have instead of what you wish you had.
The composer closing the loop: the composed session prompt is copied, and the banner tells you to paste it into the chat, which is where the agent takes over and the session begins
The honest tradeoffs
This is a real workflow, which means real costs. Planning takes time you could have spent typing prompts. For a throwaway script or a quick spike, the full method is absolutely overkill, and the framework itself will tell you to use its lighter flows for small work.
You also do not get to stop thinking. The agents produce artifacts, but you own the decisions, and a PRD you rubber stamped is just vibe coding with extra steps. The structure only pays off if you actually engage with it.
What you get back is consistency. The code in story fourteen still respects the decisions made in the architecture doc, because the Dev agent never had a chance to forget them.
Full disclosure, in the interest of practicing what I post: this article itself went through BMAD style editorial and adversarial review passes before it reached you. The robots reviewing the article about the robot workflow were at least transparent about it.
The bigger idea
The thing I keep coming back to is that BMAD is not really about the agents. It is about admitting that AI changed how fast we can write code, but not what makes code correct. Specs, reviews, small verifiable units of work: the old discipline turns out to be exactly what the new tools were missing.
If you have tried structured agent workflows, I am curious where they broke down for you. And if you are still full vibe coding, I am equally curious how far it has taken you. Both answers are interesting.
Sources and further reading:
- BMAD-METHOD on GitHub (bmad-code-org): the framework itself, MIT licensed, install docs and user guide.
- Stop Vibe Coding: Spec Driven Development with The BMad Method (Tech Lead Journal, episode 255): interview with creator Brian Madison on why spec driven development beats prompt roulette.
Top comments (1)
Still full vibe coding on the personal projects, and I keep failing to find a reason to stop. I delivered more in the last six months than in the several years before it, mostly because I am out of the code entirely now and spend that time on what the thing should actually do.
Your line is size - prototype, weekend script. Mine is whether a bad result costs me anything. My home automation is well past a weekend script and I have never read a line of it.