mirror of
https://github.com/bmad-code-org/BMAD-METHOD.git
synced 2026-01-30 04:32:02 +00:00
2e16650067
* feat(docs): add Diataxis folder structure and update sidebar styling - Create tutorials, how-to, explanation, reference directories with subdirectories - Add index.md files for each main Diataxis section - Update homepage with Diataxis card navigation layout - Implement clean React Native-inspired sidebar styling - Convert sidebar to autogenerated for both Diataxis and legacy sections - Update docusaurus config with dark mode default and navbar changes 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * feat(docs): migrate Phase 1 files to Diataxis structure Move 21 files to new locations: - Tutorials: quick-start guides, agent creation guide - How-To: installation, customization, workflows - Explanation: core concepts, features, game-dev, builder - Reference: merged glossary from BMM and BMGD Also: - Copy images to new locations - Update internal links via migration script (73 links updated) - Build verified successfully 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix(docs): add category labels for sidebar folders Add _category_.json files to control display labels and position for autogenerated sidebar categories. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * style(docs): improve welcome page and visual styling - Rewrite index.md with React Native-inspired welcoming layout - Add Diataxis section cards with descriptions - Remove sidebar separator, add spacing instead - Increase navbar padding with responsive breakpoints - Add rounded admonitions without left border bar - Use system font stack for better readability - Add lighter chevron styling in sidebar - Constrain max-width to 1600px for wide viewports 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix: use baseUrl in meta tag paths for correct deployment URLs * feat(docs): complete Phase 2 - split files and fix broken links Phase 2 of Diataxis migration: - Split 16 large legacy files into 42+ focused documents - Created FAQ section with 7 topic-specific files - Created brownfield how-to guides (3 files) - Created workflow how-to guides (15+ files) - Created architecture explanation files (3 files) - Created TEA/testing explanation files - Moved remaining legacy module files to proper Diataxis locations Link fixes: - Fixed ~50 broken internal links across documentation - Updated relative paths for new file locations - Created missing index files for installation, advanced tutorials - Simplified TOC anchors to fix Docusaurus warnings Cleanup: - Removed legacy sidebar entries for deleted folders - Deleted duplicate and empty placeholder files - Moved workflow diagram assets to tutorials/images 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix(build): use file glob instead of sidebar parsing for llms-full.txt Replace brittle sidebar.js regex parsing with recursive file glob. The old approach captured non-file strings like 'autogenerated' and category labels, resulting in only 5 files being processed. Now correctly processes all 86+ markdown files (~95k tokens). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix(seo): use absolute URLs in AI meta tags for agent discoverability AI web-browsing agents couldn't follow relative paths in meta tags due to URL security restrictions. Changed llms-full.txt and llms.txt meta tag URLs from relative (baseUrl) to absolute (urlParts.origin + baseUrl). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * refactor(docs): recategorize misplaced files per Diataxis analysis Phase 2.5 categorization fixes based on post-migration analysis: Moved to correct Diataxis categories: - tutorials/installation.md → deleted (duplicate of how-to/install-bmad.md) - tutorials/brownfield-onboarding.md → how-to/brownfield/index.md - reference/faq/* (8 files) → explanation/faq/ - reference/agents/barry-quick-flow.md → explanation/agents/ - reference/agents/bmgd-agents.md → explanation/game-dev/agents.md Created: - explanation/agents/index.md Fixed all broken internal links (14 total) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * feat(docs): add Getting Started tutorial and simplify build script - Add comprehensive Getting Started tutorial with installation as Step 1 - Simplify build-docs.js to read directly from docs/ (no consolidation) - Remove backup/restore dance that could corrupt docs folder on build failure - Remove ~150 lines of unused consolidation code 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix(css): use fixed width layout to prevent content shifting Apply React Native docs approach: set both width and max-width at largest breakpoint (1400px) so content area maintains consistent size regardless of content length. Switches to fluid 100% below 1416px breakpoint. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * refactor(docs): restructure tutorials with renamed entry point - Rename index.md to bmad-tutorial.md for clearer navigation - Remove redundant tutorials/index.md - Update sidebar and config references 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * feat(docs): add tutorial style guide and AI agent announcement bar - Add docs/_contributing/ with tutorial style guide - Reformat quick-start-bmm.md and bmad-tutorial.md per style guide - Remove horizontal separators, add strategic admonitions - Add persistent announcement bar for AI agents directing to llms-full.txt - Fix footer broken link to tutorials 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * feat(docs): add markdown demo page and UI refinements - Add comprehensive markdown-demo.md for style testing - Remove doc category links from navbar (use sidebar instead) - Remove card buttons from welcome page - Add dark mode styling for announcement bar - Clean up index.md card layout 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * feat(docs): apply unified tutorial style and update references - Reformat create-custom-agent.md to follow tutorial style guide - Update tutorial-style.md with complete unified structure - Update all internal references to renamed tutorial files - Remove obsolete advanced/index.md 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * refactor(docs): migrate from Docusaurus to Astro+Starlight Replace Docusaurus with Astro and the Starlight documentation theme for improved performance, better customization, and modern tooling. Build pipeline changes: - New build-docs.js orchestrates link checking, artifact generation, and Astro build in sequence - Add check-doc-links.js for validating internal links and anchors - Generate llms.txt and llms-full.txt for LLM-friendly documentation - Create downloadable source bundles (bmad-sources.zip, bmad-prompts.zip) - Suppress MODULE_TYPELESS_PACKAGE_JSON warning in Astro build - Output directly to build/site for cleaner deployment Website architecture: - Add rehype-markdown-links.js plugin to transform .md links to routes - Add site-url.js helper for GitHub Pages URL resolution with strict validation (throws on invalid GITHUB_REPOSITORY format) - Custom Astro components: Banner, Header, MobileMenuFooter - Symlink docs/ into website/src/content/docs for Starlight Documentation cleanup: - Remove Docusaurus _category_.json files (Starlight uses frontmatter) - Convert all docs to use YAML frontmatter with title field - Move downloads.md from website/src/pages to docs/ - Consolidate style guide and workflow diagram docs - Add 404.md and tutorials/index.md --------- Co-authored-by: forcetrainer <bryan@inagaki.us> Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
103 lines
4.0 KiB
Markdown
103 lines
4.0 KiB
Markdown
---
|
|
title: "Brownfield Development"
|
|
description: How to use BMad Method on existing codebases
|
|
---
|
|
|
|
|
|
How to effectively use BMad Method when working on existing projects and legacy codebases.
|
|
|
|
## What is Brownfield Development?
|
|
|
|
**Brownfield** refers to working on existing projects with established codebases and patterns, as opposed to **greenfield** which means starting from scratch with a clean slate.
|
|
|
|
This tutorial covers the essential workflow for onboarding to brownfield 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, Cursor, or Windsurf)
|
|
|
|
---
|
|
|
|
## 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: 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 3: Initialize for Brownfield Work
|
|
|
|
Run `workflow-init`. It should recognize you are in an existing project. If not, explicitly clarify that this is brownfield development for a new feature.
|
|
|
|
### Choosing Your Approach
|
|
|
|
You have two primary options depending on the scope of changes:
|
|
|
|
| Scope | Recommended Approach |
|
|
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
|
|
| **Small updates or additions** | Use `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 additions** | Start 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.
|
|
|
|
---
|
|
|
|
## Next Steps
|
|
|
|
- **[Document Existing Project](../../how-to/brownfield/document-existing-project.md)** - How to document your brownfield codebase
|
|
- **[Add Feature to Existing Project](../../how-to/brownfield/add-feature-to-existing.md)** - Adding new functionality
|
|
- **[Quick Fix in Brownfield](../../how-to/brownfield/quick-fix-in-brownfield.md)** - Bug fixes and ad-hoc changes
|
|
- **[Brownfield FAQ](../../explanation/faq/brownfield-faq.md)** - Common questions about brownfield development
|
|
|
|
---
|
|
|
|
## Related Documentation
|
|
|
|
- [Quick Start Guide](../../tutorials/getting-started/getting-started-bmadv6.md) - Getting started with BMM
|
|
- [Quick Spec Flow](../../explanation/features/quick-flow.md) - Fast path for small changes
|