docs(CLAUDE.md): riscrivi con regole operative e tabella file critici

Espande CLAUDE.md da 6 a ~80 righe per orientare Claude Code sulle convenzioni critiche del progetto: pipeline visiva, sincronizzazione soglie chunking su 3 file, coerenza EMBED_MODEL, skills custom.
2026-04-15 11:38:45 +02:00
parent 80bd563000
commit 94766d67cc
1 changed files with 78 additions and 11 deletions
@@ -1,19 +1,86 @@
 # CLAUDE.md — RAG from Scratch

-## Ambiente
+## Regole invarianti

-Questo progetto usa un **virtual environment Python**.
-Tutte le dipendenze e i comandi Python devono essere eseguiti nel venv.
+- **Lingua:** Rispondi sempre in italiano.
+- **Venv obbligatorio:** Usa `.venv/bin/python` o attiva con `source .venv/bin/activate`. Mai `pip`/`python` di sistema.
+- **Non modificare `raw.md`:** `step-2/<stem>/raw.md` è immutabile. La copia di lavoro è `step-4/<stem>/clean.md`.

-```bash
-# Creazione (una volta sola)
-python -m venv .venv
+---

-# Attivazione
-source .venv/bin/activate
+## Pipeline (ordine obbligatorio)

-# Installazione dipendenze
-pip install -r requirements.txt
+```
+PDF (sources/) → step-0 → step-1 → step-2 → step-3
+              → step-4 (CRITICO: revisione manuale clean.md)
+              → step-5 → step-6 → step-7 (Ollama) → step-8 → step-9
 ```

-Non installare mai pacchetti a livello di sistema con `pip install` senza venv attivo.
+Il parametro `--stem` identifica il documento (nome PDF senza `.pdf`). Lo stem è anche il nome della collection ChromaDB.
+
+Comandi tipici:
+```bash
+source .venv/bin/activate
+python step-4/revise.py --stem <stem>
+python step-5/chunker.py --stem <stem>
+python step-6/verify_chunks.py --stem <stem>
+python step-8/ingest.py --stem <stem>
+python step-9/rag.py --stem <stem>
+```
+
+---
+
+## File critici
+
+| File | Ruolo |
+|---|---|
+| `step-9/config.py` | Fonte di verità: `EMBED_MODEL`, `OLLAMA_MODEL`, `TOP_K`, `TEMPERATURE`, `SYSTEM_PROMPT` |
+| `step-5/chunker.py` | Chunking adattivo — `MIN_CHARS=200`, `MAX_CHARS=800`, `OVERLAP_S=2` |
+| `step-6/verify_chunks.py` | Verifica chunk — stesse soglie di `chunker.py` |
+| `step-6/fix_chunks.py` | Fix automatici su chunk anomali |
+| `step-4/revise.py` | Pre-processing MD automatico (8 trasformazioni euristiche) |
+| `step-8/ingest.py` | Vettorizzazione ChromaDB — legge `EMBED_MODEL` da `config.py` |
+| `step-9/rag.py` | Pipeline RAG interattiva |
+
+---
+
+## Regole di assistenza
+
+**Modifica `EMBED_MODEL` in `step-9/config.py`:**
+Avvisa sempre che serve rieseguire la vettorizzazione:
+```bash
+python step-8/ingest.py --stem <stem> --force
+```
+`ingest.py` importa `EMBED_MODEL` direttamente da `config.py` — la coerenza è critica: se violata non produce errori ma restituisce risultati insensati.
+
+**Modifica soglie chunking (`MIN_CHARS`, `MAX_CHARS`, `OVERLAP_S`):**
+I valori compaiono in tre file che vanno sincronizzati manualmente:
+1. `step-5/chunker.py`
+2. `step-6/verify_chunks.py`
+3. `step-6/fix_chunks.py`
+
+**Step 4 — revisione clean.md:**
+`revise.py` applica trasformazioni automatiche, ma il risultato va sempre revisionato a mano. La qualità del RAG dipende da `clean.md` più di qualsiasi parametro tecnico. Suggerisci sempre `/step4-review <stem>` dopo `revise.py`.
+
+**Step 6 — verifica chunk:**
+Dopo `verify_chunks.py`, usa `/step6-fix <stem>` prima di passare a step-8.
+
+---
+
+## Skills custom
+
+- `/step4-review <stem>` — Revisione qualitativa `clean.md`: artefatti, paragrafi spezzati, header errati.
+- `/step6-fix <stem>` — Dry-run e applicazione fix chunk tramite `fix_chunks.py`.
+
+---
+
+## Struttura directory per stem
+
+```
+step-2/<stem>/raw.md                ← immutabile
+step-4/<stem>/clean.md              ← copia di lavoro
+step-4/<stem>/structure_profile.json
+step-5/<stem>/chunks.json
+step-6/<stem>/report.json
+chroma_db/<stem>/                   ← collection ChromaDB
+```