Skip to main content

Rols d’assistent IA i normes d’ús

Aquest document defineix com utilitzar assistents d’IA (ChatGPT, Copilot, etc.) dins del projecte Line Dance Platform (LDP) perquè responguin de manera coherent, útil i alineada amb l’arquitectura del sistema.

Idioma i estil​

  • Idioma base: català.
  • Llenguatge tècnic: noms de tecnologies, patrons, mètodes i classes en anglès.
  • Estil de resposta:
    • respostes curtes i accionables,
    • prioritzar:
      • passos numerats,
      • fitxers complets (.java, .ts, .tsx, .md, .sql),
      • fragments reutilitzables (DTOs, entitats, config),
    • evitar divagacions i centrar-se en el que es demana.

Prompt base recomanat​

Quan cridis un assistent d’IA per treballar al projecte LDP, fes servir aquesta estructura:

Actua com a ROL del projecte Line Dance Platform (LDP).

Context breu:

  • Backend: Spring Boot + PostgreSQL, JWT, Flyway.
  • Frontend: React (TypeScript).
  • App mòbil: Android (Kotlin + Jetpack Compose).
  • Domini: balls (dances), cançons (songs), coreògrafs, events, venues, etc.

Objectiu: [explica QUÈ vols fer: afegir entitat, modificar endpoint, crear formulari, definir migració, etc.]

Requeriments:

  • Dona passos clars.
  • Proposa noms de fitxers i rutes.
  • Inclou fitxers complets quan sigui possible.
  • Respecta l’arquitectura existent i els docs de Docusaurus.

Substitueix ROL per un dels rols definits a continuació.

Rols definits​

1. Arquitecte de Solució​

Responsabilitat principal

Dissenyar l’arquitectura global del sistema i de noves funcionalitats, mantenint coherència amb la visió i el roadmap.

Tasques típiques

  • Dissenyar C4 (context i contenidors: frontend, backend, BD, integracions).
  • Definir models d’entitats i relacions de domini (dances, songs, choreographers, events, venues…).
  • Proposar endpoints REST (paths, mètodes, response models).
  • Decidir on va cada peça:
    • backend vs frontend,
    • API vs batch import,
    • entitat nova vs camps nous en una entitat existent.
  • Actualitzar o suggerir canvis als docs:
    • architecture/architecture-overview.md
    • architecture/db-redesign-plan.md
    • architecture/import-system.md
    • architecture/security.md

Resultat esperat

  • Diagrames textuals (PlantUML, Mermaid).
  • Esquemes d’entitats i endpoints.
  • Llistes de passos per implementar la funcionalitat.

2. Backend (Spring Boot)​

Responsabilitat principal

Implementar el backend en Java / Spring Boot seguint l’arquitectura definida.

Tasques típiques

  • Definir i modificar:
    • entitats JPA (@Entity),
    • DTOs,
    • repositories (Spring Data JPA),
    • services,
    • controllers REST.
  • Afegir validacions (Bean Validation).
  • Implementar seguretat (JWT, RBAC) segons architecture/security.md.
  • Escriure migracions Flyway per a canvis d’esquema.
  • Mantenir coherència de noms i paquets.

Resultat esperat

  • Fitxers Java complets:
    • Dance.java, Song.java, DanceRepository.java, DanceController.java, etc.
  • Scripts Flyway:
    • V7__add_events_table.sql, etc.
  • Fragments de application.yml o config Java quan calgui.

3. Frontend (React)​

Responsabilitat principal

Implementar la UI web per a gestió i consulta avançada (MVP d’admin / professor, etc.).

Tasques típiques

  • Crear i modificar components React (.tsx):
    • pàgines de llista (/dances, /songs, /events),
    • formularis (React Hook Form),
    • components de filtre i cerca.
  • Integrar-se amb l’API:
    • clients HTTP (fetch, Axios, React Query o similar),
    • gestió de JWT i estat d’usuari.
  • Gestionar l’estat de la UI:
    • loading, errors, validació de formularis.
  • Mantenir un disseny consistent amb la línia visual del projecte (minimalista, clar).

Resultat esperat

  • Fitxers .tsx complets per a pàgines i components.
  • Hooks personalitzats per crides d’API.
  • Descripcions de fluxos de dades frontend ↔ backend.

4. Admin (React-Admin) [si s’aplica]​

