Skip to main content
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.
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

Recommended for Existing ProjectsGenerate project-context.md to capture your existing codebase patterns and conventions. This ensures AI agents follow your established practices when implementing changes.
Run the generate project context workflow: 
/bmad-bmm-generate-project-context
This scans your codebase to identify:
  • Technology stack and versions
  • Code organization patterns
  • Naming conventions
  • Testing approaches
  • Framework-specific patterns
You can review and refine the generated file, or create it manually at _bmad-output/project-context.md if you prefer. 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
For complex projects, consider using the document-project workflow. It offers runtime variants that will scan your entire project and document its actual current state.

​
Step 4: 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 What's the difference between quick-flow and full method?
/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.

​
Choosing Your Approach

You have two primary options depending on the scope of changes:
ScopeRecommended Approach
Small updates or additionsUse quick-flow-solo-dev to create a tech-spec and implement the change. The full four-phase BMad Method is likely overkill.
Major changes or additionsStart with the BMad Method, applying as much or as little rigor as needed.

​
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.

​
Common Workflows for Established Projects

​
Adding New Features

  1. Generate or update project-context.md (if not already done)
  2. Run /bmad-help to determine the right approach
  3. For small features: use Quick Flow Solo Dev
  4. For major features: run the full BMad Method starting with Brief or PRD

​
Bug Fixes and Refactoring

For quick fixes, see the Quick Fixes guide. For larger refactoring efforts, consider using Quick Flow or the full Method to plan and execute the changes systematically.

​
Documentation Updates

Use the document-project workflow to:
  • Generate or update architecture documentation
  • Document existing system behavior
  • Create onboarding documentation for new team members

​
Best Practices

Start SmallBegin with a small feature or bug fix to get comfortable with BMad workflows before tackling larger changes.
Keep Context FreshUpdate project-context.md whenever you introduce new patterns, technologies, or conventions.
Use Fresh ChatsAlways start a new chat when loading a workflow or agent to avoid context contamination.
Avoid Analysis ParalysisNot every change needs the full BMad Method. Use Quick Flow or direct DEV agent work for straightforward changes.

​
More Information

Build docs developers (and LLMs) love

Get started for freeTalk to us