davide/CRAPP
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Reorganize documentation and unify the AI assistant rules

Browse Source 
Documentation:
- Add docs/README.md, the documentation index that AGENTS.md pointed to as the
  first file to read but which did not exist.
- One home per piece of information: the feature list stays in ROADMAP.md,
  CHANGELOG.md records only when something shipped, TODO.md only ongoing work.
  Reconcile the entries that had drifted (CSI was both done and pending;
  pagelle, badge social and serie were missing from the roadmap).
- Rewrite DATABASE.md as tables: add giocatori_squadra (already created by a
  migration) and profili_giocatore (planned in DD-016), fix the wrong heading
  levels, drop the duplicated roadmap.
- DESIGN_DECISIONS.md: move the index to the top and sort it, extract the
  template into _template-dd.md.
- ARCHITECTURE.md becomes the technical reference; CLAUDE.md no longer
  duplicates it.
- Add docs/EFFICIENZA_CLOUD.md with the rules previously kept in mem/,
  separating what the code enforces from the goals not yet implemented.
- Fix statements the code contradicted: mutations use setQueryData rather than
  invalidateQueries, and scout_sessioni and giocatori_squadra are not read by
  the code yet.
- Track the v1.0 modules with no spec in docs/modules/ from TODO.md.

AI assistants:
- AGENTS.md is the single source of the rules, now including the technical
  constraints only Claude Code knew about (generated files, Vite plugins, data
  access) and an end-of-work checklist that applies to every assistant.
- CLAUDE.md and .cursor/rules/crapp.mdc point to AGENTS.md instead of
  restating it.
