Pitfalls, best practices, and recommendations

The closing page: the mistakes that make BMAD feel like overhead, the practices that make it pay, when to reach for it and when to skip it, and a day-one setup you can copy. Everything here is framework-wide; the research-specific anti-pattern catalog lives in the recon guide.

On this page

• The meta-pitfall: ceremony for its own sake
• Framework-wide pitfalls
• Best practices
• When NOT to use BMAD
• Recommendations by team shape
• A day-one setup
• The one-line summary
• Hands-on: reproduce and fix two traps
• Under Claude Code: host-specific pitfalls

The meta-pitfall: ceremony for its own sake

Every other pitfall is a special case of one: producing documents instead of changing decisions. BMAD's value is not the artifacts, it is the wrong turns caught while they are still paragraphs. A two-page PRD that prevents a bad schema beats fifty polished pages nobody reads. If you cannot point to a decision a document changed or a mistake it prevented, that document was ceremony. Measure outcomes (see the scorecard on the memory page), not page count.

Framework-wide pitfalls

Best practices

The short list that prevents most of the above:

1. Frame before you build. A question with a kill criterion (what forge-idea produces) is worth ten open-ended prompts. A PRD claim with an evidence label is worth ten confident guesses.
2. A fresh chat per workflow. Non-negotiable. It is a quality feature, not an inconvenience, because the state that matters is on disk.
3. Pick the track by risk, not prestige. Quick Flow for small and understood; full method for multi-epic; add TEA and gates for regulated or high-stakes. Running the enterprise track on a bugfix is as wrong as vibe-coding a payments system.
4. Solutioning before multi-agent implementation. If several epics could be built by different agents or people, write the architecture first. Catching an alignment issue there is roughly 10x cheaper than in implementation.
5. Commit the shared brain. The _bmad-output/ spec chain and the team *.toml overrides go in git; personal *.user.toml stays local. A teammate who clones without them gets a different BMAD.
6. Keep project-context.md living. Every time an agent repeats a mistake it should have known better than to make, the fix is usually a line here.
7. Run the readiness gate. bmad-check-implementation-readiness is the last cheap checkpoint before code. Do not start Phase 4 on a FAIL.
8. Reconcile upstream, not downstream. When documents disagree, fix the owning document and let the change propagate; do not hand-patch every downstream file.
9. Verify load-bearing claims adversarially. For anything a spec will rely on, have a skeptic try to refute it. This is where real research errors die.
10. Measure, then loosen the gates. Track decisions changed and mistakes prevented; move from per-story-spec-approval toward none only as the evidence earns your trust. Human on the loop is earned, not assumed.

When NOT to use BMAD

The method is honest about its own boundaries:

• The prototype is the answer. When a 30-line experiment settles the question faster than a document chain, run the experiment.
• The change is small. A bugfix or one-file feature is Quick Flow, or no method at all.
• The decision is already made. Skip the analysis theater; de-risk execution instead.
• The work is throwaway. A demo you will delete tomorrow does not need a spec chain. (This is the one place plain "vibe coding" is genuinely fine.)

Recommendations by team shape

BMAD is not the only spec-driven tool, and the honest fit depends on scale. The 2026 consensus across comparison write-ups:

BMAD is the most architecturally ambitious of the SDD tools, which is its strength for complex, multi-team, long-lived work and its cost for small, fast work. Use the track system to place yourself: it is the same tool dialed up or down, not a different tool.

A day-one setup

A sensible starting configuration for a team adopting BMAD on a real project:

# 1. Install core + method + builder + creative suite, pinned for reproducibility
npx bmad-method install --yes \
  --modules bmm,bmb,cis \
  --tools claude-code

# 2. Commit the shared brain, ignore personal + regenerable machinery
cat >> .gitignore <<'EOF'
_bmad/**/*.user.toml
_bmad/core/
_bmad/bmm/
EOF
git add _bmad/_config/manifest.yaml _bmad/custom/ _bmad-output/ .gitignore

Then, before real work:

1. Generate project-context.md (bmad-generate-project-context) and commit it.
2. Write one team override that encodes your non-negotiables (test-first, your MCP docs tool, your naming conventions) in the dev agent's persistent_facts.
3. Restate the two or three load-bearing rules in CLAUDE.md / AGENTS.md.
4. Decide your gates.mode (start at per-story-spec-approval) and write it down.

