Files

T

davide 94766d67cc 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:51 +02:00

3.0 KiB

Raw Blame History

CLAUDE.md — RAG from Scratch

Regole invarianti

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.

Pipeline (ordine obbligatorio)

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

Il parametro --stem identifica il documento (nome PDF senza .pdf). Lo stem è anche il nome della collection ChromaDB.

Comandi tipici:

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:

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:

step-5/chunker.py
step-6/verify_chunks.py
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

3.0 KiB Raw Blame History