Guida alla Configurazione del File CLAUDE.md

# Nome del Progetto

## Panoramica del Progetto

[Breve descrizione dello scopo del progetto, funzioni principali e utenti target]

## Stack Tecnologico

- Frontend: [Framework e librerie principali]
- Backend: [Linguaggio e framework]
- Database: [Tipo di database]
- Deploy: [Piattaforma di deploy]

## Struttura del Progetto

\```
project/
├── src/ # Codice sorgente
├── tests/ # File di test
├── docs/ # Documentazione
└── scripts/ # File di script
\```

## Standard di Sviluppo

[Standard di codifica specifici del progetto]

## Note

[Note e restrizioni specifiche del progetto]

# CLAUDE.md - File di Configurazione del Progetto

## Regole Generali (obbligatorie per tutti i progetti)

### Lingua di Comunicazione

- Usare sempre cinese semplificato per pensare e dialogare
- Commenti di codice in inglese, documentazione in cinese

### Gestione Documenti

- Documentazione ufficiale nella directory `docs/`
- Proposte di discussione nella directory `discuss/`
- Mantenere README conciso, documentazione dettagliata separata

## Standard di Architettura del Codice

### Limiti di Dimensione File

- Python/JavaScript/TypeScript: ogni file non più di 300 righe
- Java/Go/Rust: ogni file non più di 400 righe
- Non più di 8 file per cartella
- Se superato, necessario refactoring o suddivisione

### Indicatori di Qualità del Codice

Evitare i seguenti code smell:

1. **Rigidità**: Sistema difficile da modificare
2. **Ridondanza**: Troppo codice duplicato
3. **Dipendenze Circolari**: Moduli interdipendenti
4. **Fragilità**: Modifiche causano problemi a catena
5. **Oscurità**: Intenzione del codice non chiara
6. **Data Clumps**: Elementi di dati appaiono sempre insieme
7. **Sovraprogettazione**: Complessità non necessaria

## Vincoli dello Stack Tecnologico

### Stack Tecnologico Frontend

- React 19+ (non usare versione 18 o inferiore)
- Next.js 15.4+ (non usare versione 14 o inferiore)
- Tailwind CSS v4 (non usare v3)
- Preferire TypeScript, evitare JavaScript
- Vietare CommonJS, usare solo ES Modules

### Stack Tecnologico Backend

- Node.js 18+
- Usare TypeScript
- Express/Fastify come framework web
- Prisma come ORM

### Progetti Python

- Usare uv per gestione dipendenze (non pip/poetry/conda)
- Nome directory ambiente virtuale: `.venv`
- Tipizzazione forte, evitare uso di dict
- Mantenere directory radice del progetto pulita

## Flusso di Lavoro di Sviluppo

### Gestione Script

- Tutti gli script nella directory `scripts/`
- Usare script `.sh` per operazioni start-stop
- Nessun comando npm/pnpm/python diretto
- Fallimenti di script devono essere corretti immediatamente

### Gestione Log

- File di configurazione producono log
- Output unificato nella directory `logs/`
- Includere timestamp e livello di log
- Memorizzare log di errore separatamente

### Requisiti di Test

- Copertura test unitari > 80%
- Funzioni critiche devono avere test di integrazione
- File di test nella directory `tests/`
- Usare CI/CD per eseguire test automaticamente

## Convenzioni di Nomenclatura

### Nomi File

- Componenti: PascalCase (es. UserProfile.tsx)
- Funzioni utility: camelCase (es. formatDate.ts)
- File costanti: UPPER_SNAKE_CASE (es. API_CONSTANTS.ts)
- File di stile: kebab-case (es. user-profile.css)

### Nomi Variabili

- Variabili/Funzioni: camelCase
- Costanti: UPPER_SNAKE_CASE
- Classi/Interfacce: PascalCase
- Proprietà private: \_camelCase

## Flusso di Lavoro Git

### Strategia di Branching

- main: Codice di produzione
- develop: Codice di sviluppo
- feature/\*: Branch di funzionalità
- hotfix/\*: Branch di correzione di emergenza

### Convenzioni di Commit

- feat: Nuova funzionalità
- fix: Correzione bug
- docs: Aggiornamento documentazione
- style: Formattazione codice
- refactor: Refactoring codice
- test: Relativo a test
- chore: Modifiche build/strumenti

## Standard di Progettazione API

### Principi RESTful

- GET: Ottenere risorsa
- POST: Creare risorsa
- PUT: Aggiornare risorsa (completo)
- PATCH: Aggiornare risorsa (parziale)
- DELETE: Eliminare risorsa

### Formato Risposta

\```json
{
"success": true,
"data": {},
"message": "Operazione riuscita",
"timestamp": "2024-01-01T00:00:00Z"
}
\```

### Gestione Errori

\```json
{
"success": false,
"error": {
"code": "ERROR_CODE",
"message": "Descrizione errore",
"details": {}
}
}
\```

## Standard di Sicurezza

### Informazioni Sensibili

- Non codificare chiavi nel codice
- Usare variabili d'ambiente per gestione configurazione
- Non committare file `.env` in Git
- Aggiornare regolarmente le dipendenze

### Validazione Dati

- Validazione dati sia frontend che backend
- Usare librerie di validazione schema (es. zod)
- Parametrizzare query SQL
- Prevenire attacchi XSS e CSRF

## Ottimizzazione delle Performance

### Ottimizzazione Frontend

- Lazy loading per immagini
- Code splitting
- Strategia di cache
- Scroll virtuale (liste grandi)

### Ottimizzazione Backend

- Ottimizzazione query database
- Usare cache (Redis)
- Compressione risposte API
- Controllo concorrenza

## Configurazione Deploy

### Variabili d'Ambiente

- development: Ambiente di sviluppo
- staging: Ambiente di test
- production: Ambiente di produzione

### Containerizzazione

- Usare Docker per deploy
- Build multi-stage per ottimizzare dimensione immagine
- Usare docker-compose per orchestrazione servizi

## Monitoraggio e Log

### Metriche di Monitoraggio

- Tempo di risposta API
- Tasso di errore
- Utilizzo risorse
- Analisi comportamento utente

### Livelli di Log

- ERROR: Informazioni errore
- WARN: Informazioni avviso
- INFO: Informazioni generali
- DEBUG: Informazioni debug

## Note Speciali

⚠️ **Promemoria Importanti**:

1. Affrontare immediatamente problemi di codice
2. Chiedere attivamente all'utente in caso di incertezza
3. Mantenere codice pulito e manutenibile
4. Seguire standard stabiliti del progetto

## Standard Progetto React/Next.js

### Standard Componenti

- Usare componenti funzionali + Hooks
- File componente con stesso nome del componente
- Un file, un componente
- Props definite con interfacce TypeScript

### Gestione Stato

- Stato semplice: useState
- Stato complesso: useReducer
- Stato globale: Context API / Zustand
- Stato server: TanStack Query

### Soluzione Styling

- Tailwind CSS v4 come principale
- CSS Modules come complemento
- Evitare stili inline
- Priorità a design responsive

### Ottimizzazione Performance

- Usare React.memo per evitare rendering non necessario
- useMemo/useCallback per ottimizzazione calcoli
- Importazioni dinamiche per code splitting
- Usare componente next/image per immagini

## Standard Progetto Python

### Struttura Progetto

\```
project/
├── src/
│ ├── **init**.py
│ ├── main.py
│ ├── models/
│ ├── services/
│ └── utils/
├── tests/
├── .venv/
└── pyproject.toml
\```

### Gestione Dipendenze

- Usare uv per tutte le dipendenze
- pyproject.toml per definire configurazione progetto
- requirements.txt per deploy di produzione
- requirements-dev.txt per dipendenze di sviluppo

### Annotazioni di Tipo

- Tutte le funzioni devono avere annotazioni di tipo
- Usare dataclass per definire strutture dati
- Combinare con mypy per verifica tipi
- Evitare uso tipo Any

### Programmazione Asincrona

- Priorità a async/await
- Usare asyncio per gestione concorrenza
- Usare driver asincroni per operazioni database
- Usare httpx per richieste HTTP

## Standard Architettura Microservizi

### Suddivisione Servizi

- Dividere servizi per dominio business
- Ogni servizio si deploya indipendentemente
- Comunicazione inter-servizi via API
- Codice condiviso tramite gestione pacchetti

### API Gateway

- Gestione ingresso unificata
- Autenticazione e autorizzazione
- Rate limiting e circuit breaking
- Routing richieste

### Comunicazione Servizi

- HTTP/REST: Chiamate sincrone
- Code messaggi: Comunicazione asincrona
- gRPC: Scenari alte prestazioni
- WebSocket: Comunicazione in tempo reale

### Gestione Dati

- Ogni servizio ha proprio database
- Evitare transazioni inter-servizi
- Usare event-driven per mantenere coerenza
- Implementare operazioni idempotenti

> /init