Spec-Driven Development with BMAD

1The AI invents whatever the context leaves out

First family: framing the code, starting before the first line. The AI knows only what you tell it about the project. That is called the context. Whatever the context leaves out, the AI invents. So the book proposes fixing the context in advance: that is context engineering. In its words: "The purpose of context engineering is to create boundaries of truth that the AI cannot cross" (lesson 5). In other words, facts set in advance that the AI must not contradict. Here is a bare instruction, then the same one with its context:

✗ BEFORE: Build a to-do list application.

✓ AFTER (the book's example, abridged):
Who  : overworked freelance designers
Why  : track billable hours per task
What : a Kanban (a board of cards in columns) with a timer, no social features

In that block, the last line is the most useful. It also says what you will not build: no social features. The book gives it a whole section, "Explicit exclusions". Without it, the project can keep growing features nobody asked for. That is scope creep. The book says that fixing in advance what is out of scope prevents it.

2Tests come before the code, not after

The context says what to build. You still have to check that the agent built it. An agent may code first, then write its tests afterwards. Its tests then check what it did, not what you asked for.

So BMAD flips the order with its test module, TEA (Test Architect, which the book spells three ways). Its method is called ATDD: acceptance test-driven development. It starts from acceptance criteria. An acceptance criterion (AC) is a condition the feature must meet to be declared done. Each criterion carries an identifier, such as AC1, and you write one test for each before the code.

The method follows three beats, with traffic-light colors. Red: the test fails, because the feature does not exist yet. Green: the agent codes until the test passes. Refactor: you clean up the code without changing what it does.

So this loop restarts for each acceptance criterion. The tests are first put to sleep with test.skip: they exist, but do not run. Here is my minimal version, not a copy of the book:

test.skip('AC1: the card shows the task title', async () => {
  // test body to write
});

To go red, you remove the skip: the test fails. The agent then codes until green. In the book's demo, the tests for the card and the task window exist before a single line of interface. The reason, according to the author: "If tests are created after implementation, we are not necessarily covering all scenarios" (lesson 26).

These identifiers also act as a thread from one document to the next: they tie together the story, its test and its review (idea 4). A story is a unit of work, small enough to fit in one session. It is described in a Markdown file, which is lightly formatted text.

3Before any code, check that the documents agree

Tests check the code. Before the code, BMAD checks the documents too. At this stage there is no code yet, only three texts: the PRD (what to do), the architecture (how to build it) and the epics, meaning big batches of features split into stories. These texts can contradict each other or leave something out.

Picture three plans for the same house: the architect's, the electrician's, and the list of rooms. Before building, you make sure they describe the same house. The implementation readiness check does that job. An agent reads the three documents and cross-checks them.

This check works as a gate before implementation. It returns one of three verdicts:

• PASS: everything is consistent, move on;
• CONCERNS: there are gaps, but they do not block;
• FAIL: fix before going further.

On the demo, the check found three problems in the documents, before a single line of code (lesson 28):

• entities missing from the data model: objects the application handles, but that no document describes;
• a missing date filter;
• an AppProvider that would have crashed the application if built as it stood. It is the root component, the one that hands shared data to every screen.

A FAIL is therefore no drama. The book says so: "Rather than treating this as a setback, treat it as the system doing its job" (lesson 15). The agent proposes the fix, then the human approves it.

4After every story, a review that tries to break the code

The check in idea 3 happens before the code. The review happens after, at the end of every story. The book puts it this way: "The review layer is not a formality. It is a deliberate adversarial check designed to catch what the implementation session misses" (lesson 18). An adversarial check tries to break the work rather than confirm it.

Yet the book describes this review in two ways, without choosing between them:

• Lesson 18, three passes in a row. The Blind Hunter looks for logic errors and silent failures, the ones that show no message. The Edge Case Hunter looks for edge cases, such as an empty list, and for concurrent access. The Acceptance Auditor checks each criterion identifier. Before the review, a menu asks which changes to review: uncommitted, staged, a branch diff or a range of commits.
• Lesson 31, three agents in parallel. The workflow launches them at once, on edge cases, acceptance criteria and the before-and-after diff. No Blind Hunter is named there.

Either way, the developer fixes, then the review runs again.

The book adds one piece of advice: "ideally using a different model to independently evaluate the work" (lesson 30). The reason, in my view: two sessions of the same model share the same blind spots.

5Every workflow starts in a fresh session

Second family: giving the project a memory from one session to the next. It starts from a rule in the book: a new session for each workflow, no exceptions. You should "never chain" the PRD and then the architecture in the same session (lesson 43).

The reason: accumulated context biases what follows. During the PRD, the conversation fills up with discussions about the product. If you chain the architecture right after, the agent still has them in mind and draws on them. A fresh session is a whiteboard wiped clean before the next meeting.

That context also has a limited size, counted in tokens. A token is a word fragment, the unit the model counts and bills. Switching sessions costs little: "The cost of starting fresh is seconds" (lesson 45).

Starting from scratch raises a question, though: how do you keep the work in progress? Each workflow keeps track of its own progress in a file (lesson 21). The book shows it twice:

• the test setup writes its progress to the framework-setup-progress file (lesson 22);
• the PRD is built in eleven steps, and its progress is written to a file too.

If the context fills up, you open a fresh session and relaunch the workflow, pointing it to that file. It picks up where it left off (lesson 27).

6project-context.md: rules that grow with every retrospective

A fresh session starts from scratch, but the project itself has to remember. BMAD keeps that memory in the project-context.md file, "a constitution for the project" (lesson 15). It plays the role of a CLAUDE.md, the instructions file Claude Code rereads every session. It is loaded only in BMAD workflows: 18 workflows and files refer to it (lesson 23).

The project-context.md first lists the tech stack, meaning the project's languages and tools, with their versions. It then lists conventions: TypeScript configuration, state management, data model, testing best practices.

This constitution gets amended at the end of every epic, and that is the best idea in the book. Three steps follow one another:

1. A coverage gate checks that the epic is tested enough. Coverage is the share of the code the tests check. The gate returns PASS, CONCERNS, FAIL or WAIVED, a waiver approved by the business. So an under-tested epic does not get closed (lesson 19).
2. The retrospective, the epic's review meeting, rereads the completion notes written at the end of each story.
3. The file's generation is run again, and it takes that review into account.

A concrete case, not from the book: a test wasted time because the database was not emptied between two tests. The retrospective turns that into a rule, "empty the database before each test". The next epic starts with it.

The book sums up this loop in one sentence: "the project-context.md becomes the living record of how the project has learned to build itself" (lesson 19).

7A small change goes through a lighter workflow

This whole ritual would be heavy for fixing a button. So for small changes, BMAD provides the quick-dev workflow. It condenses intent, plan, implementation and review into one session.

This shortcut has a trap. BMAD first estimates the change's "blast radius": the paths by which it could break something else. When there is "zero blast radius", quick-dev may implement without writing a specification. The book says to demand one anyway, for traceability: being able to find out later why the code changed (lesson 24).

Even in its lighter form, the workflow leaves the last word to the human. When quick-dev offers to cap the display at three tags, the book suggests declining (lesson 26).