Alex Verkhovsky
922c86d2c5
* docs: create Build a Change page and retire Quick Fixes and Build Consolidate how-to/quick-fixes and explanation/build into the canonical build/build-a-change page, opening with the sizing model and Where Build Fits table and preserving the Build diagram and intent examples. Add the Build sidebar group after Start, redirect both old routes, retarget first-party English links and the llms.txt entry, and close the resulting sidebar-order gaps. * fix(docs): track Build a Change page by scoping Astro build ignore The bare build/ gitignore rule also matched docs/build/, so the new canonical page never entered the prior commit. * docs: rewrite Build a Change page in plain English Name the skill as bmad-build instead of Build, drop the duplicated routing tables, and explain why it spends human attention on a few checkpoints instead of a Continue slog.
4.3 KiB
title, description, sidebar
| title | description | sidebar | ||
|---|---|---|---|---|
| Established Projects | How to use BMad Method on existing codebases |
|
Use BMad Method effectively when working on existing projects and legacy codebases.
This guide covers the essential workflow for onboarding to existing projects with BMad Method.
:::note[Prerequisites]
- BMad Method installed (
npx bmad-method install) - An existing codebase you want to work on
- Access to an AI-powered IDE (Claude Code or Cursor) :::
Step 1: Clean Up Completed Planning Artifacts
If you have completed all PRD epics and stories through the BMad process, clean up those files. Archive them, delete them, or rely on version history if needed. Do not keep these files in:
docs/_bmad-output/planning-artifacts/_bmad-output/implementation-artifacts/
Step 2: Create Project Context
:::tip[Recommended for Existing Projects] Build your project's context system so AI agents follow your established practices when implementing changes — this is the brownfield on-ramp. :::
Run the project context skill:
bmad-project-context
It reads what you already have and tells you how it measures up, asks what rules you want followed, then discovers and verifies the rest — running every command before writing it down. You end up with a small verified block in your repo's AGENTS.md instead of generated documentation volume. An existing hand-written file is a baseline it improves; a bloated docs/ folder is a source to verify against code, not something to add to.
Learn more about project context
Step 3: Maintain Quality Project Documentation
Your docs/ folder should contain succinct, well-organized documentation that accurately represents your project:
- Intent and business rationale
- Business rules
- Architecture
- Any other relevant project information
bmad-project-context audits and maintains the agent-facing part of this — run its audit any time the context feels stale; it shrinks and re-verifies rather than accreting. (The earlier bmad-document-project workflow is deprecated and forwards there.)
Step 3: Get Help
BMad-Help: Your Starting Point
Run bmad-help anytime you're unsure what to do next. This intelligent guide:
- Inspects your project to see what's already been done
- Shows options based on your installed modules
- Understands natural language queries
bmad-help I have an existing Rails app, where should I start?
bmad-help How much planning does this change need before implementation?
bmad-help Show me what workflows are available
BMad-Help also automatically runs at the end of every workflow, providing clear guidance on exactly what to do next.
Choose Planning Depth
All implementation uses bmad-build; scope determines what context you prepare first:
| Scope | Recommended preparation |
|---|---|
| Clear updates or additions | Enter bmad-build directly with the request, issue, or existing spec. |
| Major changes or additions | Prepare the useful PRD, UX, architecture, epic, story, readiness, and sprint context, then pass the selected work to bmad-build. |
During PRD Creation
When creating a brief or jumping directly into the PRD, ensure the agent:
- Finds and analyzes your existing project documentation
- Reads the proper context about your current system
You can guide the agent explicitly, but the goal is to ensure the new feature integrates well with your existing system.
UX Considerations
UX work is optional. The decision depends not on whether your project has a UX, but on:
- Whether you will be working on UX changes
- Whether significant new UX designs or patterns are needed
If your changes amount to simple updates to existing screens you are happy with, a full UX process is unnecessary.
Architecture Considerations
When doing architecture, ensure the architect:
- Uses the proper documented files
- Scans the existing codebase
Pay close attention here to prevent reinventing the wheel or making decisions that misalign with your existing architecture.
More Information
- Build a Change - Bug fixes and ad-hoc changes
- Established Projects FAQ - Common questions about working on established projects