The BMAD method: building with AI agents without losing the thread

Ask an AI coding assistant to write a function and the result is often impressive. Ask it to build a full product over several weeks and it forgets yesterday's decisions, reinvents what already exists and gradually drifts from the original intent. The problem isn't code quality; it's continuity of context.

BMAD in one sentence

BMAD (Breakthrough Method for Agile AI-Driven Development) is an open-source, MIT-licensed method that organises work with AI agents like an agile team: specialised roles, written deliverables, and decisions that stay explicit from one step to the next. It installs into your project as files (agents, workflows, templates) and works with the main AI coding assistants. The stable version is v6; a v7 is in preview.

The principles

1. Specialised roles rather than one do-it-all assistant

Analyst, product manager, UX designer, architect, developer, tester: each agent has a scope, a stance and deliverables. You don't ask the architect to write code, or the developer to redefine the product.

2. Context lives in documents, not in the chat

Product brief, PRD (the requirements document), architecture, architecture decision records (ADRs), stories: each step produces a document versioned with the code. The next agent starts from those documents rather than from a conversation it never saw. Decisions don't have to be re-explained in every session.

3. Plan before you build

The method runs through four stages: analysis (idea, market, brief), planning (requirements, user experience), solutioning (architecture, breakdown into epics and stories), then implementation, story by story, with review and retrospective.

4. A process sized to the work

A minor fix doesn't need a PRD. BMAD adapts the depth of planning to the size of the work: a short path for small changes, full planning for a product.

5. Humans stay in charge

Agents propose, humans decide. Unvalidated assumptions are flagged as such, and the product owner's decisions are recorded.

The test: UWH-Tracker

To form my own view, I applied BMAD (v6.12, with Claude Code) to a demanding personal project: UWH-Tracker, an ankle sensor for underwater hockey. The device records depth and motion during training, then offloads the session over Bluetooth to an iPhone app in the locker room, since Bluetooth doesn't travel through water. The project combines embedded firmware (nRF52840 microcontroller, pressure sensor, flash memory), a Bluetooth protocol and an iOS app: good ground to see whether the method holds up to complexity.

Planning: one day, and solid documents

After one day of work with the analyst, product manager and architect agents, the project had:

• a PRD with around forty functional requirements, user journeys, success metrics and an index of 35 assumptions to validate;
• an architecture and a first formal decision record (ADR) on the Bluetooth protocol and the flash storage format;
• a breakdown into 5 epics and 50 stories, 9 of them deferred to V2, each with acceptance criteria and the list of requirements it covers.

The most useful part wasn't the volume, but the questions. The agents surfaced choices I would have made too late: the motion sensor's sampling rate (fixed at 52 Hz), the source of heart-rate data (Apple Health rather than a direct integration), the clock accuracy needed to align the data. Each decision is dated in the PRD.

Implementation: story by story, with an adversarial review

The first three stories (firmware skeleton and on-board test harness, flash memory driver, read, write and erase) followed the same cycle: a short spec that freezes the intent, the implementation, then a review by a separate agent tasked with finding flaws.

On the third story, that review produced eleven findings. Most were fixed (a test that could pass by mistake, poorly documented timeouts), two were refuted with evidence, and one was logged in a "deferred work" register rather than forgotten. Development also documented a genuine technical surprise: the chip's SPI controller silently ignores data that isn't in RAM, which required an intermediate copy.

What isn't proven yet

To be precise: these three stories are in review. They build and their host tests pass, but the tests on the real board are still to be run. The agents wrote this down plainly in their notes, without dressing it up. So the method has not yet been tested over the full life of the project.

What I took away

• The value is in the documents. An up-to-date PRD and architecture make every AI session productive from the first minute, and stay readable for a human joining the project.
• Traceability changes the relationship with AI. Every story maps to requirements and every deviation is recorded: you can audit what the agent did, and why.
• Review by a separate agent is the most underrated asset. It finds real defects, as long as a human arbitrates its findings.
• It isn't magic. The method produces a lot of text that must be read and validated. For a small script it's overkill; for a product it's a worthwhile investment.
• The human role shifts towards deciding, arbitrating and verifying, which is precisely where seniority matters.

And for your data projects?

Data projects suffer from the same ills as AI-assisted development: fuzzy intent, lost decisions, drift between what was planned and what gets delivered. BMAD's principles apply directly: formalise requirements and definitions before building, document architecture decisions, break work into verifiable deliverables, and have an independent reviewer check the result.