BMAD Method: Sviluppo Agile AI-Driven
Il BMAD Method (Breakthrough Method for Agile AI-Driven Development) e una metodologia rivoluzionaria che affronta uno dei problemi più critici dello sviluppo software assistito da AI: come gestire progetti complessi che superano le capacità di una singola sessione di conversazione? La risposta sta in un concetto tanto semplice quanto potente: il Document Sharding, ovvero la frammentazione della documentazione di progetto in pezzi atomici ottimizzati per il consumo da parte di agenti AI.
BMAD non è semplicemente un set di prompt o una collezione di template: è un framework completo che include 21 agenti specializzati, oltre 50 workflow guidati, template per ogni fase di progetto e un sistema di intelligence adattiva che scala la complessità in base alla dimensione del progetto. In questo articolo esploreremo ogni aspetto del metodo, dalla teoria alla pratica, con esempi concreti di implementazione.
Cosa Imparerai
- Comprendere il problema del context overflow e come BMAD lo risolve
- Padroneggiare il concetto di Document Sharding e la sua importanza
- Conoscere i 21 agenti specializzati e i loro ruoli
- Utilizzare i 50+ workflow guidati per ogni fase del progetto
- Applicare l'intelligence scale-adaptive di BMAD
- Configurare BMAD nel proprio progetto con Claude Code
- Confrontare BMAD con metodologie tradizionali
- Evitare i comuni errori di implementazione
Panoramica della Serie
| # | Articolo | Focus |
|---|---|---|
| 1 | Claude come Partner Tecnico | Setup e primi passi |
| 2 | Contesto e Setup del Progetto | CLAUDE.md e configurazione |
| 3 | Ideazione e Requisiti | MVP e user personas |
| 4 | Architettura Backend e Frontend | Spring Boot e Angular |
| 5 | Struttura del Codice | Organizzazione e convenzioni |
| 6 | Prompt Engineering Avanzato | Tecniche avanzate |
| 7 | Testing e qualità | Strategie e generazione test |
| 8 | Documentazione Professionale | README, API, ADR |
| 9 | Deploy e DevOps | Docker, CI/CD, monitoring |
| 10 | Evoluzione e Manutenzione | Refactoring e scalabilità |
| 11 | Integrazione Progetto Reale | Claude Code in produzione |
| 12 | CLI Avanzata e Comandi | Padronanza della riga di comando |
| 13 | Custom Slash Commands e Skills | Estendere Claude Code |
| 14 | Sub-Agenti e Delegazione | Orchestrare agenti specializzati |
| 15 | Hooks: Automazione Event-Driven | Automazione basata su eventi |
| 16 | Ralph Wiggum: Loop AI Autonomi | Sviluppo autonomo iterativo |
| 17 | BMAD Method: Sviluppo Agile AI (sei qui) | Metodologia agile AI-driven |
| 18 | Orchestrazione Multi-Agente | Coordinare team di agenti |
| 19 | Collaborazione e Coworking AI | Lavorare insieme a Claude |
| 20 | Sicurezza e Permessi | Proteggere il workflow |
| 21 | Monitoring e Ottimizzazione | Metriche e performance |
1. Il Problema del Context Overflow
Per comprendere perchè BMAD esiste, bisogna capire il problema fondamentale che risolve. I modelli linguistici come Claude hanno una finestra di contesto limitata: la quantità massima di testo che possono "ricordare" durante una conversazione. Anche i modelli più avanzati con finestre da 200K token hanno limiti pratici significativi quando si tratta di gestire progetti software complessi.
Un progetto enterprise tipico include centinaia di file sorgente, decine di documenti di specifica, architettura, test plan, deployment guide, e documentazione API. Inserire tutto questo in una singola conversazione è impossibile, e anche inserirne parti significative degrada la qualità delle risposte perchè il modello deve "diluire" la sua attenzione su troppo materiale.
Il Problema in Numeri
| Elemento | Dimensione Tipica | % Context Window (200K) |
|---|---|---|
| Specifica requisiti completa | 20K-50K token | 10-25% |
| Documento architettura | 15K-30K token | 7-15% |
| Schema database (20 tabelle) | 5K-10K token | 2-5% |
| API documentation | 30K-80K token | 15-40% |
| Test plan completo | 10K-25K token | 5-12% |
| Codebase esistente (100 file) | 100K-500K token | 50-250% |
| Totale tipico progetto medio | 200K-700K token | 100-350% |
Come si vede, anche un progetto di media complessità genera più documentazione di quanta ne possa contenere una singola finestra di contesto. Le soluzioni tradizionali a questo problema sono insoddisfacenti:
- Riassumere tutto: Si perde dettaglio critico per l'implementazione
- Sessioni separate: Si perde coerenza tra le diverse parti del progetto
- Copia-incolla selettivo: Richiede gestione manuale costante e soggetta a errori
- RAG (Retrieval Augmented Generation): Buono per domande puntuali, ma insufficiente per task di implementazione complessi
2. Document Sharding: L'Innovazione Chiave
Il Document Sharding è il concetto centrale di BMAD. L'idea è semplice ma profonda: anziché creare documentazione monolitica che tenta di descrivere tutto il progetto in documenti lunghi, BMAD suddivide ogni aspetto del progetto in frammenti atomici, auto-contenuti e interconnessi che possono essere forniti all'agente AI esattamente quando servono, senza spreco di contesto.
Principi del Document Sharding
- Atomicita: Ogni shard descrive un singolo concetto, componente o decisione. Non è necessario leggere altri shard per comprenderlo completamente.
- Auto-contenimento: Ogni shard include tutto il contesto necessario per il suo utilizzo. Se un shard descrive un'API endpoint, contiene schema di input/output, validazione, errori possibili e dipendenze.
- Interconnessione: Gli shard contengono riferimenti espliciti ad altri shard correlati, permettendo all'agente di navigare la documentazione come un grafo.
- Dimensione ottimale: Ogni shard è dimensionato per occupare una porzione gestibile della finestra di contesto (tipicamente 2K-8K token), lasciando spazio per il ragionamento e la generazione di codice.
Struttura Directory BMAD
bmad-agent/
├── agents/ # 21 agenti specializzati
│ ├── pm-agent.md # Product Manager
│ ├── architect-agent.md # System Architect
│ ├── developer-agent.md # Developer
│ ├── ux-agent.md # UX Designer
│ ├── sm-agent.md # Scrum Master
│ ├── qa-agent.md # Quality Assurance
│ ├── devops-agent.md # DevOps Engineer
│ ├── data-agent.md # Data Engineer
│ ├── security-agent.md # Security Specialist
│ ├── tech-writer-agent.md # Technical Writer
│ ├── analyst-agent.md # Business Analyst
│ ├── design-agent.md # System Designer
│ ├── frontend-agent.md # Frontend Specialist
│ ├── backend-agent.md # Backend Specialist
│ ├── mobile-agent.md # Mobile Developer
│ ├── ml-agent.md # ML Engineer
│ ├── performance-agent.md # Performance Engineer
│ ├── migration-agent.md # Migration Specialist
│ ├── review-agent.md # Code Reviewer
│ ├── release-agent.md # Release Manager
│ └── orchestrator-agent.md # Agent Orchestrator
│
├── tasks/ # 50+ workflow guidati
│ ├── analysis/
│ │ ├── gather-requirements.md
│ │ ├── competitive-analysis.md
│ │ ├── user-persona-creation.md
│ │ └── risk-assessment.md
│ ├── planning/
│ │ ├── create-roadmap.md
│ │ ├── sprint-planning.md
│ │ ├── resource-allocation.md
│ │ └── milestone-definition.md
│ ├── architecture/
│ │ ├── system-design.md
│ │ ├── api-contract.md
│ │ ├── database-schema.md
│ │ └── integration-patterns.md
│ ├── implementation/
│ │ ├── feature-implementation.md
│ │ ├── code-generation.md
│ │ ├── refactoring-guide.md
│ │ └── testing-strategy.md
│ └── delivery/
│ ├── deployment-plan.md
│ ├── release-checklist.md
│ ├── monitoring-setup.md
│ └── post-mortem.md
│
├── templates/ # Template riutilizzabili
│ ├── prd-template.md # Product Requirements Document
│ ├── adr-template.md # Architecture Decision Record
│ ├── epic-template.md # Epic/Feature template
│ ├── story-template.md # User Story template
│ └── test-plan-template.md # Test Plan template
│
├── personas/ # Configurazioni persona
│ ├── startup-mode.md # Modalità startup lean
│ ├── enterprise-mode.md # Modalità enterprise rigorosa
│ └── solo-dev-mode.md # Modalità sviluppatore singolo
│
└── checklists/ # Checklist di qualità
├── code-review.md
├── security-audit.md
├── accessibility.md
└── performance.mdEsempio di Shard: API Endpoint
# API Shard: Crea Prenotazione
## Endpoint
POST /api/v1/bookings
## Descrizione
Crea una nuova prenotazione per un utente registrato.
## Autenticazione
Bearer JWT Token (ruoli: USER, ADMIN)
## Input Schema
{
"roomId": "string (UUID, obbligatorio)",
"checkIn": "string (ISO 8601, obbligatorio)",
"checkOut": "string (ISO 8601, obbligatorio)",
"guests": "number (1-10, obbligatorio)",
"notes": "string (max 500 char, opzionale)"
}
## Validazioni
1. checkOut deve essere successivo a checkIn
2. La durata minima è 1 notte
3. La durata massima è 30 notti
4. La room deve esistere e essere disponibile nel periodo
5. L'utente non deve avere prenotazioni sovrapposte
## Risposte
- 201 Created: prenotazione creata con successo
- 400 Bad Request: validazione fallita
- 401 Unauthorized: token mancante o invalido
- 404 Not Found: room non trovata
- 409 Conflict: room non disponibile nel periodo
## Dipendenze
- Shard: room-availability-service
- Shard: user-validation-middleware
- Shard: booking-entity-schema
## Test Richiesti
- Happy path con dati validi
- Validazione date (checkOut prima di checkIn)
- Room non disponibile (conflict)
- Utente non autenticato
- Prenotazione sovrappostaQuesto shard contiene tutto ciò che serve per implementare l'endpoint: schema di input, validazioni, risposte, dipendenze e test richiesti. Un agente AI che riceve questo shard ha il contesto necessario per produrre un'implementazione completa senza bisogno di leggere l'intera documentazione del progetto.
3. I 21 Agenti Specializzati BMAD
Il cuore operativo di BMAD è composto da 21 agenti specializzati, ciascuno configurato con competenze, prompt di sistema e workflow specifici per un aspetto dello sviluppo software. Questi agenti non sono entità indipendenti ma configurazioni di Claude Code che attivano expertise specifica attraverso prompt di sistema e accesso selettivo agli shard di documentazione.
Mappa degli Agenti per Fase di Progetto
| Fase | Agenti Coinvolti | Responsabilità |
|---|---|---|
| Analisi | PM Agent, Analyst, UX Agent | Requisiti, personas, analisi competitiva |
| Pianificazione | SM Agent, PM Agent | Roadmap, sprint planning, risorse |
| Architettura | Architect, Designer, Security | System design, API contract, sicurezza |
| Implementazione | Developer, Frontend, Backend, Mobile, ML | Codice, test, integrazione |
| qualità | QA Agent, Review Agent, Performance | Testing, code review, performance |
| Delivery | DevOps, Release, Tech Writer | Deploy, documentazione, release notes |
| Coordinamento | Orchestrator, Data Agent, Migration | Orchestrazione, dati, migrazione |
Profilo Agente: PM Agent (Product Manager)
Il PM Agent è responsabile della raccolta e gestione dei requisiti di prodotto. È il primo agente ad essere invocato nella maggior parte dei progetti e produce gli artefatti fondamentali che guidano tutto il resto dello sviluppo.
# PM Agent - Product Manager
## Identita
Sei un Product Manager esperto con 15+ anni di esperienza in prodotti
software B2B e B2C. Eccelli nella raccolta dei requisiti, nell'analisi
dei bisogni degli stakeholder e nella definizione di roadmap strategiche.
## Competenze Specifiche
- Tecniche di elicitazione dei requisiti (interviste, workshop, survey)
- Framework di prioritizzazione (MoSCoW, RICE, Kano)
- Creazione di Product Requirements Document (PRD)
- Definizione di metriche di successo (KPI, OKR)
- Analisi competitiva e posizionamento
## Workflow Disponibili
1. gather-requirements: Raccolta strutturata dei requisiti
2. competitive-analysis: Analisi del panorama competitivo
3. user-persona-creation: Creazione di user personas dettagliate
4. prd-creation: Stesura del Product Requirements Document
5. roadmap-planning: Pianificazione della roadmap di prodotto
## Template
- prd-template.md: Template per il documento requisiti
- epic-template.md: Template per epic/feature
- story-template.md: Template per user stories
## Regole di Interazione
1. Fai sempre domande chiarificatrici prima di procedere
2. Quantifica i requisiti quando possibile (numeri, metriche, SLA)
3. Identifica e documenta i rischi per ogni requisito critico
4. Distingui sempre tra MUST, SHOULD, COULD e WON'T (MoSCoW)
5. Produci artefatti in formato shard per il consumo da parte di altri agentiProfilo Agente: Architect Agent
L'Architect Agent trasforma i requisiti del PM Agent in decisioni architetturali concrete. Produce shard di architettura che guidano l'implementazione, definendo tecnologie, pattern, interfacce e trade-off.
# Architect Agent - System Architect
## Identita
Sei un System Architect senior con esperienza in architetture distribuite,
microservizi, event-driven e serverless. Bilanci pragmatismo e rigore
tecnico nelle decisioni architetturali.
## Competenze Specifiche
- Design di architetture scalabili (verticale e orizzontale)
- Pattern architetturali (DDD, CQRS, Event Sourcing, Hexagonal)
- API Design (REST, GraphQL, gRPC)
- Database selection (SQL vs NoSQL vs NewSQL)
- Trade-off analysis (CAP theorem, performance vs consistency)
- Security by design
## Output Attesi
Per ogni decisione architetturale, produrre:
1. ADR (Architecture Decision Record) in formato shard
2. Diagramma componenti (descrizione testuale per mermaid)
3. API contract shard per ogni interfaccia
4. Database schema shard
5. Lista di vincoli e assunzioni
## Regole
1. Ogni decisione deve avere un ADR con alternative considerate
2. Preferire soluzioni semplici a soluzioni eleganti
3. Documentare i trade-off in modo esplicito
4. Definire interfacce prima delle implementazioni
5. Considerare sempre scalabilità, sicurezza e manutenibilitàProfilo Agente: Developer Agent
Il Developer Agent è l'agente che produce codice effettivo. Consuma gli shard prodotti dal PM Agent e dall'Architect Agent per implementare feature, scrivere test e produrre codice che rispetti i vincoli architetturali.
# Developer Agent - Full-Stack Developer
## Identita
Sei uno sviluppatore full-stack esperto con padronanza di TypeScript,
Java, Python e Go. Scrivi codice pulito, testabile e manutenibile.
Segui le best practice della community e i principi SOLID.
## Competenze Specifiche
- TypeScript/JavaScript (Node.js, Angular, React, Next.js)
- Java (Spring Boot, Hibernate)
- Python (FastAPI, Django)
- Database (PostgreSQL, MongoDB, Redis)
- Testing (Jest, JUnit, pytest)
- Clean Code e Design Patterns
## Workflow
1. Leggi lo shard della feature/endpoint da implementare
2. Leggi lo shard dell'architettura rilevante
3. Implementa il codice seguendo le convenzioni del progetto
4. Scrivi test unitari con coverage > 80%
5. Esegui lint e type check
6. Aggiorna il STATUS.md del modulo
## Regole
1. Mai usare `any` in TypeScript senza commento giustificativo
2. Ogni funzione pubblica deve avere JSDoc/JavaDoc
3. Error handling esplicito, mai catch vuoti
4. Seguire il naming convention definito in CLAUDE.md
5. Rispettare le interfacce definite dall'Architect AgentProfilo Agente: QA Agent
Il QA Agent è responsabile della strategia di testing e della validazione della qualità del codice. Opera in parallelo al Developer Agent, producendo test case, eseguendo analisi di copertura e identificando gap nella qualità dell'implementazione.
Profilo Agente: Scrum Master Agent
Lo SM Agent coordina il processo di sviluppo, gestisce la pianificazione degli sprint, facilità le retrospettive e rimuove gli impedimenti. Nel contesto BMAD, è responsabile della creazione e manutenzione del backlog di shard e della prioritizzazione dei task.
Gli Altri Agenti
Panoramica Completa dei 21 Agenti
| # | Agente | Ruolo | Output Principale |
|---|---|---|---|
| 1 | PM Agent | Product Manager | PRD, User Stories, Backlog |
| 2 | Architect Agent | System Architect | ADR, API Contract, Schema |
| 3 | Developer Agent | Full-Stack Developer | Codice, Unit Test |
| 4 | UX Agent | UX Designer | Wireframe, User Flows |
| 5 | SM Agent | Scrum Master | Sprint Plan, Retrospective |
| 6 | QA Agent | Quality Assurance | Test Plan, Bug Report |
| 7 | DevOps Agent | DevOps Engineer | Pipeline, Infrastructure |
| 8 | Data Agent | Data Engineer | Schema, Migration, ETL |
| 9 | Security Agent | Security Specialist | Threat Model, Audit |
| 10 | Tech Writer Agent | Technical Writer | Docs, API Guide, README |
| 11 | Analyst Agent | Business Analyst | Analysis, Metrics, KPI |
| 12 | Designer Agent | System Designer | Component Design, Patterns |
| 13 | Frontend Agent | Frontend Specialist | UI Components, State |
| 14 | Backend Agent | Backend Specialist | Services, APIs, DB |
| 15 | Mobile Agent | Mobile Developer | App, Native Features |
| 16 | ML Agent | ML Engineer | Models, Pipelines, Eval |
| 17 | Performance Agent | Performance Engineer | Benchmarks, Optimization |
| 18 | Migration Agent | Migration Specialist | Migration Plan, Scripts |
| 19 | Review Agent | Code Reviewer | Review Notes, Suggestions |
| 20 | Release Agent | Release Manager | Release Notes, Changelog |
| 21 | Orchestrator Agent | Agent Coordinator | Task Routing, Sync |
4. I 50+ Workflow Guidati
Ogni agente BMAD dispone di workflow predefiniti: sequenze strutturate di passi che guidano l'agente attraverso task complessi in modo sistematico e riproducibile. I workflow eliminano l'ambiguità e garantiscono che ogni aspetto di un task venga affrontato, indipendentemente dalla complessità.
Workflow per Fase: Analisi
I workflow della fase di analisi sono progettati per raccogliere e strutturare le informazioni necessarie prima di qualsiasi attivita di design o implementazione.
# Workflow: Raccolta Requisiti Strutturata
## Prerequisiti
- Accesso al cliente/stakeholder (o documento brief)
- Template PRD (prd-template.md)
- Checklist domande standard
## Passi
### Step 1: Comprensione del Contesto
- Qual è il problema che il prodotto risolve?
- Chi sono gli utenti target?
- Quali sono i vincoli di business (budget, timeline, compliance)?
- Esistono sistemi legacy da integrare?
### Step 2: Elicitazione Funzionale
Per ogni macro-funzionalità identificata:
1. Definisci il caso d'uso principale (happy path)
2. Identifica i casi limite (edge cases)
3. Definisci i criteri di accettazione (Given/When/Then)
4. Classifica la priorità (MoSCoW)
5. Stima la complessità relativa (S/M/L/XL)
### Step 3: Requisiti Non-Funzionali
- Performance: tempi di risposta attesi (p50, p95, p99)
- Scalabilità: utenti concorrenti previsti (ora, 6 mesi, 1 anno)
- Disponibilità: SLA target (99.9%? 99.99%?)
- Sicurezza: compliance requirements (GDPR, SOC2, PCI-DSS)
- Accessibilita: WCAG livello target (A, AA, AAA)
### Step 4: Produzione Artefatti
Genera i seguenti shard:
1. shard-prd-overview.md (panoramica progetto)
2. shard-personas.md (user personas)
3. shard-requirements-functional.md (requisiti funzionali)
4. shard-requirements-nonfunctional.md (requisiti non-funzionali)
5. shard-constraints.md (vincoli e assunzioni)
6. shard-risks.md (rischi identificati)
### Step 5: Validazione
- Rivedi ogni shard per completezza
- Verifica che ogni requisito sia testabile
- Conferma le priorità con lo stakeholderWorkflow per Fase: Architettura
# Workflow: System Design
## Input Richiesti
- shard-prd-overview.md
- shard-requirements-functional.md
- shard-requirements-nonfunctional.md
- shard-constraints.md
## Passi
### Step 1: Identificazione Componenti
Leggi i requisiti funzionali e identifica:
- Bounded contexts (DDD)
- Servizi principali
- Integrazioni esterne
- Layer di persistenza
### Step 2: Scelta Pattern Architetturale
Valuta e documenta in ADR:
- Monolith vs Microservizi vs Modular Monolith
- Sync vs Async communication
- SQL vs NoSQL per ogni bounded context
- Hosting: Cloud vs On-premise vs Hybrid
### Step 3: Design delle Interfacce
Per ogni servizio/modulo:
1. Definisci API contract (OpenAPI/Protobuf)
2. Definisci event schema (per comunicazione async)
3. Definisci database schema
4. Documenta in shard separati
### Step 4: Security Design
- Autenticazione: metodo e flusso
- Autorizzazione: modello (RBAC, ABAC, ReBAC)
- Encryption: at rest e in transit
- Threat model (STRIDE)
### Step 5: Produzione Shard Architetturali
1. shard-architecture-overview.md
2. shard-adr-{decisione}.md (uno per ogni decisione)
3. shard-api-{servizio}.md (uno per ogni API)
4. shard-db-{context}.md (schema per ogni bounded context)
5. shard-security-model.mdWorkflow per Fase: Implementazione
# Workflow: Implementazione Feature
## Input Richiesti
- shard-api-{endpoint}.md (contract dell'endpoint)
- shard-db-{context}.md (schema database)
- shard-architecture-overview.md (vincoli architetturali)
## Passi
### Step 1: Analisi dello Shard
1. Leggi lo shard dell'endpoint/feature da implementare
2. Identifica dipendenze da altri shard
3. Verifica che tutte le interfacce siano definite
### Step 2: Scaffolding
1. Crea i file necessari seguendo la struttura del progetto
2. Definisci interfacce TypeScript/Java per i tipi
3. Crea stub per i metodi principali
### Step 3: Implementazione TDD
Per ogni funzionalità dello shard:
1. Scrivi il test che verifica il comportamento atteso
2. Implementa il codice minimo per far passare il test
3. Refactora mantenendo i test verdi
4. Ripeti per la prossima funzionalità
### Step 4: Integrazione
1. Verifica compatibilità con interfacce definite
2. Esegui test di integrazione
3. Verifica compliance con lo shard di architettura
### Step 5: qualità
1. Esegui linter e type checker
2. Verifica coverage > 80%
3. Documenta API con JSDoc/JavaDoc
4. Aggiorna STATUS.md5. Scale-Adaptive Intelligence
Una delle innovazioni più significative di BMAD è la Scale-Adaptive Intelligence: la capacità di adattare automaticamente il livello di complessità, formalità e rigore del processo in base alla dimensione e alla natura del progetto. Non tutti i progetti hanno bisogno di 21 agenti e 50 workflow; un side project personale richiede un approccio radicalmente diverso da un sistema enterprise.
Livelli di Scala BMAD
| Livello | Tipo Progetto | Agenti Attivi | Workflow | Formalità |
|---|---|---|---|---|
| Nano | Script, utility, tool singolo | 1 (Developer) | Minimal | Nessuna documentazione formale |
| Micro | Side project, prototype, MVP | 3 (PM, Dev, QA) | Essenziali | README + test di base |
| Small | Startup, team piccolo (2-5) | 6 (PM, Arch, Dev, QA, DevOps, Writer) | Standard | PRD + ADR + API docs |
| Medium | Prodotto aziendale, team medio (5-15) | 12 | Completi | Full documentation + compliance |
| Large | Enterprise, team grande (15+) | Tutti i 21 | Tutti + custom | Full formal + audit trail |
Modalità Solo Developer
Per sviluppatori singoli, BMAD offre la modalità Solo Dev che condensa le responsabilità di più agenti in un workflow snello ma efficace:
# BMAD Solo Developer Mode
## Agenti Attivi
1. PM Agent (leggero): solo user stories e criteri di accettazione
2. Developer Agent: implementazione + testing
3. DevOps Agent: solo deployment configuration
## Workflow Semplificato
1. Definisci il problema in 1 paragrafo
2. Lista le feature principali (max 10)
3. Per ogni feature, scrivi 1 user story con criteri di accettazione
4. Implementa con TDD
5. Deploy
## Shard Minimi
- overview.md: cosa fa il progetto, per chi, perchè
- features.md: lista feature con priorità
- tech-stack.md: tecnologie scelte con motivazione
- Per ogni feature: 1 shard con interface + test criteria
## Regole
- Niente ADR formali per decisioni ovvie
- Test unitari solo per logica di business complessa
- Documentazione inline (JSDoc) invece di documenti separati
- Deploy continuo senza release formali6. Le 4 Fasi del Workflow BMAD
Indipendentemente dalla scala del progetto, BMAD organizza il processo di sviluppo in quattro fasi distinte, ciascuna con obiettivi, agenti responsabili e artefatti di output specifici. Le fasi sono sequenziali per la prima esecuzione ma diventano iterative una volta che il progetto e avviato.
Fase 1: Analisi
La fase di analisi è dedicata alla comprensione profonda del problema da risolvere. Gli agenti PM, Analyst e UX collaborano per raccogliere requisiti, definire personas, analizzare il panorama competitivo e identificare vincoli e rischi.
Agenti coinvolti: PM Agent, Analyst Agent, UX Agent
Artefatti prodotti: PRD (Product Requirements Document), User Personas, Analisi Competitiva, Risk Assessment, Requisiti Funzionali e Non-Funzionali sotto forma di shard atomici.
L'output della fase di analisi è un insieme di shard che descrive completamente cosa deve essere costruito e per chi, senza ancora definire come. Questa separazione è fondamentale per evitare decisioni premature di implementazione.
Fase 2: Pianificazione
La fase di pianificazione trasforma i requisiti in un piano di lavoro concreto. Lo Scrum Master Agent e il PM Agent collaborano per definire la roadmap, organizzare il backlog, pianificare gli sprint e allocare le risorse (agenti) ai task.
Agenti coinvolti: SM Agent, PM Agent
Artefatti prodotti: Roadmap di progetto, Sprint Backlog, Milestone Definition, Resource Allocation Matrix. Ogni task nel backlog è associato a uno o più shard di requisiti e a uno o più agenti responsabili dell'implementazione.
Fase 3: Architettura
La fase di architettura definisce come il sistema sarà costruito. L'Architect Agent e il Designer Agent analizzano i requisiti e producono decisioni architetturali documentate, API contract, schema database e modelli di sicurezza.
Agenti coinvolti: Architect Agent, Designer Agent, Security Agent
Artefatti prodotti: Architecture Overview, ADR (Architecture Decision Records), API Contracts, Database Schemas, Security Model, Integration Patterns. Ogni decisione è documentata con le alternative considerate e le motivazioni della scelta, creando un audit trail completo delle decisioni progettuali.
Fase 4: Implementazione
La fase di implementazione è dove il codice viene scritto. I Developer Agent (con le varianti Frontend, Backend, Mobile) consumano gli shard prodotti nelle fasi precedenti per implementare feature, scrivere test e produrre codice pronto per il deploy. In parallelo, il QA Agent valida la qualità e il DevOps Agent prepara l'infrastruttura.
Agenti coinvolti: Developer Agent, Frontend Agent, Backend Agent, QA Agent, DevOps Agent, Tech Writer Agent
Artefatti prodotti: Codice sorgente, Test suite, Documentazione API, Pipeline CI/CD, Release Notes, User Guide.
┌─────────────────────────────────────────────────────────────────┐
│ FASE 1: ANALISI │
│ PM Agent ──→ Analyst Agent ──→ UX Agent │
│ Output: PRD shards, Personas, Requirements, Risks │
└──────────────────────────┬──────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ FASE 2: PIANIFICAZIONE │
│ SM Agent ──→ PM Agent │
│ Output: Roadmap, Sprint Backlog, Milestones │
└──────────────────────────┬──────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ FASE 3: ARCHITETTURA │
│ Architect Agent ──→ Designer Agent ──→ Security Agent │
│ Output: ADR shards, API contracts, DB schemas, Security model │
└──────────────────────────┬──────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ FASE 4: IMPLEMENTAZIONE │
│ Developer ──→ QA ──→ DevOps ──→ Tech Writer │
│ Output: Code, Tests, Pipeline, Documentation │
└──────────────────────────┬──────────────────────────────────────┘
│
▼
┌──────────────┐
│ DELIVERY │
│ Release + │
│ Monitoring │
└──────────────┘7. Confronto con Metodologie Tradizionali
BMAD non nasce nel vuoto: si posiziona all'intersezione tra le metodologie agili tradizionali e le capacità emergenti degli agenti AI. Comprendere le differenze e le complementarità con approcci consolidati aiuta a valutare quando e come applicare BMAD.
BMAD vs Metodologie Tradizionali
| Aspetto | Scrum | Kanban | BMAD |
|---|---|---|---|
| Iterazioni | Sprint fissi (2-4 settimane) | Flusso continuo | Loop adattivi (minuti-ore) |
| Ruoli | 3 ruoli umani | Nessun ruolo fisso | 21 agenti AI configurabili |
| Documentazione | User stories, backlog | Card sul board | Shard atomici interconnessi |
| Feedback | Fine sprint (retrospettiva) | Continuo (metriche flusso) | Ogni iterazione (test automatici) |
| Scalabilità | SAFe, LeSS per large-scale | Scalabile nativamente | Scale-adaptive intelligence |
| Costo umano | Team completo richiesto | Team flessibile | 1 operatore + costo API |
| Velocita | Settimane per feature | Giorni per feature | Ore per feature (con loop) |
E' importante sottolineare che BMAD non sostituisce le metodologie agili ma le potenzia. Un team che utilizza Scrum può adottare BMAD per accelerare la fase di implementazione di ogni sprint, mantenendo le cerimonie Scrum per il coordinamento umano e utilizzando gli agenti BMAD per l'esecuzione dei task individuali.
8. Configurare BMAD nel Proprio Progetto
L'integrazione di BMAD in un progetto esistente richiede una configurazione iniziale che prepara la struttura di directory, i file di configurazione e gli shard di base. Il processo è progettato per essere incrementale: si può iniziare con la configurazione minima e aggiungere complessità man mano che il progetto cresce.
Step 1: Installazione
# Clona il template BMAD
git clone https://github.com/bmad-method/bmad-agent.git .bmad
# Crea la struttura di base nel progetto
mkdir -p .bmad/{agents,tasks,templates,shards}
# Copia gli agenti necessari per il livello di scala scelto
# Esempio: livello "Small" (6 agenti)
cp .bmad/agents/{pm-agent,architect-agent,developer-agent,qa-agent,devops-agent,tech-writer-agent}.md \
.bmad/agents/
# Copia i workflow rilevanti
cp -r .bmad/tasks/{analysis,architecture,implementation} .bmad/tasks/
# Configura CLAUDE.md per integrare BMAD
cat >> CLAUDE.md << 'EOF'
## BMAD Configuration
- Agents directory: .bmad/agents/
- Tasks directory: .bmad/tasks/
- Shards directory: .bmad/shards/
- Active scale: Small (6 agents)
When starting a new task, always:
1. Check which shard is relevant in .bmad/shards/
2. Follow the appropriate workflow in .bmad/tasks/
3. Produce output as new shards when generating documentation
EOFStep 2: Creazione degli Shard Iniziali
# .bmad/shards/project-overview.md
# Project Overview Shard
## Nome Progetto
BookingAPI - Sistema di Prenotazioni Online
## Problema
I piccoli hotel e B&B non hanno un sistema di prenotazione
moderno, economico e facile da integrare nei loro siti web.
## Soluzione
API REST + Widget embeddabile per la gestione prenotazioni
con calendario disponibilità, pagamenti e notifiche.
## Stack Tecnologico
- Backend: Node.js + Express + TypeScript
- Database: PostgreSQL
- Cache: Redis
- Auth: JWT + OAuth2
- Deploy: Docker + Railway
## Utenti Target
1. Proprietari di piccoli hotel/B&B (admin)
2. Ospiti che prenotano (utente finale)
3. Sviluppatori che integrano il widget (developer)
## Vincoli
- Budget: $0 infrastruttura (free tier)
- Timeline: MVP in 2 settimane
- Compliance: GDPR per dati utente
- Accessibility: WCAG 2.1 AA
## Shard Correlati
- shard-personas.md
- shard-requirements-functional.md
- shard-architecture-overview.mdStep 3: Invocare un Agente
Una volta configurato, si invoca un agente BMAD fornendo a Claude Code il contesto dell'agente e lo shard rilevante:
# Metodo 1: Prompt diretto con contesto agente
claude "Leggi .bmad/agents/architect-agent.md per assumere il ruolo di architetto.
Poi leggi .bmad/shards/project-overview.md e .bmad/shards/requirements-functional.md.
Segui il workflow in .bmad/tasks/architecture/system-design.md per produrre
il design architetturale. Salva ogni output come shard separato in .bmad/shards/"
# Metodo 2: Slash command personalizzato
# In .claude/commands/bmad-architect.md:
# Assume the Architect Agent role from .bmad/agents/architect-agent.md
# Read relevant shards and produce architecture design shards
/bmad-architect "Design del sistema di prenotazioni"
# Metodo 3: Combinazione con Ralph Wiggum
# PROMPT.md con istruzioni BMAD + loop autonomo
cat PROMPT.md | claude --print --dangerously-skip-permissions9. Best Practice e Errori Comuni
L'adozione di BMAD porta benefici significativi quando applicata correttamente, ma può introdurre complessità non necessaria se utilizzata in modo inappropriato. Questa sezione raccoglie le lezioni apprese dalla community e identifica i pattern di successo e gli anti-pattern da evitare.
Best Practice
- Inizia piccolo: Parti dal livello di scala Micro o Small e aggiungi complessità solo quando serve. E' molto più facile aggiungere agenti e workflow che rimuoverli una volta integrati nel processo.
- Shard prima, codice dopo: Resisti alla tentazione di scrivere codice prima di avere shard chiari. L'investimento nella documentazione strutturata ripaga enormemente nella fase di implementazione.
- Un shard = un concetto: Se uno shard richiede più di 8K token, probabilmente sta cercando di coprire troppi concetti. Suddividilo in shard più piccoli e interconnessi.
- Aggiorna gli shard: Gli shard non sono documenti statici. Quando l'implementazione rivela che un'assunzione era sbagliata, aggiorna lo shard corrispondente per mantenere la coerenza.
- Combina con Ralph Wiggum: Per la fase di implementazione, l'accoppiamento BMAD + Ralph Wiggum è estremamente efficace: BMAD fornisce la struttura e gli shard, Ralph Wiggum esegue l'implementazione iterativa.
Errori Comuni
Anti-Pattern BMAD
| Anti-Pattern | Problema | Soluzione |
|---|---|---|
| Over-engineering | Usare tutti i 21 agenti per un todo-list | Scegliere il livello di scala appropriato |
| Shard monolitici | Shard da 20K+ token che contengono tutto | Suddividere in shard atomici da 2-8K token |
| Shard orfani | Shard senza riferimenti ad altri shard | Ogni shard deve avere una sezione "Shard Correlati" |
| Analisi infinita | Produrre shard senza mai implementare | Definire un time-box per ogni fase |
| Ignorare il feedback | Non aggiornare shard quando l'implementazione diverge | Review e aggiornamento shard a fine sprint |
| Copy-paste agenti | Usare agenti senza personalizzarli per il progetto | Adattare prompt e regole di ogni agente al contesto |
10. Integrazione con Claude Code CLI
BMAD si integra nativamente con Claude Code attraverso diversi meccanismi: CLAUDE.md per il contesto persistente, slash commands per l'invocazione degli agenti, hooks per l'automazione e sub-agenti per l'esecuzione parallela.
CLAUDE.md come Hub BMAD
# CLAUDE.md
## Progetto
BookingAPI - Sistema Prenotazioni Online
## BMAD Configuration
Scale: Small (6 agents active)
### Directory Structure
- `.bmad/agents/` - Agent configurations
- `.bmad/tasks/` - Guided workflows
- `.bmad/shards/` - Project documentation shards
- `.bmad/templates/` - Reusable templates
### Active Agents
1. PM Agent: requirements and product decisions
2. Architect Agent: system design and ADRs
3. Developer Agent: code implementation
4. QA Agent: testing strategy and execution
5. DevOps Agent: deployment and infrastructure
6. Tech Writer Agent: documentation
### Conventions
- Every new feature must start with a shard
- Every architecture decision needs an ADR shard
- Implementation follows TDD within BMAD workflows
- Shards are updated when implementation diverges
### Current Sprint
Read `.bmad/shards/sprint-current.md` for active tasks
## Comandi di Sviluppo
- `npm run dev` - Start development server
- `npm test` - Run test suite
- `npm run build` - Production build
- `npm run lint` - Lint checkSlash Commands per Agenti BMAD
# .claude/commands/bmad-pm.md
# Assume the PM Agent role from .bmad/agents/pm-agent.md
# Gather requirements and produce shards
Read .bmad/agents/pm-agent.md to understand your role.
Then follow the workflow in .bmad/tasks/analysis/gather-requirements.md.
Save all outputs as shards in .bmad/shards/.
Ask clarifying questions before proceeding.
---
# .claude/commands/bmad-architect.md
# Assume the Architect Agent role from .bmad/agents/architect-agent.md
# Design system architecture based on requirement shards
Read .bmad/agents/architect-agent.md to understand your role.
Read all shards in .bmad/shards/ that start with "requirements-".
Follow the workflow in .bmad/tasks/architecture/system-design.md.
Produce architecture shards and ADRs.
---
# .claude/commands/bmad-implement.md
# Assume the Developer Agent role from .bmad/agents/developer-agent.md
# Implement the next feature based on architecture shards
Read .bmad/agents/developer-agent.md to understand your role.
Read .bmad/shards/sprint-current.md to identify the next task.
Read the relevant API and architecture shards.
Follow the workflow in .bmad/tasks/implementation/feature-implementation.md.
Use TDD: write tests first, then implement.11. Caso Pratico: BMAD per un'API di Prenotazioni
Per rendere concreti i concetti presentati, vediamo come BMAD viene applicato alla costruzione di una vera API di prenotazioni per hotel, dalla fase di analisi fino all'implementazione del primo endpoint.
Fase Analisi: Output del PM Agent
Dopo aver invocato il PM Agent con il brief del progetto, vengono prodotti i seguenti shard di requisiti:
- project-overview.md: Contesto, problema, soluzione e vincoli
- personas-hotel-owner.md: Profilo del proprietario di hotel
- personas-guest.md: Profilo dell'ospite che prenota
- requirements-booking-crud.md: Requisiti CRUD prenotazioni
- requirements-availability.md: Requisiti calcolo disponibilità
- requirements-auth.md: Requisiti autenticazione/autorizzazione
- constraints-budget-timeline.md: Vincoli di budget e tempistiche
Fase Architettura: Output dell'Architect Agent
L'Architect Agent consuma gli shard di requisiti e produce le decisioni architetturali:
- architecture-overview.md: Architettura modulare a layer
- adr-001-modular-monolith.md: Decisione di usare un monolite modulare
- adr-002-postgresql.md: Scelta di PostgreSQL come database
- api-bookings.md: Contract completo dell'API prenotazioni
- db-schema-bookings.md: Schema database per il modulo prenotazioni
- security-model.md: JWT + RBAC per l'autenticazione
Fase Implementazione: Il Developer Agent al Lavoro
Il Developer Agent riceve lo shard api-bookings.md e segue il workflow
TDD per implementare il primo endpoint. L'output è codice funzionante con test
completi, prodotto iterativamente attraverso il loop di sviluppo.
// src/bookings/booking.service.ts
// Generato dal Developer Agent seguendo lo shard api-bookings.md
import { Injectable, ConflictException, NotFoundException } from '@nestjs/common';
import { BookingRepository } from './booking.repository';
import { RoomService } from '../rooms/room.service';
import { CreateBookingDto, BookingResponse } from './booking.dto';
@Injectable()
export class BookingService {
constructor(
private readonly bookingRepo: BookingRepository,
private readonly roomService: RoomService,
) {}
/**
* Crea una nuova prenotazione verificando la disponibilità.
* @shard api-bookings.md - POST /api/v1/bookings
*/
async createBooking(
userId: string,
dto: CreateBookingDto,
): Promise<BookingResponse> {
// Verifica esistenza room
const room = await this.roomService.findById(dto.roomId);
if (!room) {
throw new NotFoundException('Room non trovata');
}
// Verifica disponibilità nel periodo
const isAvailable = await this.roomService.checkAvailability(
dto.roomId,
dto.checkIn,
dto.checkOut,
);
if (!isAvailable) {
throw new ConflictException('Room non disponibile nel periodo richiesto');
}
// Crea prenotazione
const booking = await this.bookingRepo.create({
userId,
roomId: dto.roomId,
checkIn: dto.checkIn,
checkOut: dto.checkOut,
guests: dto.guests,
notes: dto.notes,
status: 'CONFIRMED',
});
return this.toResponse(booking);
}
private toResponse(booking: any): BookingResponse {
return {
id: booking.id,
roomId: booking.roomId,
checkIn: booking.checkIn,
checkOut: booking.checkOut,
guests: booking.guests,
status: booking.status,
createdAt: booking.createdAt,
};
}
}Conclusione
Il BMAD Method rappresenta un approccio maturo e sistematico allo sviluppo software assistito da AI. Attraverso il Document Sharding, BMAD risolve il problema fondamentale del context overflow, permettendo di gestire progetti di qualsiasi complessità senza sacrificare la qualità o la coerenza della documentazione e dell'implementazione.
La vera forza di BMAD sta nella sua adattabilita: dalla modalità Solo Dev per side project personali alla configurazione enterprise con tutti i 21 agenti, il framework scala naturalmente con le esigenze del progetto. Combinato con tecniche come il loop Ralph Wiggum per l'implementazione autonoma e gli hooks per l'automazione, BMAD diventa il nucleo di un sistema di sviluppo AI-driven completo ed efficace.
Punti Chiave
- Document Sharding risolve il context overflow: Frammenti atomici e auto-contenuti permettono di gestire progetti complessi
- 21 agenti coprono l'intero ciclo: Dall'analisi dei requisiti al deployment, ogni aspetto ha un agente dedicato
- 50+ workflow eliminano l'ambiguità: Sequenze strutturate garantiscono completezza e riproducibilità
- Scale-adaptive intelligence: Il framework si adatta dalla scala Nano alla Large senza over-engineering
- 4 fasi iterative: Analisi, Pianificazione, Architettura e Implementazione in un ciclo continuo
- Complementare alle metodologie agili: BMAD potenzia Scrum e Kanban, non li sostituisce
- Integrazione nativa con Claude Code: CLAUDE.md, slash commands e hooks per un workflow fluido
Nel prossimo articolo esploreremo l'Orchestrazione Multi-Agente: come coordinare più istanze di Claude Code che lavorano simultaneamente su aspetti diversi di un progetto, gestendo la sincronizzazione, la risoluzione dei conflitti e la convergenza verso un obiettivo comune.