docs: improve project-context documentation and fix folder structure
- Add explanation/how-to docs for project-context.md feature - Update workflow-map Context Management section with comprehensive guidance - Fix folder structure examples to show proper nested subdirectories (planning-artifacts/ and implementation-artifacts/ under _bmad-output/) - Update established-projects.md with project-context creation step - Standardize terminology: use "existing projects" instead of "brownfield"
This commit is contained in:
Brian Madison
parent
d6cc8b060a
commit
d4b4bdfa12
|
|
@ -75,9 +75,12 @@ Show in "What You've Accomplished" sections:
|
|||
````md
|
||||
```
|
||||
your-project/
|
||||
├── _bmad/ # BMad configuration
|
||||
├── _bmad/ # BMad configuration
|
||||
├── _bmad-output/
|
||||
│ ├── PRD.md # Your requirements document
|
||||
│ ├── planning-artifacts/
|
||||
│ │ └── PRD.md # Your requirements document
|
||||
│ ├── implementation-artifacts/
|
||||
│ └── project-context.md # Implementation rules (optional)
|
||||
└── ...
|
||||
```
|
||||
````
|
||||
|
|
|
|||
|
|
@ -0,0 +1,157 @@
|
|||
---
|
||||
title: "Project Context"
|
||||
description: How project-context.md guides AI agents with your project's rules and preferences
|
||||
sidebar:
|
||||
order: 7
|
||||
---
|
||||
|
||||
The `project-context.md` file is your project's implementation guide for AI agents. Similar to a "constitution" in other development systems, it captures the rules, patterns, and preferences that ensure consistent code generation across all workflows.
|
||||
|
||||
## What It Does
|
||||
|
||||
AI agents make implementation decisions constantly — which patterns to follow, how to structure code, what conventions to use. Without clear guidance, they may:
|
||||
- Follow generic best practices that don't match your codebase
|
||||
- Make inconsistent decisions across different stories
|
||||
- Miss project-specific requirements or constraints
|
||||
|
||||
The `project-context.md` file solves this by documenting what agents need to know in a concise, LLM-optimized format.
|
||||
|
||||
## How It Works
|
||||
|
||||
Every implementation workflow automatically loads `project-context.md` if it exists. The architect workflow also loads it to respect your technical preferences when designing the architecture.
|
||||
|
||||
**Loaded by these workflows:**
|
||||
- `create-architecture` — respects technical preferences during solutioning
|
||||
- `create-story` — informs story creation with project patterns
|
||||
- `dev-story` — guides implementation decisions
|
||||
- `code-review` — validates against project standards
|
||||
- `quick-dev` — applies patterns when implementing tech-specs
|
||||
- `sprint-planning`, `retrospective`, `correct-course` — provides project-wide context
|
||||
|
||||
## When to Create It
|
||||
|
||||
The `project-context.md` file is useful at any stage of a project:
|
||||
|
||||
| Scenario | When to Create | Purpose |
|
||||
|----------|----------------|---------|
|
||||
| **New project, before architecture** | Manually, before `create-architecture` | Document your technical preferences so the architect respects them |
|
||||
| **New project, after architecture** | Via `generate-project-context` or manually | Capture architecture decisions for implementation agents |
|
||||
| **Existing project** | Via `generate-project-context` | Discover existing patterns so agents follow established conventions |
|
||||
| **Quick Flow project** | Before or during `quick-dev` | Ensure quick implementation respects your patterns |
|
||||
|
||||
:::tip[Recommended]
|
||||
For new projects, create it manually before architecture if you have strong technical preferences. Otherwise, generate it after architecture to capture those decisions.
|
||||
:::
|
||||
|
||||
## What Goes In It
|
||||
|
||||
The file has two main sections:
|
||||
|
||||
### Technology Stack & Versions
|
||||
|
||||
Documents the frameworks, languages, and tools your project uses with specific versions:
|
||||
|
||||
```markdown
|
||||
## Technology Stack & Versions
|
||||
|
||||
- Node.js 20.x, TypeScript 5.3, React 18.2
|
||||
- State: Zustand (not Redux)
|
||||
- Testing: Vitest, Playwright, MSW
|
||||
- Styling: Tailwind CSS with custom design tokens
|
||||
```
|
||||
|
||||
### Critical Implementation Rules
|
||||
|
||||
Documents patterns and conventions that agents might otherwise miss:
|
||||
|
||||
```markdown
|
||||
## Critical Implementation Rules
|
||||
|
||||
**TypeScript Configuration:**
|
||||
- Strict mode enabled — no `any` types without explicit approval
|
||||
- Use `interface` for public APIs, `type` for unions/intersections
|
||||
|
||||
**Code Organization:**
|
||||
- Components in `/src/components/` with co-located `.test.tsx`
|
||||
- Utilities in `/src/lib/` for reusable pure functions
|
||||
- API calls use the `apiClient` singleton — never fetch directly
|
||||
|
||||
**Testing Patterns:**
|
||||
- Unit tests focus on business logic, not implementation details
|
||||
- Integration tests use MSW to mock API responses
|
||||
- E2E tests cover critical user journeys only
|
||||
|
||||
**Framework-Specific:**
|
||||
- All async operations use the `handleError` wrapper for consistent error handling
|
||||
- Feature flags accessed via `featureFlag()` from `@/lib/flags`
|
||||
- New routes follow the file-based routing pattern in `/src/app/`
|
||||
```
|
||||
|
||||
Focus on what's **unobvious** — things agents might not infer from reading code snippets. Don't document standard practices that apply universally.
|
||||
|
||||
## Creating the File
|
||||
|
||||
You have three options:
|
||||
|
||||
### Manual Creation
|
||||
|
||||
Create the file at `_bmad-output/project-context.md` and add your rules:
|
||||
|
||||
```bash
|
||||
# In your project root
|
||||
mkdir -p _bmad-output
|
||||
touch _bmad-output/project-context.md
|
||||
```
|
||||
|
||||
Edit it with your technology stack and implementation rules. The architect and implementation workflows will automatically find and load it.
|
||||
|
||||
### Generate After Architecture
|
||||
|
||||
Run the `generate-project-context` workflow after completing your architecture:
|
||||
|
||||
```bash
|
||||
/bmad-bmm-generate-project-context
|
||||
```
|
||||
|
||||
This scans your architecture document and project files to generate a context file capturing the decisions made.
|
||||
|
||||
### Generate for Existing Projects
|
||||
|
||||
For existing projects, run `generate-project-context` to discover existing patterns:
|
||||
|
||||
```bash
|
||||
/bmad-bmm-generate-project-context
|
||||
```
|
||||
|
||||
The workflow analyzes your codebase to identify conventions, then generates a context file you can review and refine.
|
||||
|
||||
## Why It Matters
|
||||
|
||||
Without `project-context.md`, agents make assumptions that may not match your project:
|
||||
|
||||
| Without Context | With Context |
|
||||
|----------------|--------------|
|
||||
| Uses generic patterns | Follows your established conventions |
|
||||
| Inconsistent style across stories | Consistent implementation |
|
||||
| May miss project-specific constraints | Respects all technical requirements |
|
||||
| Each agent decides independently | All agents align with same rules |
|
||||
|
||||
This is especially important for:
|
||||
- **Quick Flow** — skips PRD and architecture, so context file fills the gap
|
||||
- **Team projects** — ensures all agents follow the same standards
|
||||
- **Existing projects** — prevents breaking established patterns
|
||||
|
||||
## Editing and Updating
|
||||
|
||||
The `project-context.md` file is a living document. Update it when:
|
||||
|
||||
- Architecture decisions change
|
||||
- New conventions are established
|
||||
- Patterns evolve during implementation
|
||||
- You identify gaps from agent behavior
|
||||
|
||||
You can edit it manually at any time, or re-run `generate-project-context` to update it after significant changes.
|
||||
|
||||
:::note[File Location]
|
||||
The default location is `_bmad-output/project-context.md`. Workflows search for it there, and also check `**/project-context.md` anywhere in your project.
|
||||
:::
|
||||
|
|
@ -5,7 +5,7 @@ sidebar:
|
|||
order: 6
|
||||
---
|
||||
|
||||
Use BMad Method effectively when working on existing projects and legacy codebases, sometimes also referred to as brownfield projects.
|
||||
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.
|
||||
|
||||
|
|
@ -23,7 +23,30 @@ If you have completed all PRD epics and stories through the BMad process, clean
|
|||
- `_bmad-output/planning-artifacts/`
|
||||
- `_bmad-output/implementation-artifacts/`
|
||||
|
||||
## Step 2: Maintain Quality Project Documentation
|
||||
## Step 2: Create Project Context
|
||||
|
||||
:::tip[Recommended for Existing Projects]
|
||||
Generate `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:
|
||||
|
||||
```bash
|
||||
/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](../explanation/project-context.md)
|
||||
|
||||
## Step 3: Maintain Quality Project Documentation
|
||||
|
||||
Your `docs/` folder should contain succinct, well-organized documentation that accurately represents your project:
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,136 @@
|
|||
---
|
||||
title: "Manage Project Context"
|
||||
description: Create and maintain project-context.md to guide AI agents
|
||||
sidebar:
|
||||
order: 7
|
||||
---
|
||||
|
||||
Use the `project-context.md` file to ensure AI agents follow your project's technical preferences and implementation rules throughout all workflows.
|
||||
|
||||
:::note[Prerequisites]
|
||||
- BMad Method installed
|
||||
- Understanding of your project's technology stack and conventions
|
||||
:::
|
||||
|
||||
## When to Use This
|
||||
|
||||
- You have strong technical preferences before starting architecture
|
||||
- You've completed architecture and want to capture decisions for implementation
|
||||
- You're working on an existing codebase with established patterns
|
||||
- You notice agents making inconsistent decisions across stories
|
||||
|
||||
## Step 1: Choose Your Approach
|
||||
|
||||
**Manual creation** — Best when you know exactly what rules you want to document
|
||||
|
||||
**Generate after architecture** — Best for capturing decisions made during solutioning
|
||||
|
||||
**Generate for existing projects** — Best for discovering patterns in existing codebases
|
||||
|
||||
## Step 2: Create the File
|
||||
|
||||
### Option A: Manual Creation
|
||||
|
||||
Create the file at `_bmad-output/project-context.md`:
|
||||
|
||||
```bash
|
||||
mkdir -p _bmad-output
|
||||
touch _bmad-output/project-context.md
|
||||
```
|
||||
|
||||
Add your technology stack and implementation rules:
|
||||
|
||||
```markdown
|
||||
---
|
||||
project_name: 'MyProject'
|
||||
user_name: 'YourName'
|
||||
date: '2026-02-15'
|
||||
sections_completed: ['technology_stack', 'critical_rules']
|
||||
---
|
||||
|
||||
# Project Context for AI Agents
|
||||
|
||||
## Technology Stack & Versions
|
||||
|
||||
- Node.js 20.x, TypeScript 5.3, React 18.2
|
||||
- State: Zustand
|
||||
- Testing: Vitest, Playwright
|
||||
- Styling: Tailwind CSS
|
||||
|
||||
## Critical Implementation Rules
|
||||
|
||||
**TypeScript:**
|
||||
- Strict mode enabled, no `any` types
|
||||
- Use `interface` for public APIs, `type` for unions
|
||||
|
||||
**Code Organization:**
|
||||
- Components in `/src/components/` with co-located tests
|
||||
- API calls use `apiClient` singleton — never fetch directly
|
||||
|
||||
**Testing:**
|
||||
- Unit tests focus on business logic
|
||||
- Integration tests use MSW for API mocking
|
||||
```
|
||||
|
||||
### Option B: Generate After Architecture
|
||||
|
||||
Run the workflow in a fresh chat:
|
||||
|
||||
```bash
|
||||
/bmad-bmm-generate-project-context
|
||||
```
|
||||
|
||||
The workflow scans your architecture document and project files to generate a context file capturing the decisions made.
|
||||
|
||||
### Option C: Generate for Existing Projects
|
||||
|
||||
For existing projects, run:
|
||||
|
||||
```bash
|
||||
/bmad-bmm-generate-project-context
|
||||
```
|
||||
|
||||
The workflow analyzes your codebase to identify conventions, then generates a context file you can review and refine.
|
||||
|
||||
## Step 3: Verify Content
|
||||
|
||||
Review the generated file and ensure it captures:
|
||||
|
||||
- Correct technology versions
|
||||
- Your actual conventions (not generic best practices)
|
||||
- Rules that prevent common mistakes
|
||||
- Framework-specific patterns
|
||||
|
||||
Edit manually to add anything missing or remove inaccuracies.
|
||||
|
||||
## What You Get
|
||||
|
||||
A `project-context.md` file that:
|
||||
|
||||
- Ensures all agents follow the same conventions
|
||||
- Prevents inconsistent decisions across stories
|
||||
- Captures architecture decisions for implementation
|
||||
- Serves as a reference for your project's patterns and rules
|
||||
|
||||
## Tips
|
||||
|
||||
:::tip[Focus on the Unobvious]
|
||||
Document patterns agents might miss such as "Use JSDoc style comments on every public class, function and variable", not universal practices like "use meaningful variable names" which LLMs know at this point.
|
||||
:::
|
||||
|
||||
:::tip[Keep It Lean]
|
||||
This file is loaded by every implementation workflow. Long files waste context. Do not include content that only applies to narrow scope or specific stories or features.
|
||||
:::
|
||||
|
||||
:::tip[Update as Needed]
|
||||
Edit manually when patterns change, or re-generate after significant architecture changes.
|
||||
:::
|
||||
|
||||
:::tip[Works for All Project Types]
|
||||
Just as useful for Quick Flow as for full BMad Method projects.
|
||||
:::
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [**Project Context Explanation**](../explanation/project-context.md) — Learn more about how it works
|
||||
- [**Workflow Map**](../reference/workflow-map.md) — See which workflows load project context
|
||||
|
|
@ -23,11 +23,11 @@ Document sharding splits large markdown files into smaller, organized files base
|
|||
|
||||
```text
|
||||
Before Sharding:
|
||||
docs/
|
||||
_bmad-output/planning-artifacts/
|
||||
└── PRD.md (large 50k token file)
|
||||
|
||||
After Sharding:
|
||||
docs/
|
||||
_bmad-output/planning-artifacts/
|
||||
└── prd/
|
||||
├── index.md # Table of contents with descriptions
|
||||
├── overview.md # Section 1
|
||||
|
|
|
|||
|
|
@ -77,14 +77,46 @@ Skip phases 1-3 for small, well-understood work.
|
|||
|
||||
Each document becomes context for the next phase. The PRD tells the architect what constraints matter. The architecture tells the dev agent which patterns to follow. Story files give focused, complete context for implementation. Without this structure, agents make inconsistent decisions.
|
||||
|
||||
For established projects, `document-project` creates or updates `project-context.md` - what exists in the codebase and the rules all implementation workflows must observe. Run it just before Phase 4, and again when something significant changes - structure, architecture, or those rules. You can also edit `project-context.md` by hand.
|
||||
### Project Context
|
||||
|
||||
All implementation workflows load `project-context.md` if it exists. Additional context per workflow:
|
||||
:::tip[Recommended]
|
||||
Create `project-context.md` to ensure AI agents follow your project's rules and preferences. This file works like a constitution for your project — it guides implementation decisions across all workflows.
|
||||
:::
|
||||
|
||||
| Workflow | Also Loads |
|
||||
| -------------- | ---------------------------- |
|
||||
**When to create it:**
|
||||
|
||||
| Scenario | Approach |
|
||||
|----------|----------|
|
||||
| Before architecture (manual) | Document technical preferences you want the architect to respect |
|
||||
| After architecture | Generate it to capture decisions made during solutioning |
|
||||
| Existing projects | Run `generate-project-context` to discover established patterns |
|
||||
| Quick Flow | Create before `quick-dev` to ensure consistent implementation |
|
||||
|
||||
**How to create it:**
|
||||
|
||||
- **Manually** — Create `_bmad-output/project-context.md` with your technology stack and implementation rules
|
||||
- **Generate it** — Run `/bmad-bmm-generate-project-context` to auto-generate from your architecture or codebase
|
||||
|
||||
**What workflows load it:**
|
||||
|
||||
| Workflow | Purpose |
|
||||
|----------|---------|
|
||||
| `create-architecture` | Respects technical preferences when designing |
|
||||
| `create-story` | Informs story creation with project patterns |
|
||||
| `dev-story` | Guides implementation decisions |
|
||||
| `code-review` | Validates against project standards |
|
||||
| `quick-dev` | Applies patterns when implementing |
|
||||
|
||||
[**Learn more about project-context.md**](../explanation/project-context.md)
|
||||
|
||||
### Additional Context by Workflow
|
||||
|
||||
Beyond `project-context.md`, each workflow loads specific documents:
|
||||
|
||||
| Workflow | Also Loads |
|
||||
|----------|------------|
|
||||
| `create-story` | epics, PRD, architecture, UX |
|
||||
| `dev-story` | story file |
|
||||
| `code-review` | architecture, story file |
|
||||
| `quick-spec` | planning docs (if exist) |
|
||||
| `quick-dev` | tech-spec |
|
||||
| `dev-story` | story file |
|
||||
| `code-review` | architecture, story file |
|
||||
| `quick-spec` | planning docs (if exist) |
|
||||
| `quick-dev` | tech-spec |
|
||||
|
|
|
|||
|
|
@ -79,6 +79,12 @@ Always start a fresh chat for each workflow. This prevents context limitations f
|
|||
|
||||
Work through phases 1-3. **Use fresh chats for each workflow.**
|
||||
|
||||
:::tip[Project Context (Optional)]
|
||||
Before starting, consider creating `project-context.md` to document your technical preferences and implementation rules. This ensures all AI agents follow your conventions throughout the project.
|
||||
|
||||
Create it manually at `_bmad-output/project-context.md` or generate it after architecture using `/bmad-bmm-generate-project-context`. [Learn more](../explanation/project-context.md).
|
||||
:::
|
||||
|
||||
### Phase 1: Analysis (Optional)
|
||||
|
||||
All workflows in this phase are optional:
|
||||
|
|
@ -155,12 +161,15 @@ Your project now has:
|
|||
|
||||
```text
|
||||
your-project/
|
||||
├── _bmad/ # BMad configuration
|
||||
├── _bmad/ # BMad configuration
|
||||
├── _bmad-output/
|
||||
│ ├── PRD.md # Your requirements document
|
||||
│ ├── architecture.md # Technical decisions
|
||||
│ ├── epics/ # Epic and story files
|
||||
│ └── sprint-status.yaml # Sprint tracking
|
||||
│ ├── planning-artifacts/
|
||||
│ │ ├── PRD.md # Your requirements document
|
||||
│ │ ├── architecture.md # Technical decisions
|
||||
│ │ └── epics/ # Epic and story files
|
||||
│ ├── implementation-artifacts/
|
||||
│ │ └── sprint-status.yaml # Sprint tracking
|
||||
│ └── project-context.md # Implementation rules (optional)
|
||||
└── ...
|
||||
```
|
||||
|
||||
|
|
@ -171,6 +180,7 @@ your-project/
|
|||
| `help` | `/bmad-help` | Any | Get guidance on what to do next |
|
||||
| `prd` | `/bmad-bmm-create-prd` | PM | Create Product Requirements Document |
|
||||
| `create-architecture` | `/bmad-bmm-create-architecture` | Architect | Create architecture document |
|
||||
| `generate-project-context` | `/bmad-bmm-generate-project-context` | Analyst | Create project context file |
|
||||
| `create-epics-and-stories` | `/bmad-bmm-create-epics-and-stories` | PM | Break down PRD into epics |
|
||||
| `check-implementation-readiness` | `/bmad-bmm-check-implementation-readiness` | Architect | Validate planning cohesion |
|
||||
| `sprint-planning` | `/bmad-bmm-sprint-planning` | SM | Initialize sprint tracking |
|
||||
|
|
|
|||
Loading…
Reference in New Issue