videoteca/CLAUDE.md

CLAUDE.md — regole di lavoro per l'IA su questo repo

1. Document-first: prima di scrivere codice, aggiorna il documento pertinente in docs/ (o crea un ADR). Poi implementa.
2. SSOT: non duplicare informazioni. Consulta docs/index.md per sapere dove vive ogni tema; negli altri file usa link.
3. ADR: ogni scelta tecnica rilevante → nuovo file docs/adr/NNNN-titolo.md (numerazione progressiva, mai riusata). Non modificare un ADR accettato: se la decisione cambia, crea un nuovo ADR che lo sostituisce e aggiorna lo stato del vecchio in Sostituito da NNNN.
4. Stato: a fine lavoro aggiorna docs/PROJECT_STATE.md e CHANGELOG.md (root).
5. Verifica: fatti su librerie/versioni/limiti vanno verificati su fonti ufficiali e citati nel documento (con data). Mai a memoria.
6. Decisioni aperte: non scegliere al posto dell'utente; elencale in docs/04-rischi-e-domande-aperte.md e chiedi.
7. Casi limite: per ogni modulo ragiona sui casi possibili (input vuoti, file corrotti, interruzioni, concorrenza, spazio disco) come farebbe uno sviluppatore senior, e documentali.
8. Costo zero: preferire soluzioni gratuite e self-hosted; se serve qualcosa a pagamento, verificare il costo reale e segnalarlo prima.
9. La struttura di docs/ può adattarsi al progetto: se serve un nuovo documento, aggiungilo a docs/index.md.

Contesto del progetto (non duplicare: i dettagli stanno nei link)

• Cos'è: web app locale per archiviare e guardare filmati per categoria/sottocategoria, con ripresa dal punto lasciato. Stack: PocketBase + frontend vanilla (ADR 0001, 0007). Stato: docs/PROJECT_STATE.md. Fase attuale: pre-M0, nessun codice.
• Lingua: documentazione, commit e risposte in italiano.
• Vincoli che non vanno violati senza nuovo ADR: un solo admin = superuser PocketBase, gli utenti con account possono solo guardare (ADR 0013); progresso e "visto" per utente (ADR 0008); filmati solo in categorie foglia (ADR 0010); originali conservati nell'MVP (N-06 in docs/01-vision-requisiti.md).
• Ogni modifica a una regola API o a un campo dati: aggiorna il modello in docs/02-architettura.md e ricontrolla i casi limite di accesso (un utente non deve vedere né scrivere i dati di un altro).
• Fatti su PocketBase/ffmpeg/codec/browser: verifica sulla documentazione ufficiale e cita URL e data nell'ADR (regola 5). Non assumere comportamenti a memoria (es. collection users predefinita: non confermata).
• Nuovo documento: aggiungilo a docs/index.md. Nuovo ADR: aggiungi la riga al registro in docs/index.md e usa il template docs/adr/0000-template.md.
• Alla chiusura di una domanda aperta (Q-xx): rimuovila da docs/04-rischi-e-domande-aperte.md, registra l'esito nel requisito o nell'ADR, aggiorna PROJECT_STATE.md e CHANGELOG.md.
• Segreti: nessuna password o token nel repo, nei log o nel changelog; il superuser si crea come da documentazione PocketBase (ADR 0012).
• Verifica dei link tra file .md dopo ogni modifica alla documentazione.