docs/how-to/established-projects.md
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]
npx bmad-method install)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/:::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
Your docs/ folder should contain succinct, well-organized documentation that accurately represents your project:
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.)
Run bmad-help anytime you're unsure what to do next. This intelligent guide:
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.
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. |
When creating a brief or jumping directly into the PRD, ensure the agent:
You can guide the agent explicitly, but the goal is to ensure the new feature integrates well with your existing system.
UX work is optional. The decision depends not on whether your project has a UX, but on:
If your changes amount to simple updates to existing screens you are happy with, a full UX process is unnecessary.
When doing architecture, ensure the architect:
Pay close attention here to prevent reinventing the wheel or making decisions that misalign with your existing architecture.