External/BMAD-METHOD
1
0
Fork 0
mirror of https://github.com/bmadcode/BMAD-METHOD.git synced 2025-12-29 16:14:59 +00:00
Code Issues Packages Projects Releases Wiki Activity
BMAD-METHOD/src/modules/bmm/docs/brownfield-guide.md

18 KiB
Raw Blame History

BMad Method Brownfield Development Guide

Complete guide for working with existing codebases

Reading Time: ~35 minutes

Quick Navigation

Jump to:

What is Brownfield Development?

Brownfield projects involve working within existing codebases rather than starting fresh:

  • Bug fixes - Single file changes
  • Small features - Adding to existing modules
  • Feature sets - Multiple related features
  • Major integrations - Complex architectural additions
  • System expansions - Enterprise-scale enhancements

Key Difference from Greenfield: You must understand and respect existing patterns, architecture, and constraints.

Core Principle: AI agents need comprehensive documentation to understand existing code before they can effectively plan or implement changes.

Getting Started

Understanding Planning Tracks

For complete track details, see Scale Adaptive System.

Brownfield tracks at a glance:

Track Scope Typical Stories Key Difference
Quick Flow Bug fixes, small features 1-15 Must understand affected code and patterns
BMad Method Feature sets, integrations 10-50+ Integrate with existing architecture
Enterprise Method Enterprise expansions 30+ Full system documentation + compliance required

Note: Story counts are guidance, not definitions. Tracks are chosen based on planning needs.

Track Selection for Brownfield

When you run workflow-init, it handles brownfield intelligently:

Step 1: Shows what it found

  • Old planning docs (PRD, epics, stories)
  • Existing codebase

Step 2: Asks about YOUR work

"Are these works in progress, previous effort, or proposed work?"

  • (a) Works in progress → Uses artifacts to determine level
  • (b) Previous effort → Asks you to describe NEW work
  • (c) Proposed work → Uses artifacts as guidance
  • (d) None of these → You explain your work

Step 3: Analyzes your description

  • Keywords: "fix", "bug" → Quick Flow, "dashboard", "platform" → BMad Method, "enterprise", "multi-tenant" → Enterprise Method
  • Complexity assessment
  • Confirms suggested track with you

Key Principle: System asks about YOUR current work first, uses old artifacts as context only.

Example: Old Complex PRD, New Simple Work

System: "Found PRD.md (BMad Method track, 30 stories, 6 months old)"
System: "Is this work in progress or previous effort?"
You: "Previous effort - I'm just fixing a bug now"
System: "Tell me about your current work"
You: "Update payment method enums"
System: "Quick Flow track (tech-spec approach). Correct?"
You: "Yes"
✅ Creates Quick Flow workflow

Phase 0: Documentation (Critical First Step)

🚨 For brownfield projects: Always ensure adequate documentation before planning

Three Scenarios

Scenario You Have Action Tool Time
A No documentation Run document-project Workflow 10-30m
B Docs exist, no index.md Run index-docs Task 2-5m
C Complete docs with index.md Skip Phase 0 - 0m

Scenario A: No Documentation

Run document-project workflow:

  1. Load Analyst agent
  2. Run "document-project"
  3. Choose scan level:
    • Quick (2-5min): Pattern analysis, no source reading
    • Deep (10-30min): Reads critical paths - Recommended
    • Exhaustive (30-120min): Reads all files

Outputs:

  • docs/index.md - Master AI entry point
  • docs/project-overview.md - Executive summary
  • docs/architecture.md - Architecture analysis
  • docs/source-tree-analysis.md - Directory structure
  • Additional files based on project type

Scenario B: Docs Exist, No Index

Run index-docs task:

  1. Load BMad Master agent (or any agent with task access)
  2. Load task: bmad/core/tasks/index-docs.xml
  3. Specify docs directory (e.g., ./docs)
  4. Task generates index.md from existing docs

Why index.md matters: Primary entry point for AI agents. Provides structured navigation even when good docs exist.

Scenario C: Complete Documentation

If docs/index.md exists with comprehensive content, skip to Phase 1 or 2.

Why document-project is Critical

