Integrare Claude Code in un Progetto Reale: Play The Event
Nei primi 10 articoli di questa serie abbiamo esplorato Claude come partner tecnico, dalla configurazione iniziale fino al deploy e alla manutenzione. Ora è il momento di vedere tutto questo applicato a un progetto reale di produzione: Play The Event, una piattaforma enterprise multi-stack con architettura DDD, Hexagonal e CQRS.
In questo articolo condivido l'esperienza concreta di integrazione di Claude Code nel workflow quotidiano di sviluppo, mostrando come trasforma radicalmente la produttività su un progetto con backend Java/Spring Boot, frontend Angular 19 e analytics Python/FastAPI.
Cosa Imparerai
- Configurare CLAUDE.md come file di istruzioni centralizzato
- Creare slash commands personalizzati per task ripetitivi
- Applicare un workflow di sviluppo iterativo con Claude Code
- Gestire task complessi con suddivisione automatica
- Sfruttare la conoscenza multi-stack di Claude Code
- Integrare accessibilità WCAG 2.1 AA nel processo di sviluppo
- Eseguire refactoring contestuale cross-file
- Gestire l'intero ciclo di integrazione di librerie esterne
- Applicare convenzioni di naming bilingui (italiano/inglese)
- Utilizzare Claude Code per debugging e problem solving
- Sfruttare la memoria persistente per pattern ricorrenti
- Strutturare piani di lavoro con il Plan Mode
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 (sei qui) | Claude Code in produzione |
1. Configurazione del Progetto con CLAUDE.md
Il cuore dell'integrazione di Claude Code in Play The Event è il file CLAUDE.md, posizionato nella root del repository. Questo file definisce il contesto completo del progetto, permettendo a Claude di ereditare automaticamente l'architettura, le convenzioni e i vincoli ad ogni sessione.
# CLAUDE.md - Play The Event
## Architettura
- Domain-Driven Design (DDD)
- Hexagonal Architecture (Ports & Adapters)
- CQRS (Command Query Responsibility Segregation)
## Comandi di Sviluppo
### Backend (Java/Spring Boot)
- mvn spring-boot:run -pl backend
- mvn test -pl backend
### Frontend (Angular 19)
- npm start --prefix frontend
- npm run build --prefix frontend
### Analytics (Python/FastAPI)
- uvicorn main:app --reload --port 8001
## Convenzioni di Naming
- Codice sorgente: ITALIANO (Evento, Partecipante, creaEvento())
- API REST: INGLESE (/api/v1/events, /api/v1/participants)
- Database: snake_case inglese (event_participants)
## Accessibilita (OBBLIGATORIO)
- WCAG 2.1 AA per ogni modifica UI
- Contrasto minimo 4.5:1
- Aria-labels su tutti gli elementi interattivi
- Navigazione da tastiera completa
## Formato Commit
- [fe] - Modifiche frontend Angular
- [be] - Modifiche backend Spring Boot
- [py] - Modifiche analytics Python
- [deploy] - Configurazione deployment
- [docs] - Documentazione
Grazie a questo file, Claude Code non ha bisogno di ricevere spiegazioni ripetitive sull'architettura. Ad ogni nuova sessione, legge il CLAUDE.md e opera con piena consapevolezza dello stack, delle convenzioni e dei vincoli del progetto.
2. Slash Commands Personalizzati
Per i task ripetitivi, Claude Code supporta slash commands personalizzati che automatizzano operazioni comuni. In Play The Event ne utilizziamo diversi per mantenere coerenza e velocità.
Comandi Personalizzati
| Comando | Descrizione | Uso Tipico |
|---|---|---|
| /commit | Genera commit con formato validato | Dopo ogni modifica completata |
| /create-aggregate | Scaffolding DDD completo | Nuova entità di dominio |
| /create-component | Componente Angular 19 standalone | Nuova UI feature |
| /create-migration | Script Flyway SQL | Evoluzione schema database |
| /review-ddd | Verifica compliance architetturale | Code review automatizzata |
| /generate-tests | Generazione automatica unit test | Copertura test rapida |
# Il comando /create-aggregate genera automaticamente:
## Domain Layer
src/main/java/com/pte/domain/model/Evento.java # Entità
src/main/java/com/pte/domain/model/EventoId.java # Value Object ID
src/main/java/com/pte/domain/repository/EventoRepository.java # Port
## Application Layer
src/main/java/com/pte/application/command/CreaEventoCommand.java
src/main/java/com/pte/application/handler/CreaEventoHandler.java
src/main/java/com/pte/application/query/GetEventoQuery.java
## Infrastructure Layer
src/main/java/com/pte/infrastructure/persistence/EventoJpaRepository.java
src/main/java/com/pte/infrastructure/persistence/EventoEntity.java
## Interface Layer
src/main/java/com/pte/interfaces/rest/EventoController.java
src/main/java/com/pte/interfaces/rest/dto/EventoRequest.java
src/main/java/com/pte/interfaces/rest/dto/EventoResponse.java
Ogni comando genera codice che rispetta le convenzioni definite nel CLAUDE.md: classi in italiano, endpoint REST in inglese, struttura Hexagonal rigorosa.
3. Workflow di Sviluppo Iterativo
Il ciclo di sviluppo con Claude Code segue un pattern iterativo naturale che parte da una richiesta in linguaggio naturale e arriva al codice verificato.
Ciclo di Sviluppo Tipico
- Richiesta: L'utente descrive la feature in linguaggio naturale
- Analisi: Claude legge automaticamente i file rilevanti
- Implementazione: Propone e applica le modifiche con spiegazioni
- Verifica: Esegue la build per controllare errori di compilazione
- Iterazione: L'utente segnala problemi, Claude corregge
# Richiesta utente:
"Migliora il CSS della sezione expense-analytics"
# Claude Code:
1. Legge expense-analytics.component.scss
2. Legge expense-analytics.component.html
3. Analizza il design system esistente
4. Propone miglioramenti: grid layout, spacing, responsive
5. Applica le modifiche
6. Esegue: npm run build --prefix frontend
7. Risultato: Build OK, 0 errori
# Seconda iterazione:
"L'export deve essere in Excel, non JSON"
# Claude Code:
1. Identifica la necessità di una libreria esterna
2. Installa: npm install xlsx --prefix frontend
3. Modifica la funzione di export
4. Crea 8 fogli Excel strutturati (uno per sezione analytics)
5. Verifica la build: OK
4. Gestione di Task Complessi
Quando un task è troppo grande per essere completato in un singolo passaggio, Claude Code lo suddivide automaticamente in sottotask tracciabili, completandoli in sequenza con verifica.
# Richiesta: "Migliorie Dashboard Analytics"
Claude suddivide automaticamente in:
[1/6] Empty States per sezioni senza dati
[2/6] Quick Actions Bar con azioni frequenti
[3/6] Miglioramenti visivi KPI cards
[4/6] Trend comparativi mese precedente
[5/6] Sezione prossimi eventi in programma
[6/6] Sparklines nei KPI per trend rapido
Ogni sottotask viene:
- Implementato singolarmente
- Verificato con build
- Committato separatamente
Questo approccio garantisce che ogni modifica sia isolata, verificabile e facilmente reversibile in caso di problemi.
5. Conoscenza Multi-Stack
Play The Event opera su tre stack tecnologici diversi nello stesso repository. Claude Code comprende le relazioni tra i layer e opera su tutti e tre con consapevolezza delle dipendenze reciproche.
Backend - Java/Spring Boot
- Entità di dominio DDD
- Repository e servizi applicativi
- Controller REST
- Configurazione Spring Security
- Migrazione database Flyway
Frontend - Angular 19
- Componenti standalone con Signals
- Servizi HTTP e interceptors
- Gestione stato reattivo
- Routing lazy-loaded
- SCSS con design system
Analytics - Python/FastAPI
- Machine Learning per clustering partecipanti
- Predizioni di affluenza eventi
- Report automatizzati con grafici
- API RESTful per integrazione frontend
Claude comprende che un DTO nel backend corrisponde a un modello TypeScript nel frontend e a uno schema di risposta nell'analytics. Quando modifica un'entità, propaga le modifiche attraverso tutti i layer coinvolti.
6. Accessibilita Integrata
Le linee guida WCAG 2.1 AA sono integrate direttamente nel CLAUDE.md. Claude Code le applica automaticamente durante ogni modifica UI, senza bisogno di promemoria manuali.
## Checklist Accessibilita (OBBLIGATORIO per ogni modifica UI)
### Contrasto e Colori
- Rapporto minimo 4.5:1 per testo normale
- Rapporto minimo 3:1 per testo grande (18px+ o 14px+ bold)
- NON usare #F39C12 su sfondo bianco (contrasto insufficiente)
- Colori accessibili documentati nel design system
### Struttura HTML
- Gerarchia heading corretta (h1 > h2 > h3, mai saltare livelli)
- Elementi semantici: nav, main, section, article, aside
- Aria-labels su tutti gli elementi interattivi senza testo visibile
- Role attributes dove necessario
### Interazione
- Tab order logico e sequenziale
- Focus visibile su tutti gli elementi interattivi
- Touch targets minimo 44x44px
- Supporto navigazione da tastiera completa
Quando Claude Code genera un nuovo componente o modifica un template esistente, verifica automaticamente la conformità a queste regole, aggiungendo aria-labels, controllando i contrasti e garantendo la navigazione da tastiera.
7. Refactoring Contestuale
Claude Code comprende le dipendenze tra i file del progetto. Quando si modifica un modello, un servizio o un componente, propaga automaticamente le modifiche a tutti i file correlati.
Propagazione Automatica delle Modifiche
| Azione | Propagazione Automatica |
|---|---|
| Modifica modello TypeScript | Aggiorna servizi, componenti e template che lo usano |
| Rinomina proprietà | Propaga il cambiamento in tutti i file correlati |
| Rimuovi una feature | Pulisce import, traduzioni i18n e route |
| Modifica DTO backend | Aggiorna interfaccia TypeScript corrispondente |
# Richiesta: "Rinomina 'dataEvento' in 'dataInizio' nell'entità Evento"
# Claude Code propaga automaticamente:
1. domain/model/Evento.java → dataEvento → dataInizio
2. interfaces/rest/dto/EventoResponse.java → campo aggiornato
3. infrastructure/persistence/EventoEntity.java → colonna mappata
4. frontend/models/evento.model.ts → proprietà TypeScript
5. frontend/components/evento-detail.component.html → binding template
6. frontend/components/evento-list.component.html → colonna tabella
7. resources/db/migration/V12__rename_data_evento.sql → ALTER TABLE
8. Integrazione con Librerie Esterne
Claude Code gestisce l'intero ciclo di vita dell'integrazione di nuove librerie, dall'identificazione della necessità alla verifica della build finale.
Ciclo Completo di Integrazione
- Identifica: Riconosce quando serve una libreria esterna per il task richiesto
- Installa: Esegue il comando di installazione appropriato (npm, maven, pip)
- Implementa: Importa, configura e utilizza l'API della libreria
- Verifica: Esegue la build per assicurare zero errori di compilazione
# Richiesta: "L'export dei report deve essere in Excel, non JSON"
# Step 1 - Identifica
Claude: "Per generare file Excel serve la libreria xlsx"
# Step 2 - Installa
$ npm install xlsx --save --prefix frontend
# Step 3 - Implementa
import * as XLSX from 'xlsx';
exportToExcel(data: ReportAnalytics): void {{ '{' }}
const workbook = XLSX.utils.book_new();
// Crea 8 fogli strutturati
XLSX.utils.book_append_sheet(workbook,
XLSX.utils.json_to_sheet(data.kpiRiepilogo), 'KPI');
XLSX.utils.book_append_sheet(workbook,
XLSX.utils.json_to_sheet(data.partecipanti), 'Partecipanti');
// ... altri 6 fogli
XLSX.writeFile(workbook, `report-






