ZICHEN.DEV

BMAD + Claude Code Setup Guide (IDE & Web Chat)

Audience: Developers and engineering teams (backend/frontend).
Goal: Install the BMAD Method into an existing repo and wire its agents to both Claude Code (IDE) and web chat(Claude/ChatGPT), then run a full PM → SM → Dev → QA cycle.

TL;DR

  • Install BMAD in your repo: npx bmad-method install
  • IDE (Claude Code) uses slash commands (/pm, /sm, /dev, /qa). Create four command files that wrap the core agents under .bmad-core/agents/.
  • Web chat uses the bundled files under bmad/web-bundles/ and the *agent ... syntax.
  • Put working docs in docs/ (docs/prd.md, docs/architecture.md, docs/stories/).

1) What is BMAD?

BMAD (Brownfield Method for AI Development) is a lightweight set of prompts, checklists, and workflows that let you drive work through role agents (PM, SM, Dev, QA) with predictable outputs and file locations.

BMAD ships with two flavors:

  • Core (IDE‑first): .bmad-core/ → modular agents and utilities meant to be used from your IDE with Claude Code.
  • Web bundles: bmad/web-bundles/ → flattened, self-contained agent/team files designed to be pasted into a web chat.

Rule of thumb: IDE → use .bmad-core/agents. Web chat → use bmad/web-bundles.

2) Prerequisites

  • Node.js 20+ (check: node -v)
  • Git
  • JetBrains IDE (WebStorm/IntelliJ/etc.) with Claude Code plugin signed in
  • Optional: Claude (web) or ChatGPT for web-based agent runs

3) Install BMAD in your repository

From the project root:

# Install or update BMAD (idempotent)
npx bmad-method install

If you hit an npm glitch (e.g., cache issues), try:

npm cache clean --force
npx bmad-method install

What you should see created/updated:

.bmad-core/
  agents/
  agent-teams/
  checklists/
  data/
  tasks/
  templates/
  utils/
  workflows/
  core-config.yaml
bmad/
  web-bundles/
    agents/
    teams/
    expansion-packs/

Commit the new files:

git add .bmad-core bmad
git commit -m "chore(bmad): install method core + web bundles"

4) Recommended project docs layout

Create a minimal docs scaffold. The agents will read and write here.

mkdir -p docs/stories
  • docs/prd.md – Product Requirements Document
  • docs/architecture.md – System Architecture
  • docs/stories/ – One file per story/epic (created by PM/SM flows)

Tip: Keep large/generated folders excluded in your IDE (e.g., node_modules/, dist/) so the IDE assistant focuses on real code.

5) Using BMAD in the IDE (Claude Code)

Claude Code uses slash commands. It does not natively parse *agent directives or auto-load arbitrary folders. We’ll create four commands that wrap the core agents.

5.1 Create project slash commands

Make a commands folder (convention):

commands/bmad/
  pm.md
  sm.md
  dev.md
  qa.md