Without it, workflows lack context:

  • tech-spec (Quick Flow) can't auto-detect stack/patterns
  • PRD (BMad Method/Enterprise) can't reference existing code
  • architecture (BMad Method/Enterprise) can't build on existing structure
  • story-context can't inject pattern-specific guidance

Workflow Phases by Track

Phase 1: Analysis (Optional)

Workflows:

  • brainstorm-project - Solution exploration
  • research - Technical/market research
  • product-brief - Strategic planning (BMad Method/Enterprise tracks only)

When to use: Complex features, technical decisions, strategic additions

When to skip: Bug fixes, well-understood features, time-sensitive changes

See Workflows Guide for details.

Phase 2: Planning (Required)

Planning approach adapts by track:

Quick Flow: Use tech-spec workflow

  • Creates tech-spec.md
  • Auto-detects existing stack (brownfield)
  • Confirms conventions with you
  • Generates implementation-ready stories

BMad Method/Enterprise: Use prd workflow

  • Creates PRD.md + epic breakdown
  • References existing architecture
  • Plans integration points

Brownfield-specific: See Scale Adaptive System for complete workflow paths by track.

Phase 3: Solutioning (BMad Method/Enterprise Only)

Critical for brownfield:

  • Review existing architecture FIRST
  • Document integration points explicitly
  • Plan backward compatibility
  • Consider migration strategy

Workflows:

  • create-architecture - Extend architecture docs (BMad Method/Enterprise)
  • solutioning-gate-check - Validate before implementation (BMad Method/Enterprise)

Phase 4: Implementation (All Tracks)

Sprint-based development through story iteration:

flowchart TD
    SPRINT[sprint-planning<br/>Initialize tracking]
    EPIC[epic-tech-context<br/>Per epic]
    CREATE[create-story]
    CONTEXT[story-context]
    DEV[dev-story]
    REVIEW[code-review]
    CHECK{More stories?}
    RETRO[retrospective<br/>Per epic]

    SPRINT --> EPIC
    EPIC --> CREATE
    CREATE --> CONTEXT
    CONTEXT --> DEV
    DEV --> REVIEW
    REVIEW --> CHECK
    CHECK -->|Yes| CREATE
    CHECK -->|No| RETRO

    style SPRINT fill:#bfb,stroke:#333,stroke-width:2px
    style RETRO fill:#fbf,stroke:#333,stroke-width:2px

Status Progression:

  • Epic: backlog → contexted
  • Story: backlog → drafted → ready-for-dev → in-progress → review → done

Brownfield-Specific Implementation Tips:

  1. Respect existing patterns - Follow established conventions
  2. Test integration thoroughly - Validate interactions with existing code
  3. Use feature flags - Enable gradual rollout
  4. Context injection matters - epic-tech-context and story-context reference existing patterns

Best Practices

1. Always Document First

Even if you know the code, AI agents need document-project output for context. Run it before planning.

2. Be Specific About Current Work

When workflow-init asks about your work:

  • ✅ "Update payment method enums to include Apple Pay"
  • ❌ "Fix stuff"

3. Choose Right Documentation Approach

  • Has good docs, no index? → Run index-docs task (fast)
  • No docs or need codebase analysis? → Run document-project (Deep scan)

4. Respect Existing Patterns

Tech-spec and story-context will detect conventions. Follow them unless explicitly modernizing.

5. Plan Integration Points Explicitly

Document in tech-spec/architecture:

  • Which existing modules you'll modify
  • What APIs/services you'll integrate with
  • How data flows between new and existing code

6. Design for Gradual Rollout

  • Use feature flags for new functionality
  • Plan rollback strategies
  • Maintain backward compatibility
  • Create migration scripts if needed

7. Test Integration Thoroughly

  • Regression testing of existing features
  • Integration point validation
  • Performance impact assessment
  • API contract verification

8. Use Sprint Planning Effectively

  • Run sprint-planning at Phase 4 start
  • Context epics before drafting stories
  • Update sprint-status.yaml as work progresses

9. Leverage Context Injection

  • Run epic-tech-context before story drafting
  • Always create story-context before implementation
  • These reference existing patterns for consistency

10. Learn Continuously

  • Run retrospective after each epic
  • Incorporate learnings into next stories
  • Update discovered patterns
  • Share insights across team

Common Scenarios

