Questo documento definisce le regole che qualsiasi assistente AI (Cursor, Claude Code, Codex, ChatGPT o altri) deve seguire quando lavora su questo progetto.
Non presumere che il progetto sia nello stesso stato dell'ultima sessione o conversazione.
---
# Workflow di sviluppo
Ogni nuova funzionalità segue sempre questo processo.
Idea
↓
Progettazione
↓
Documentazione
↓
Database
↓
Implementazione
↓
Test
↓
Pull Request
↓
Merge su develop
↓
Verifica
↓
Merge su main
↓
Deploy
Le funzionalità possono essere sviluppate in parallelo da persone diverse, ciascuna sul proprio branch.
---
# Git
Il repository utilizza due branch principali.
## main
Versione stabile.
Qualsiasi modifica deve mantenere l'app perfettamente funzionante.
`main` rappresenta la versione destinata alla produzione.
## develop
Branch di integrazione e test.
Le nuove funzionalità vengono integrate in `develop` prima di arrivare in `main`.
Non lavorare direttamente su `main`.
Evitare modifiche dirette a `develop`, salvo attività esplicitamente concordate.
---
# Branch di sviluppo
Ogni sviluppatore deve lavorare su un branch dedicato creato a partire da `develop`.
Esempi:
-`feature/profilo-giocatore`
-`feature/integrazione-csi`
-`fix/presenze`
-`refactor/supabase-client`
Non utilizzare lo stesso branch contemporaneamente per attività indipendenti.
Prima di iniziare un'attività verificare che il branch sia aggiornato rispetto a `develop`.
---
# Integrazione delle modifiche
Le modifiche significative devono essere integrate tramite Pull Request verso `develop`.
Una Pull Request dovrebbe permettere di capire:
- cosa è stato modificato;
- perché è stato modificato;
- quali file o moduli sono coinvolti;
- se il database è stato modificato;
- quali test sono stati eseguiti;
- eventuali rischi o conseguenze.
Prima del merge verificare eventuali conflitti con il lavoro sviluppato nel frattempo dagli altri collaboratori.
---
# Tracciabilità delle modifiche
Ogni modifica significativa deve lasciare una traccia nel progetto.
Devono essere utilizzati:
- commit con messaggi descrittivi;
- Pull Request per l'integrazione;
- [CHANGELOG.md](http://CHANGELOG.md) quando una modifica deve essere registrata nella cronologia del progetto;
- PROJECT_[STATE.md](http://STATE.md) quando cambia lo stato generale del progetto;
- DESIGN_[DECISIONS.md](http://DECISIONS.md) per decisioni architetturali significative.
La documentazione deve permettere a uno sviluppatore o a un assistente AI di ricostruire cosa è successo senza dipendere dalla cronologia delle conversazioni.
---
# Aggiornamento del contesto dopo la sincronizzazione
Quando vengono scaricate modifiche da GitHub, l'assistente AI deve considerare il repository come fonte di verità.
Prima di iniziare una nuova attività deve:
1. verificare i nuovi commit;
2. identificare le modifiche rilevanti;
3. leggere la documentazione modificata;
4. verificare eventuali modifiche al database;
5. tenere conto delle nuove decisioni architetturali.
Non ignorare modifiche introdotte da altri collaboratori.
Non sovrascrivere modifiche esistenti senza averne compreso lo scopo.
---
# Architettura
Frontend
- React
- TypeScript
- TanStack Start
- Tailwind CSS
Backend
- Supabase
Hosting
- Vercel
Repository
- GitHub
---
# Database
Il database utilizza Supabase.
Regole:
- non eliminare tabelle esistenti;
- non modificare lo schema senza creare una migration;
- preferire strutture scalabili;
- evitare duplicazione dei dati;
- non modificare migration già applicate;
- ogni modifica allo schema deve essere rappresentata da una nuova migration.
Fare sempre riferimento a:
docs/[DATABASE.md](http://DATABASE.md)
---
# Componenti
Preferire:
- componenti piccoli;
- componenti riutilizzabili;
- responsabilità singola;
- codice semplice da mantenere.
Evitare duplicazioni.
Prima di creare un nuovo componente verificare se esiste già un componente riutilizzabile.
---
# Interfaccia
Lo stile dell'app deve rimanere coerente.
Principi:
- semplice;
- moderna;
- pulita;
- veloce;
- ottimizzata per smartphone;
- poche schermate;
- pochi click.
---
# Documentazione
Ogni nuova funzionalità deve essere documentata prima dello sviluppo.
La documentazione dei moduli si trova in:
docs/modules/
Aggiornare sempre, quando necessario:
- [ROADMAP.md](http://ROADMAP.md)
- [CHANGELOG.md](http://CHANGELOG.md)
- [TODO.md](http://TODO.md)
- [DATABASE.md](http://DATABASE.md) (se il database cambia)
- DESIGN_[DECISIONS.md](http://DECISIONS.md) (se si prende una decisione architetturale importante)
- PROJECT_[STATE.md](http://STATE.md) (se cambia lo stato generale del progetto)
---
# Struttura della documentazione
La cartella `docs/` rappresenta la documentazione ufficiale del progetto.
## Documenti principali
- [README.md](http://README.md) → panoramica del progetto
- [VISION.md](http://VISION.md) → obiettivi e filosofia
