17 - BMAD Method: Sviluppo Agile AI-Driven

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.md

# 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 sovrapposta

# 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 agenti

# 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à

# 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 Agent

# 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 stakeholder

# 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.md

# 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.md

# 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 formali

┌─────────────────────────────────────────────────────────────────┐
│                      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  │
                    └──────────────┘

# 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
EOF

# .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.md

# 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-permissions

# 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 check

# .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.

// 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,
    };
  }
}