Scenario 1: Bug Fix (Quick Flow)

Situation: Authentication token expiration causing logout issues

Track: Quick Flow

Workflow:

  1. Document: Skip if auth system documented, else run document-project (Quick scan)
  2. Plan: Load PM → run tech-spec
    • Analyzes bug
    • Detects stack (Express, Jest)
    • Confirms conventions
    • Creates tech-spec.md + story
  3. Implement: Load DEV → run dev-story
  4. Review: Load DEV → run code-review

Time: 2-4 hours

Scenario 2: Small Feature (Quick Flow)

Situation: Add "forgot password" to existing auth system

Track: Quick Flow

Workflow:

  1. Document: Run document-project (Deep scan of auth module if not documented)
  2. Plan: Load PM → run tech-spec
    • Detects Next.js 13.4, NextAuth.js
    • Analyzes existing auth patterns
    • Confirms conventions
    • Creates tech-spec.md + epic + 3-5 stories
  3. Implement: Load SM → sprint-planning → create-story → story-context Load DEV → dev-story for each story
  4. Review: Load DEV → code-review

Time: 1-3 days

Scenario 3: Feature Set (BMad Method)

Situation: Add user dashboard with analytics, preferences, activity

Track: BMad Method

Workflow:

  1. Document: Run document-project (Deep scan) - Critical for understanding existing UI patterns
  2. Analyze: Load Analyst → research (if evaluating analytics libraries)
  3. Plan: Load PM → prd
  4. Solution: Load Architect → create-architecture → solutioning-gate-check
  5. Implement: Sprint-based (10-15 stories)
    • Load SM → sprint-planning
    • Per epic: epic-tech-context → stories
    • Load DEV → dev-story per story
  6. Review: Per story completion

Time: 1-2 weeks

Scenario 4: Complex Integration (BMad Method)

Situation: Add real-time collaboration to document editor

Track: BMad Method

Workflow:

  1. Document: Run document-project (Exhaustive if not documented) - Mandatory
  2. Analyze: Load Analyst → research (WebSocket vs WebRTC vs CRDT)
  3. Plan: Load PM → prd
  4. Solution:
    • Load Architect → create-architecture (extend for real-time layer)
    • Load Architect → solutioning-gate-check
  5. Implement: Sprint-based (20-30 stories)

Time: 3-6 weeks

Scenario 5: Enterprise Expansion (Enterprise Method)

Situation: Add multi-tenancy to single-tenant SaaS platform

Track: Enterprise Method

Workflow:

  1. Document: Run document-project (Exhaustive) - Mandatory
  2. Analyze: Required
    • brainstorm-project - Explore multi-tenancy approaches
    • research - Database sharding, tenant isolation, pricing
    • product-brief - Strategic document
  3. Plan: Load PM → prd (comprehensive)
  4. Solution:
    • create-architecture - Full system architecture
    • integration-planning - Phased migration strategy
    • create-architecture - Multi-tenancy architecture
    • validate-architecture - External review
    • solutioning-gate-check - Executive approval
  5. Implement: Phased sprint-based (50+ stories)

Time: 3-6 months

Troubleshooting

For complete troubleshooting, see Troubleshooting Guide.

AI Agents Lack Codebase Understanding

Symptoms:

  • Suggestions don't align with existing patterns
  • Ignores available components
  • Doesn't reference existing code

Solution:

  1. Run document-project with Deep scan
  2. Verify docs/index.md exists
  3. Check documentation completeness
  4. Run deep-dive on specific areas if needed

Have Documentation But Agents Can't Find It

Symptoms:

  • README.md, ARCHITECTURE.md exist
  • AI agents ask questions already answered
  • No docs/index.md file

Solution:

  • Quick fix: Run index-docs task (2-5min)
  • Comprehensive: Run document-project workflow (10-30min)

Integration Points Unclear

Symptoms:

  • Not sure how to connect new code to existing
  • Unsure which files to modify

Solution:

  1. Ensure document-project captured existing architecture
  2. Check story-context - should document integration points
  3. In tech-spec/architecture - explicitly document:
    • Which existing modules to modify
    • What APIs/services to integrate with
    • Data flow between new and existing code
  4. Review architecture document for integration guidance