Put the following headers in each file, then paste the content of the corresponding core agent from .bmad-core/agents/*.md underneath the header.

5.2 (Optional) Pin always-loaded files

If your .bmad-core/core-config.yaml supports it, add key docs so agents always see them:

devLoadAlwaysFiles:
  - docs/prd.md
  - docs/architecture.md

5.3 Run the first BMAD cycle

Open Claude Code panel in the IDE and run these in order:

  1. PM → backlog
/pm Read docs/prd.md and produce a prioritized backlog (epics → stories) for a 1‑week iteration. Save stories in docs/stories/.
  1. SM → tasks
/sm For the top story in docs/stories/, generate step-by-step dev tasks + acceptance criteria and hand off one ready story to Dev.
  1. Dev → implementation
/dev Implement the handed-off story; modify code under src/; add tests; update docs as specified.
  1. QA → validation
/qa Validate the implementation against AC; list defects or mark verified.

Keep commits small and message them by story ID (e.g., feat(us-012): add sftp path validation).

6) Using BMAD in web chat (Claude/ChatGPT)

Web chat accepts large, single-file prompts. Use the bundled files you already have in bmad/web-bundles/.

6.1 Load a team or agent bundle

  • Team: bmad/web-bundles/teams/healthcare-team.txt
  • Single agent: bmad/web-bundles/agents/healthcare-pm.txt (or the standard pm.txt)

Paste the file into a new chat. Then use the BMAD web directive syntax:

*agent healthcare-pm
Create a minimal prioritized backlog from the following PRD (paste or link). Save output in story format.

6.2 Move outputs into the repo

Web chat cannot directly write your repo. Copy the generated stories/artefacts into docs/stories/ (or let the IDE agent rewrite them in place in a follow-up IDE step).

6.5) Using BMAD with Augment Code

Will BMAD break Augment? No. But avoid running two planners at once. Pick a Planner of Record (PoR) for each task:

  • BMAD as PoR → BMAD PM/SM plan the work; Augment executes (Dev/QA).
  • Augment as PoR → Augment plans; BMAD provides conventions and reviews.

Recommended workflow (BMAD plans, Augment executes)

  1. Produce a BMAD story/work order. Use /pm → /sm to create a story with clear Scope / Out of scope / Acceptance Criteria / Files to touch / Tests to add in docs/stories/US-###.md.
  2. Hand off to Augment with guard rails. Start a fresh Augment session and paste:
You are the executor. The high-level plan is fixed by BMAD.
Use the story below as the single source of truth.
- You MAY refine into step-by-step subtasks, but do NOT change scope or acceptance criteria.
- Ask ONE clarification question only if absolutely necessary; otherwise proceed.
- Make minimal diffs, add/modify tests, and ensure linters/CI pass.
- Update docs/stories/US-###.md status → "In Review" when done.

Story:
(paste docs/stories/US-###.md here)
  1. (Optional) Provide a structured work order. If Augment benefits from structured inputs, include a small YAML:
  1. Close the loop with BMAD. Run /qa to validate against AC; then /sm to move the story state.

If you prefer Augment to plan

  • Use Augment as PoR and prepend a small header to enforce BMAD conventions (write to docs/stories/, crisp AC, no PHI, commit style like feat(us-###): ...).
  • For tiny tasks, you can skip BMAD PM/SM and only keep BMAD’s folders/DoD.

Gotchas

  • Planner conflict: Don’t run BMAD /sm and Augment’s planner on the same task in the same session.
  • Missing outputs: Tell Augment exactly where to write tests/docs.
  • Context bloat: Exclude node_modules/, dist/, large logs.
  • Security: No real PHI; use placeholders.

Optional templates

  • templates/work_order.yaml — copy the YAML stub above.
  • scripts/story-to-workorder.* — small script to transform a BMAD story into the YAML work order.

7) Where BMAD reads/writes

  • Reads: docs/prd.md, docs/architecture.md, relevant code under src/, and any files listed in core-config.yaml(if configured).
  • Writes (common): docs/stories/*.md, diffs in src/, and QA checklists.

You can change these conventions, but standardizing them makes handoffs smoother.

8) Troubleshooting

“*agent doesn’t work in the IDE.”
Use slash commands in the IDE (/pm, /sm, …). The *agent directive is for web bundles.

“Claude Code isn’t seeing my custom commands.”
Ensure the command files are in your project, saved as .md, and you’re invoking them as /filename (without .md). Restart the IDE if needed.

“The PM wrote stories, but I can’t find them.”
By convention they go into docs/stories/. If missing, instruct PM explicitly to write there.

“Install failed / Node version errors.”
Verify Node 20+. Clear npm cache and rerun. If your network blocks registry, configure npm proxy.

“Claude keeps reading node_modules/.”
Mark heavy/generated folders as Excluded in the IDE. Keep the working set small.

“Healthcare: PHI concerns.”
Never paste real PHI into prompts. Use fake data or placeholders. Ensure stories include audit and access controls.

9) Example: quickstart commit

# 1) install bmad
npx bmad-method install

# 2) docs scaffold
mkdir -p docs/stories && touch docs/prd.md docs/architecture.md

echo "# PRD\n(TODO)" > docs/prd.md
echo "# Architecture\n(TODO)" > docs/architecture.md

# 3) add four IDE commands (edit in IDE or create files via shell)
mkdir -p commands/bmad
$EDITOR commands/bmad/pm.md
$EDITOR commands/bmad/sm.md
$EDITOR commands/bmad/dev.md
$EDITOR commands/bmad/qa.md

git add .bmad-core bmad docs commands
git commit -m "docs(bmad): wire PM/SM/Dev/QA commands and docs scaffold"

10) FAQ

Q: Can BMAD generate architecture diagrams?
Yes—ask PM/Architect to produce diagrams (Mermaid/PlantUML) and save them under docs/architecture/.

Q: Can I run the whole team automatically?
Create a /team command by wrapping .bmad-core/agent-teams/* to coordinate PM→SM→Dev→QA in one workflow, but keep iterations short.

11) Change control

  • Keep BMAD prompts versioned in the repo.
  • PR any changes to command files so the team stays aligned.

Credits

BMAD core folder names and conventions come from the BMAD Method project. This guide adapts them for general use with Claude Code and web chat workflows.

zichzheng

Leave a Reply

Your email address will not be published. Required fields are marked *