- Remove the five .cursor/*.md files, which Cursor never loaded.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
davide
2026-08-30 16:26:14 +02:00
co-authored by Claude Opus 5
parent c06b33e83b
commit e1e8dd5415
22 changed files with 485 additions and 812 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+113 -217
View File
@@ -1,231 +1,127 @@
# AGENTS.md
# CrAPP - AI Development Guide
Questo documento definisce le regole che qualsiasi assistente AI (Cursor, Claude Code, Codex, ChatGPT o altri) deve seguire quando lavora su questo progetto.
---
# Obiettivo del progetto
CrAPP è una Progressive Web App sviluppata per digitalizzare completamente la gestione di una squadra di pallavolo.
L'obiettivo principale è:
- ridurre il lavoro amministrativo degli amministratori;
- aumentare il coinvolgimento dei giocatori;
- centralizzare tutte le informazioni della squadra;
- utilizzare l'intelligenza artificiale solo quando porta un reale beneficio.
---
# Prima di modificare il codice
Prima di implementare qualsiasi modifica leggere sempre:
1. docs/README.md
2. docs/VISION.md
3. docs/ROADMAP.md
4. docs/ARCHITECTURE.md
5. docs/DATABASE.md
6. docs/DESIGN_DECISIONS.md
7. docs/TODO.md
8. il documento interessato in docs/modules/
Non implementare funzionalità non documentate.
---
# Workflow di sviluppo
Ogni nuova funzionalità segue sempre questo processo.
Idea
↓
Progettazione
↓
Documentazione
↓
Database
↓
Implementazione
↓
Test
↓
Merge su main
↓
Deploy automatico
---
# Git
Il repository utilizza due branch principali.
## main
Versione stabile.
Qualsiasi modifica deve mantenere l'app perfettamente funzionante.
## develop
Branch utilizzato per lo sviluppo delle nuove funzionalità.
Tutte le nuove implementazioni devono essere realizzate qui.
---
# 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.
Fare sempre riferimento a:
docs/DATABASE.md
---
# Componenti
Preferire:
- componenti piccoli;
- componenti riutilizzabili;
- responsabilità singola;
- codice semplice da mantenere.
Evitare duplicazioni.
---
# 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
- CHANGELOG.md
- TODO.md
- DATABASE.md (se il database cambia)
- DESIGN_DECISIONS.md (se si prende una decisione architetturale importante)
---
# Struttura della documentazione
La cartella `docs/` rappresenta la documentazione ufficiale del progetto.
## Documenti principali
- README.md → panoramica del progetto
- VISION.md → obiettivi e filosofia
- ROADMAP.md → evoluzione prevista
- ARCHITECTURE.md → architettura tecnica
- DATABASE.md → struttura del database
- DESIGN_DECISIONS.md → registro delle decisioni di progetto
- CHANGELOG.md → cronologia delle modifiche
- TODO.md → attività pianificate
## Moduli
La cartella `docs/modules/` contiene una specifica funzionale per ogni modulo dell'applicazione.
Ogni nuovo modulo deve essere progettato e documentato prima dell'implementazione.
---
# Regole
L'AI non deve:
# AGENTS.md — CrAPP
Regole che qualsiasi assistente AI (Claude Code, Codex, Cursor, ChatGPT o altri) deve seguire
quando lavora su questo progetto. **È l'unica fonte delle regole**: `CLAUDE.md` e
`.cursor/rules/` rimandano qui, non ripetono nulla.
> **Qualsiasi cosa venga aggiunta o modificata — una regola, una funzionalità, una decisione,
> una tabella — va registrata nei file di riferimento del progetto prima di considerare il
> lavoro finito**, indipendentemente dall'assistente con cui è stata fatta. Vedi
> [Fine lavoro](#fine-lavoro-cosa-aggiornare-sempre): non è un passaggio opzionale.
CrAPP è una Progressive Web App per la gestione di una squadra di pallavolo amatoriale (CRAP
Volley). Obiettivi e principi in [docs/VISION.md](docs/VISION.md), architettura in
[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
**Codice, commenti, nomi di variabili e documentazione sono in italiano**: mantieni questa
convenzione.
## Prima di modificare il codice
Leggere sempre, nell'ordine:
1. [docs/README.md](docs/README.md) — indice della documentazione
2. [docs/VISION.md](docs/VISION.md)
3. [docs/ROADMAP.md](docs/ROADMAP.md)
4. [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
5. [docs/DATABASE.md](docs/DATABASE.md)
6. [docs/DESIGN_DECISIONS.md](docs/DESIGN_DECISIONS.md)
7. [docs/TODO.md](docs/TODO.md)
8. il documento del modulo interessato in [docs/modules/](docs/modules/)
**Non implementare funzionalità non documentate** (DD-002).
## Workflow
```
idea → progettazione → documento in docs/modules/ → database → implementazione su develop
→ test → merge su main → deploy automatico Vercel
```
- `main` = produzione, sempre funzionante: **non si modifica direttamente**. Qualsiasi
modifica deve mantenere l'app perfettamente funzionante.
- `develop` = sviluppo e preview; tutte le nuove implementazioni nascono qui.
## Vincoli tecnici da non violare
- `src/routeTree.gen.ts` e `src/integrations/supabase/{client.ts,types.ts}` sono **generati**:
non modificarli a mano.
- **Non ri-aggiungere** i plugin Vite (devtools, tanstackStart, viteReact, tailwind,
tsconfig-paths, nitro) già inclusi da `@lovable.dev/vite-tanstack-config` in
`vite.config.ts`: l'app si rompe.
- Nessun accesso al database dai componenti: solo tramite i moduli in `src/lib/`, così il
backend resta sostituibile in un solo punto (DD-013).
- Efficienza cloud: niente polling, cache lunga, e dopo una mutazione `setQueryData` invece di
`invalidateQueries`. Regole complete in [docs/EFFICIENZA_CLOUD.md](docs/EFFICIENZA_CLOUD.md).
- Badge e statistiche si calcolano a runtime, non si persistono (DD-007); la gamification
resta equa tra ruoli (DD-008): niente metriche che favoriscano attaccanti o liberi.
- L'app deve poter girare su Node.js + PostgreSQL standard: niente servizi esclusivi
Lovable/Vercel (DD-001, DD-013, [docs/PORTABILITA.md](docs/PORTABILITA.md)).
## Database
- Non eliminare tabelle esistenti.
- Non modificare lo schema senza creare una migration in `supabase/migrations/`.
- Preferire una nuova tabella all'aggiunta di molte colonne, quando il modulo è indipendente.
- Preferire strutture scalabili; evitare duplicazione dei dati.
- Riferimento: [docs/DATABASE.md](docs/DATABASE.md), da aggiornare nella stessa modifica che
cambia lo schema.
## Codice e componenti
- TypeScript, funzioni piccole, nomi descrittivi.
- Componenti piccoli, riutilizzabili, a responsabilità singola.
- Nessuna duplicazione: riusare sempre i componenti e i moduli esistenti.
- Commentare solo il codice realmente complesso.
- Nessuna nuova dipendenza senza reale necessità; mantenere la struttura esistente.
- Le dipendenze si installano con **bun**; `bunfig.toml` impone `minimumReleaseAge = 24h` come
guardia supply-chain: aggiungere un pacchetto a `minimumReleaseAgeExcludes` richiede
conferma esplicita dell'utente.
## Interfaccia
Stile coerente con l'esistente: semplice, moderna, pulita, veloce, ottimizzata per
smartphone, poche schermate e pochi click (DD-005). Riusare i componenti in
`src/components/crapp/` (`ui-bits.tsx` per `PageHeader`, `Section`, `StatTile`) e le primitive
shadcn in `src/components/ui/`.
## Fine lavoro: cosa aggiornare sempre
Il lavoro **non è finito** finché non è registrato dove va. Vale per tutti gli assistenti allo
stesso modo: chi fa la modifica aggiorna i file, chiunque la stia facendo e da qualunque
strumento. Un cambiamento che vive solo nel codice o solo nella chat è un cambiamento perso.
| Cosa hai aggiunto o cambiato | Dove va registrato |
|---|---|
| Una **regola** per gli assistenti (convenzione, divieto, vincolo di lavoro) | **Questo file, e solo questo.** Mai in `CLAUDE.md` o `.cursor/rules/`: rimandano qui, e una regola scritta lì la vedrebbe un assistente solo |
| Una **funzionalità** | `docs/modules/<modulo>.md` (**prima** di scrivere il codice), poi `docs/ROADMAP.md` e `docs/CHANGELOG.md` |
| Una **decisione** architetturale o di prodotto | `docs/DESIGN_DECISIONS.md`, formato `DD-XXX` (copiare `docs/_template-dd.md`) e aggiungerla all'indice in cima |
| Una **modifica allo schema** del database | una migration in `supabase/migrations/` **e** `docs/DATABASE.md`, nella stessa modifica |
| Lavoro iniziato, sospeso o concluso | `docs/TODO.md` e `PROJECT_STATE.md` |
| Un **comando** o uno script nuovo | `docs/ARCHITECTURE.md` (sezione Comandi) e `CLAUDE.md` |
Quale informazione vive in quale file — e perché non va duplicata altrove — è spiegato in
[docs/README.md](docs/README.md).
## Cosa l'AI non deve fare
- introdurre librerie senza necessità;
- modificare il database senza motivazione;
- eliminare funzionalità esistenti;
- modificare il comportamento dell'app senza richiesta esplicita.
L'AI deve:
## Cosa l'AI deve fare
- spiegare le modifiche importanti;
- mantenere compatibilità con il codice esistente;
- privilegiare la semplicità;
- riutilizzare i componenti esistenti.
---
## Filosofia
# Filosofia del progetto
Prima di scrivere codice, chiedersi sempre:
Prima di scrivere codice chiedersi sempre:
Questa modifica rende CrAPP più semplice?
Riduce il lavoro degli amministratori?
Migliora l'esperienza dei giocatori?
È coerente con la documentazione?
Se almeno una risposta è negativa, rivalutare la soluzione proposta.
- questa modifica rende CrAPP più semplice?
- riduce il lavoro degli amministratori?
- migliora l'esperienza dei giocatori?
- è coerente con la documentazione?