6.5 KiB

Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Overview

This is the Self-Evolving BMAD (Breakthrough Method of Agile AI-driven Development) Framework - an adaptive AI-orchestrated development methodology that continuously improves itself through project experience. The system enables rapid project planning, architecture design, and implementation while learning and optimizing its own processes.

Self-Improvement Strategy

Core Philosophy

Continuous Evolution: The methodology improves with each project milestone
Milestone-Based Learning: Git commits mark methodology evolution checkpoints
User-Approved Changes: Major methodology changes require explicit approval
Rollback Capability: Version control allows reverting to previous methodology states

Improvement Triggers

Post-Milestone Retrospectives: Automatic analysis after each phase completion
Pattern Recognition: Identification of successful vs. problematic workflows
User Feedback: Systematic incorporation of user insights
Effectiveness Metrics: Measurement of velocity, quality, and satisfaction

Architecture and Structure

Core Components

Personas (bmad-agent/personas/) - Self-improving AI agent definitions:
- Analyst (Mary) - Research, brainstorming, project briefs + methodology analysis
- PM (John) - Product requirements documents (PRDs) + process optimization
- Architect (Fred) - System architecture + methodology architecture improvements
- Design Architect (Jane) - UI/UX specs + workflow design improvements
- PO (Sarah) - Validates cross-artifact coherence + methodology validation
- Frontend Dev (Ellyn) - NextJS/React/TypeScript + development process improvements
- Full Stack Dev (James) - General development + implementation optimization
- Platform Engineer (Alex) - Infrastructure + methodology infrastructure
- Scrum Master (Bob) - Story generation + process improvement facilitation
Tasks (bmad-agent/tasks/) - Self-optimizing executable instruction sets
Templates (bmad-agent/templates/) - Adaptive document templates that improve with use
Checklists (bmad-agent/checklists/) - Evolving quality control and validation criteria
Evolution Tracking (docs/methodology-evolution/) - History and metrics of improvements

Key Design Patterns

Adaptive Agent Architecture: Each persona learns and improves its own capabilities
Self-Optimizing Workflows: Processes automatically suggest improvements based on outcomes
Version-Controlled Methodology: Git tracks methodology evolution with rollback capability
Approval-Gated Evolution: Major changes require user confirmation before implementation
Metric-Driven Improvement: Effectiveness measurements guide optimization decisions

Working with Self-Improving BMAD Agents

Milestone-Based Git Workflow

Each major phase completion triggers:

Retrospective Analysis: What worked well? What needs improvement?
Improvement Identification: Specific changes to methodology/personas/tasks
Approval Process: Present changes to user for confirmation
Implementation: Apply approved improvements
Git Commit: Version control milestone with descriptive commit message

Commands for Self-Improvement

git log --oneline --grep="Milestone" - View methodology evolution history
git checkout <milestone-hash> - Rollback to previous methodology version
git diff HEAD~1 bmad-agent/ - Compare methodology changes between versions

Configuration Files

ide-bmad-orchestrator.cfg.md - Self-updating agent configurations
web-bmad-orchestrator-agent.cfg.md - Adaptive web platform configurations
docs/methodology-evolution/improvement-log.md - Track all methodology changes

Enhanced Template Syntax

Templates now include self-improvement capabilities:

{{placeholder}} - Variable substitution
[[LLM: instructions]] - Hidden AI guidance that can be optimized
<<REPEAT>>...<<END-REPEAT>> - Iterative sections with improvement tracking
^^CONDITION^^...^^END-CONDITION^^ - Conditional content based on effectiveness metrics
@{example}...@{end} - Reference examples that update based on successful patterns
[[IMPROVE: suggestion]] - Methodology improvement suggestions

Self-Evolving Workflow

Ideation: Analyst creates project briefs + identifies research process improvements
Requirements: PM transforms briefs into PRDs + optimizes requirements gathering
Design: Design Architect creates UI/UX specs + refines design processes
Architecture: Architect designs system structure + improves technical workflows
Validation: PO ensures alignment + validates methodology improvements
Implementation: SM generates stories + optimizes development processes
Retrospective: All agents contribute to methodology evolution analysis

Development Protocol

Milestone Commits

Each significant phase generates a commit with format: "Milestone X: [Phase Name] - [Key Improvements]"

Improvement Process

Identify: What could work better?
Analyze: Why didn't it work optimally?
Propose: Specific improvements to methodology
Approve: Get user confirmation for major changes
Implement: Apply improvements to personas/tasks/templates
Track: Document changes in evolution log
Commit: Version control the improvements

Rollback Procedure

If methodology changes prove problematic:

git log --oneline --grep="Milestone" - Find last good milestone
git checkout <hash> -- bmad-agent/ - Restore methodology files
git commit -m "Rollback: Restore methodology to Milestone X"

Effectiveness Metrics

Velocity: Time from idea to working implementation
Quality: Reduction in bugs, rework, and user complaints
Satisfaction: User feedback on methodology effectiveness
Learning Rate: Speed of methodology improvement over time

Development Notes

Always ask for approval before making major methodology changes
Document all improvements in the evolution log
Commit at milestones to maintain version control checkpoints
Measure effectiveness to guide optimization decisions
Embrace experimentation while maintaining rollback capability

This framework represents the first self-evolving AI development methodology, continuously optimizing itself through real-world application and user feedback.

6.5 KiB Raw Blame History