11 - Integrare Claude Code in un Progetto Reale

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.

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

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

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

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.

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

# 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-${{ '{' }}data.nomeEvento{{ '}' }}.xlsx`);
{{ '}' }}

# Step 4 - Verifica
$ npm run build --prefix frontend
Build completata con successo. 0 errori.

9. Convenzioni di Naming Bilingui

Una peculiarita di Play The Event documentata nel CLAUDE.md: il codice sorgente usa nomi in italiano, mentre le API REST seguono convenzioni in inglese. Claude Code rispetta questa distinzione automaticamente.

// Claude genera il controller rispettando entrambe le convenzioni

@RestController
@RequestMapping("/api/v1/events")  // Inglese per API
public class EventoController {{ '{' }}  // Italiano per classe

    private final CreaEventoHandler creaEventoHandler;  // Italiano

    @PostMapping
    public ResponseEntity<EventoResponse> createEvent(  // Inglese per metodo HTTP
        @RequestBody CreaEventoRequest request) {{ '{' }}  // Italiano per DTO interno
        return ResponseEntity.ok(
            creaEventoHandler.esegui(request)  // Italiano per logica
        );
    {{ '}' }}
{{ '}' }}

10. Debugging e Problem Solving

Claude Code analizza errori e propone fix mirati. Non si limita a suggerire: identifica la causa, implementa la soluzione e verifica che funzioni.

# Segnalazione: "Il pulsante Export Report non funziona"

# Claude Code analizza il codice:
exportReport() {{ '{' }}
  console.log('Export report clicked');  // Solo un log!
{{ '}' }}

# Diagnosi: La funzione non e mai stata implementata,
# contiene solo un placeholder console.log

# Fix implementato da Claude Code:
exportReport() {{ '{' }}
  const reportData = this.analyticsService.getReportCompleto();
  const blob = new Blob([JSON.stringify(reportData, null, 2)],
    {{ '{' }} type: 'application/json' {{ '}' }});
  const url = URL.createObjectURL(blob);
  const link = document.createElement('a');
  link.href = url;
  link.download = `report-${{ '{' }}this.evento.nome{{ '}' }}.json`;
  link.click();
  URL.revokeObjectURL(url);
{{ '}' }}

11. Memoria Persistente (Auto Memory)

Claude Code mantiene una directory di memoria persistente che sopravvive tra le sessioni. Questo permette di accumulare conoscenza incrementale sul progetto, documentare pattern ricorrenti e soluzioni a errori comuni.

/home/user/.claude/projects/play-the-event/memory/
  MEMORY.md              # File principale (caricato nel system prompt)
  debugging.md           # Errori comuni e soluzioni
  patterns.md            # Pattern architetturali ricorrenti
  conventions.md         # Convenzioni specifiche del progetto

# Play The Event - Memoria di Progetto

## Pattern Ricorrenti
- Gli aggregati DDD seguono sempre: Entity + ValueObject ID + Repository Port
- I componenti Angular usano Signals, mai subscribe manuale
- Le migrazioni Flyway seguono V{{ '{' }}numero{{ '}' }}__{{ '{' }}descrizione{{ '}' }}.sql

## Errori Comuni Risolti
- Angular: "NG0100 ExpressionChangedAfterItHasBeenChecked"
  → Soluzione: usare signal computed() invece di getter
- Spring Boot: "LazyInitializationException" nelle query
  → Soluzione: usare JOIN FETCH o @EntityGraph

## Decisioni Architetturali
- Scelto CQRS per separare letture (analytics) da scritture (comandi)
- FastAPI per analytics perchè le librerie ML sono native Python

La memoria viene consultata automaticamente all'inizio di ogni sessione, permettendo a Claude Code di costruire sulla conoscenza delle sessioni precedenti senza ricominciare da zero.

12. Piano di Lavoro Strutturato

Per task complessi che richiedono modifiche su più file o decisioni architetturali, Claude Code entra in Plan Mode: un workflow strutturato che garantisce allineamento con lo sviluppatore prima di scrivere codice.

# Plan Mode - Fasi

## Fase 1: Esplorazione
- Claude Code esplora il codebase
- Identifica file coinvolti
- Analizza dipendenze e impatto

## Fase 2: Progettazione
- Propone piano dettagliato con priorità
- Elenca file da creare/modificare
- Identifica rischi e alternative

## Fase 3: Revisione
- Presenta il piano allo sviluppatore
- Risponde a domande e chiarimenti
- Modifica il piano se necessario

## Fase 4: Approvazione
- Lo sviluppatore approva il piano
- Claude Code inizia l'implementazione
- Esegue step by step con verifica

Benefici Misurabili

L'integrazione di Claude Code nel workflow di Play The Event ha prodotto miglioramenti concreti e misurabili nella produttività quotidiana.

Strumenti e Risorse per Claude Code