The one-line summary

Hands-on: reproduce and fix two traps

Two traps above are worth provoking on purpose so the fix sticks. Do both in a scratch repo.

Trap 1: context bloat

Reproduce it. In one long-lived chat, run several workflows back to back without clearing:

> run bmad-prd for the checkout epic
> run bmad-create-epics-and-stories
> run bmad-quick-dev on the coupon bug

Now inspect the window. /context prints it by category:

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

> /context
Context usage: 186k / 200k tokens (93%)
  System prompt + tools    18.4k
  MCP tools                 9.1k
  Memory (CLAUDE.md)        2.1k
  Messages (transcript)   156.4k
  Free space               14k   (auto-compact fires near 95%)

At 93% you are one workflow from auto-compaction quietly dropping early detail. Fix it in two moves. /compact summarizes the transcript in place; give it a focus so it keeps what matters within the current workflow:

> /compact focus on the current story

At a workflow boundary do not summarize, start clean (state lives in files, not scrollback):

> /clear

Re-check and watch it drop:

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

> /context
Context usage: 31k / 200k tokens (15%)
  Messages (transcript)     1.4k

/compact when you want continuity inside one workflow; /clear at every workflow boundary.

Trap 2: permission fatigue

Reproduce it. A single bmad-quick-dev loop makes you approve npm test and git status on every iteration. By the fifth prompt you are rubber-stamping, which is the real hazard: the approval you stop reading is the one that mattered.

Fix it. Pre-authorize the safe, high-frequency calls in .claude/settings.json (project-scoped, so commit it and the team inherits it):

{
  "permissions": {
    "allow": [
      "Bash(npm test *)",
      "Bash(git status)"
    ],
    "defaultMode": "acceptEdits"
  }
}

Each allow rule stops the prompt for exactly those calls; defaultMode: acceptEdits auto-accepts file edits while still gating new commands. You can add the same rules interactively with /permissions. Now the whitelisted calls run prompt-free, and the prompts that remain are the ones worth reading.

Do not reach for bypassPermissions to silence the noise. It disables every check and belongs only on a throwaway sandbox you can delete, never on a real repo.

Under Claude Code: host-specific pitfalls

Every trap above has a host-specific twin. Running BMAD on Claude Code adds its own failure modes, all avoidable once you know the mechanic behind each one.

• Permission fatigue. Clicking approve on every tool call trains you to stop reading them. Set a defaultMode (for example acceptEdits) and write precise allow rules like Bash(npm test *) and Read(src/**) instead of rubber-stamping. Reserve bypassPermissions for throwaway sandboxes; never point it at a real repo.
• Context bloat. Never running /compact or /clear lets the window fill until auto-compaction fires near 95% and silently drops early detail. Watch /context, and /clear between workflows (the one-fresh-chat-per-workflow rule is yours to enforce here).
• Cache-defeating prefixes. A timestamp or per-run id near the front of the context breaks the automatic prefix cache and reprices the whole session (see page 12).
• MCP overload. Connecting many servers so their tool schemas crowd context. Prune servers; rely on deferred schemas and ToolSearch (see page 13).
• Skipping plan mode. Starting a risky change in acceptEdits means edits land before you have seen the approach. Enter plan mode (Shift+Tab) for anything you would want to review first.
• Over-trusting /rewind. It restores Claude's own file edits, not committed history, Bash side effects, or background-subagent edits; those live in git. It is a 100-checkpoint, session-scoped buffer, not version control.
• Parsing the transcript. Scripts that read ~/.claude/projects/.../*.jsonl break on the next release; the format is internal. Use --output-format json or /export.

None of these are BMAD's fault; they are the cost of a powerful host used carelessly. The discipline is the one BMAD asks for everywhere: know where state lives, and spend attention where it changes a decision.

BMAD works when you treat it as bounded context, explicit procedure, externalized state, typed artifact handoffs, source and tool boundaries, human decision gates, and inspectable customization, applied at the scale the work justifies. It stops working the moment it becomes a folder of documents nobody reads. Keep it as the spine, let specialized tools (and the Deep Recon research skill) do what they are good at, make every handoff a file with an owner and a consumer, and spend human attention where it counts most: framing the work and judging the result. That is how "research before code" becomes an operating system for decisions rather than another layer of ceremony. 🎓