Existing Tests Breaking

Symptoms:

  • Regression test failures
  • Previously working functionality broken

Solution:

  1. Review changes against existing patterns
  2. Verify API contracts unchanged (unless intentionally versioned)
  3. Run test-review workflow (TEA agent)
  4. Add regression testing to DoD
  5. Consider feature flags for gradual rollout

Inconsistent Patterns Being Introduced

Symptoms:

  • New code style doesn't match existing
  • Different architectural approach

Solution:

  1. Check convention detection (Quick Spec Flow should detect patterns)
  2. Review documentation - ensure document-project captured patterns
  3. Use story-context - injects pattern guidance
  4. Add to code-review checklist: pattern adherence, convention consistency
  5. Run retrospective to identify deviations early

Quick Reference

Commands by Phase

# Phase 0: Documentation (If Needed)
# Analyst agent:
document-project        # Create comprehensive docs (10-30min)
# OR load index-docs task for existing docs (2-5min)

# Phase 1: Analysis (Optional)
# Analyst agent:
brainstorm-project      # Explore solutions
research                # Gather data
product-brief           # Strategic planning (BMad Method/Enterprise only)

# Phase 2: Planning (Required)
# PM agent:
tech-spec               # Quick Flow track
prd                     # BMad Method/Enterprise tracks

# Phase 3: Solutioning (BMad Method/Enterprise)
# Architect agent:
create-architecture          # Extend architecture
solutioning-gate-check       # Final validation

# Phase 4: Implementation (All Tracks)
# SM agent:
sprint-planning              # Initialize tracking
epic-tech-context            # Epic context
create-story                 # Draft story
story-context                # Story context

# DEV agent:
dev-story                    # Implement
code-review                  # Review

# SM agent:
retrospective                # After epic
correct-course               # If issues

Key Files

Phase 0 Output:

  • docs/index.md - Master AI entry point (REQUIRED)
  • docs/project-overview.md
  • docs/architecture.md
  • docs/source-tree-analysis.md

Phase 1-3 Tracking:

  • docs/bmm-workflow-status.yaml - Progress tracker

Phase 2 Planning:

  • docs/tech-spec.md (Quick Flow track)
  • docs/PRD.md (BMad Method/Enterprise tracks)
  • Epic breakdown

Phase 3 Architecture:

  • docs/architecture.md (BMad Method/Enterprise tracks)

Phase 4 Implementation:

  • docs/sprint-status.yaml - Single source of truth
  • docs/epic-{n}-context.md
  • docs/stories/{epic}-{story}-{title}.md
  • docs/stories/{epic}-{story}-{title}-context.md

Decision Flowchart

flowchart TD
    START([Brownfield Project])
    CHECK{Has docs/<br/>index.md?}

    START --> CHECK
    CHECK -->|No| DOC[document-project<br/>Deep scan]
    CHECK -->|Yes| TRACK{What Track?}

    DOC --> TRACK

    TRACK -->|Quick Flow| TS[tech-spec]
    TRACK -->|BMad Method| PRD[prd → architecture]
    TRACK -->|Enterprise| PRD2[prd → arch + security/devops]

    TS --> IMPL[Phase 4<br/>Implementation]
    PRD --> IMPL
    PRD2 --> IMPL

    style START fill:#f9f,stroke:#333,stroke-width:2px
    style DOC fill:#ffb,stroke:#333,stroke-width:2px
    style IMPL fill:#bfb,stroke:#333,stroke-width:2px

Prevention Tips

Avoid issues before they happen:

  1. ✅ Always run document-project for brownfield - Saves context issues later
  2. ✅ Use fresh chats for complex workflows - Prevents hallucinations
  3. ✅ Verify files exist before workflows - Check PRD, epics, stories present
  4. ✅ Read agent menu first - Confirm agent has the workflow
  5. ✅ Start with simpler track if unsure - Easy to upgrade (Quick Flow → BMad Method)
  6. ✅ Keep status files updated - Manual updates when needed
  7. ✅ Run retrospectives after epics - Catch issues early
  8. ✅ Follow phase sequence - Don't skip required phases

Related Documentation

Support & Resources

Community:

Documentation:

Brownfield development is about understanding and respecting what exists while thoughtfully extending it.