Claude Code non vive in isolamento: attorno ad esso si è sviluppato un ecosistema ricco di estensioni, strumenti comunitari, SDK e risorse formative che ne amplificano le capacità. Conoscere questo ecosistema permette di sfruttare al massimo il potenziale di Claude Code in qualsiasi contesto di sviluppo.

Estensioni per IDE

L'integrazione con gli editor di codice rappresenta il punto di contatto più diretto tra Claude Code e il flusso di lavoro quotidiano. Claude Code Chat per VS Code offre un'interfaccia di chat nativa direttamente nell'editor, con cronologia delle conversazioni e supporto completo per i server MCP. Questo significa poter interagire con Claude senza mai abbandonare l'ambiente di sviluppo, mantenendo il contesto del progetto sempre attivo. A complemento, il Claude VSCode Theme fornisce una collezione di temi scuri progettati per ridurre l'affaticamento visivo durante sessioni prolungate di pair programming con l'assistente.

Claude for Chrome

Per chi lavora frequentemente nel browser, Claude for Chrome (attualmente in Beta) porta le capacità dell'agente direttamente nella navigazione web. Questa estensione supporta la pianificazione automatica dei task, consentendo di schedulare operazioni ricorrenti, e introduce un planning mode per strutturare flussi di lavoro complessi prima di eseguirli. La gestione multi-tab permette di coordinare azioni su diverse schede simultaneamente, mentre la navigazione intelligente consente a Claude di interagire con le pagine web in modo autonomo. Questa funzionalità richiede il piano Max ed è particolarmente utile per task di ricerca, testing di interfacce web e automazione di workflow basati su browser.

Guide della Community

La community degli sviluppatori ha prodotto risorse di altissimo valore per padroneggiare Claude Code. La guida "Claude Code Everything You Need to Know" rappresenta il riferimento più completo disponibile, coprendo setup iniziale, prompt engineering, comandi, hooks, workflow di automazione, configurazione di server MCP e il metodo BMAD per la gestione strutturata dei progetti. Per chi preferisce un approccio più conciso, "40+ Claude Code Tips" raccoglie oltre quaranta suggerimenti pratici e immediatamente applicabili, dalla configurazione ottimale alle tecniche avanzate di interazione con l'agente.

Ecosistema di Server MCP

Il Model Context Protocol (MCP) ha dato vita a un ecosistema di integrazioni che estende le capacità di Claude Code ben oltre il terminale. Il repository awesome-mcp-servers cataloga un panorama impressionante di oltre 2500 integrazioni API organizzate per categoria. Le categorie principali includono:

• Browser Automation: Microsoft Playwright per il controllo programmatico di browser
• Cloud Platforms: AWS, Cloudflare, Terraform e Pulumi per la gestione dell'infrastruttura
• Database: Connettori per PostgreSQL, MongoDB, Redis e altri sistemi di persistenza
• Developer Tools: Integrazioni con GitHub, GitLab, Jira e strumenti di CI/CD
• Security: Scanner di vulnerabilità, analisi statica e audit di sicurezza

Per lo sviluppo e il testing di server MCP personalizzati, l'MCP Inspector fornisce un ambiente di debug interattivo che semplifica notevolmente il processo di sviluppo e validazione dei propri server.

Agent SDK per Agenti Autonomi

Per gli sviluppatori che desiderano costruire agenti personalizzati basati su Claude, sono disponibili SDK ufficiali sia per Python che per TypeScript. Questi kit di sviluppo forniscono le primitive necessarie per creare agenti autonomi capaci di ragionare, pianificare ed eseguire task complessi in modo indipendente.

La community ha risposto con entusiasmo: il repository awesome-claude-agents raccoglie una collezione curata di agenti costruiti con questi SDK, mentre awesome-claude-code-subagents cataloga oltre 100 agenti specializzati progettati per task specifici come generazione di codice, revisione, testing, documentazione e deployment. Questi sub-agenti possono essere combinati in pipeline sofisticate, creando flussi di lavoro completamente automatizzati.

Corsi Ufficiali

Anthropic offre un percorso formativo strutturato per sviluppatori che vogliono padroneggiare l'intero ecosistema Claude:

Questi corsi coprono l'intero spettro delle possibilità offerte dalla piattaforma Claude, dalla scrittura di codice assistita alla costruzione di sistemi agentic complessi, fino al deployment su piattaforme cloud enterprise.

Conclusione

L'integrazione di Claude Code in Play The Event dimostra che Claude Code non è un semplice autocomplete: è un pair programmer che comprende l'architettura del progetto, applica le convenzioni del team e mantiene coerenza attraverso un codebase enterprise multi-stack.

La chiave del successo è trattare Claude Code come un membro del team: fornirgli contesto chiaro, convenzioni esplicite e feedback iterativo. Il risultato è un workflow di sviluppo radicalmente più efficiente, dove la qualità del codice e la velocità di delivery crescono insieme.