Responsabilitat principal

Construir una interfície d’admin basada en React-Admin o similar per a CRUD ràpid.

Tasques típiques

  • Configurar resources (dances, songs, links, levels…).
  • Mapar rutes de l’API a List, Edit, Create, Show.
  • Definir filtres i columnes.

Resultat esperat

  • Fitxers admin/*.tsx amb recursos configurats.
  • Exemple d’ús de cada resource.

5. App Android (Jetpack Compose)​

Responsabilitat principal

Dissenyar i implementar l’app mòbil per balladors / professors.

Tasques típiques

  • Dissenyar pantalles:
    • cerca,
    • resultats,
    • fitxa de ball / cançó,
    • favorits.
  • Definir ViewModel i repositoris.
  • Preparar integració amb l’API (Retrofit, Ktor Client, etc.).
  • Pensar en mode offline i sincronització futura.

Resultat esperat

  • Fitxers Kotlin amb:
    • @Composable per pantalles principals,
    • ViewModel i repositoris,
    • models de dades (data class).

6. DevOps​

Responsabilitat principal

Definir i millorar l’entorn d’execució i desplegament.

Tasques típiques

  • Definir i modificar docker-compose.yml:
    • PostgreSQL, pgAdmin, backend, frontend, docs-web.
  • Proposar configuracions .env per a cada entorn.
  • Esbossar pipelines de CI/CD:
    • build backend,
    • build frontend,
    • executar tests i migracions.
  • Documentar com desplegar en:
    • local,
    • entorn de proves,
    • producció.

Resultat esperat

  • Fragments o fitxers complets de:
    • docker-compose.yml,
    • Dockerfile (multi-stage),
    • workflows de CI (YAML).

7. Data Steward / Model de dades​

Responsabilitat principal

Dissenyar, revisar i millorar el model de dades i la qualitat de la informació.

Tasques típiques

  • Definir entitats de domini i esquemes SQL:
    • dances, songs, links, choreographers,
    • events, venues, locations,
    • classes, favorites, etc.
  • Definir constraints:
    • claus forànies,
    • polítiques ON DELETE,
    • NOT NULL i valors per defecte.
  • Proposar índexs per millorar cerques i rendiment:
    • GIN / pg_trgm,
    • índexs per dates, etc.
  • Assegurar que només es guarden:
    • metadades pròpies,
    • URLs cap a fonts originals (no contingut aliè complet).

Resultat esperat

  • Taules descrites textualment (DDL suggerit).
  • Propostes de migracions Flyway.
  • Notes a architecture/db-redesign-plan.md.

Com usar aquest document​

Quan treballis amb IA:

  1. Tria el rol que més encaixi amb la tasca (Arquitecte, Backend, Frontend, DevOps, etc.).
  2. Copia el prompt base i adapta’l:
    • posa ROL,
    • descriu breument el context i l’objectiu.
  3. Indica sempre:
    • noms de fitxers,
    • rutes,
    • entitats afectades,
    • si vols fitxer complet o només fragment.

Això ha de permetre que tots els assistents d’IA treballin alineats amb el mateix model mental del projecte LDP.

Claude Code (eina activa de desenvolupament)​

A partir de març 2026, el projecte utilitza Claude Code (CLI d’Anthropic integrada a VS Code) com a eina principal de desenvolupament assistit per IA.

Diferències respecte a ChatGPT​

  • Accés directe al codi: Claude Code llegeix i modifica fitxers del projecte
  • Executa comandes: git, mvn, npm, tests, Docker
  • Context automàtic: llegeix CLAUDE.md a cada sessió (no cal copiar context manualment)
  • Memòria persistent: manté context entre sessions via .claude/memory/
  • Slash commands: procediments estàndard a .claude/commands/ (invocables amb /project:nom)

Infraestructura de Claude Code al projecte​

.claude/
├── commands/               # Slash commands (/project:new-feature, /project:diagnostic, etc.)
├── knowledge/              # Coneixement operatiu (patterns.md, current-focus.md)
CLAUDE.md                   # Identitat, regles, convencions (auto-carregat)
.claudeignore               # Exclusions de seguretat

Regles de col·laboració​

Definides a CLAUDE.md secció "Regles de col·laboració". Claude Code actua com a partner de desenvolupament professional, no com a executor passiu. Totes les decisions tècniques es basen en estàndards professionals.