CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Cos'è questo repository

Non è un progetto software: è un vault Obsidian gestito con il pattern llm-wiki (raw → wiki, sorgenti immutabili → pagine sintetizzate), applicato a un dominio di ingegneria meccanica. Non ci sono build/lint/test: l'unico "lavoro" è ingest di documenti grezzi e mantenimento delle pagine wiki.

Il layer .llm-wiki/ (project.json, file-snapshot.json, file-change-queue.json, history/) è gestito da un'app esterna che traccia le modifiche a purpose.md, schema.md e wiki/*.md. Non modificare questi file JSON a mano: si aggiornano da soli quando l'app rileva un cambiamento.

I tre livelli

raw/ — sorgenti immutabili. Non modificare mai un file dentro raw/ dopo l'ingest: se un dato è sbagliato o mal estratto, la correzione va fatta nella pagina wiki (con nota sul problema), non nel raw.
- raw/sources/ — un sottocartella per documento sorgente (vedi convenzione sotto)
- raw/assets/ — immagini/scan/figure autonome non legate a un output MinerU
wiki/ — pagine generate/curate da Claude, organizzate per tipo secondo schema.md (entities/, concepts/, sources/, queries/, comparisons/, synthesis/, più index.md, log.md, overview.md).
purpose.md / schema.md — regole. purpose.md definisce l'ambito e le domande guida del progetto; schema.md definisce come sono strutturate le pagine e le convenzioni di naming/frontmatter. Leggi entrambi prima di ogni sessione di ingest.

Convenzione per `raw/sources/`

Ogni documento sorgente vive in raw/sources/<slug-documento>/, dove <slug-documento> è un kebab-case descrittivo (es. iso-6336-gear-rating, catalogo-skf-cuscinetti-2024). Dentro:

l'output originale così com'è (markdown + eventuali images/, *_content_list.json, ecc.) — non spostare o rinominare i file interni prodotti dal parser, altrimenti si rompono i link relativi alle immagini
se il documento arriva come PDF puro senza markdown, il PDF stesso

Questa cartella è la unità minima di provenienza: ogni claim scritto in wiki/ deve poter essere ricondotto a uno slug in raw/sources/.

Ingest di un nuovo documento in `raw/`

Quando trovi materiale nuovo (o non ancora processato) in raw/sources/:

Identifica il tipo di documento: norma/standard (ISO, UNI, DIN...), datasheet/catalogo produttore, paper/articolo tecnico, capitolo di libro, report interno, manuale. Il tipo guida quali pagine wiki creare (uno standard e un datasheet produttore, per esempio, diventano entity diverse con campi diversi).
Valuta la qualità dell'estrazione prima di fidarti del testo (vedi sezione MinerU sotto). Se il documento è scansionato o processato in modalità pipeline, non trattare l'OCR come verità assoluta senza controllo.
Estrai entità e concetti: componenti/materiali/norme/produttori → wiki/entities/; fenomeni, metodi di calcolo, teorie → wiki/concepts/; il documento stesso → una pagina in wiki/sources/.
Segui schema.md per frontmatter, naming e wikilink [[slug]]. Non inventare tipi di pagina o convenzioni diverse.
Aggiorna wiki/index.md (nuove voci) e wiki/log.md (una riga sotto la data odierna che descrive cosa hai ingerito e le pagine toccate). Questi due si aggiornano ad ogni ingest, senza bisogno che l'utente lo chieda.
Se il documento contraddice materiale già presente, segui la sezione "Contradiction Handling" di schema.md (nota sulla pagina concept/entity coinvolta, crea/aggiorna una query page, risolvi con una synthesis solo quando hai abbastanza evidenza).

wiki/overview.md non si aggiorna ad ogni ingest (diventerebbe rumoroso e incoerente riscritto un documento alla volta). Aggiornalo solo a checkpoint più ampi:

l'utente lo chiede esplicitamente ("aggiorna l'overview"),
dopo un batch di più documenti correlati appena ingeriti,
quando emerge un cambiamento reale nella thesis/scope del progetto (vedi purpose.md).

In quei casi riscrivi overview.md come sintesi corrente dello stato della wiki (cosa copre, cosa manca, thesis aggiornata), non come changelog — quello è il ruolo di log.md.

Note su MinerU (backend "pipeline")

Molti documenti in raw/sources/ arrivano pre-processati con MinerU in modalità pipeline (parsing layout+OCR tradizionale, non VLM). Questo backend è più leggero ma ha limiti noti di cui tenere conto durante l'ingest:

Ordine di lettura: su layout multi-colonna o tabelle complesse l'ordine dei blocchi estratti può essere sbagliato. Se un paragrafo non ha senso nel punto in cui compare, verifica se appartiene a una colonna/sezione diversa prima di citarlo.
Formule: convertite in LaTeX via OCR, possono contenere simboli sbagliati (es. confusione tra l/1/I, apici/pedici persi, segni persi). Non riportare una formula tecnica in una pagina wiki senza controllo visivo minimo di plausibilità (unità di misura coerenti, termini noti).
Tabelle: rese come markdown/HTML, possono avere celle disallineate o merge di celle perse. Trattare i valori numerici tabellari come "da verificare" se la tabella sembra irregolare.
Header/footer/note a piè di pagina: a volte finiscono interfogliati nel corpo del testo. Non trattarli come parte del discorso principale.
Immagini: estratte come crop in images/ e referenziate con path relativi nel .md — non toccare i path.

Regola pratica: quando una pagina wiki riporta un dato numerico, una formula o una specifica tecnica presa da un documento in pipeline mode, se il punto è dubbio aggiungi una nota inline tipo (da verificare: OCR pipeline mode, layout tabellare irregolare) invece di ometterla silenziosamente o presentarla come certa.

Checklist import da output MinerU grezzo

Un output MinerU tipico (cartella <nome>/auto/) contiene molti file: solo una parte va copiata in raw/sources/<slug>/.

Tenere:

<nome>.md — testo
<nome>_content_list.json (o _v2, sceglierne uno solo) — blocchi strutturati con page_idx/img_path, utile per citare pagine
images/ — cartella intera, referenziata dal .md con path relativi tipo images/<hash>.jpg
<nome>_origin.pdf — opzionale, solo se vuoi poter riaprire il PDF originale per verificare formule/tabelle dubbie (spesso decine di MB: valuta se vale lo spazio)

Scartare (debug/intermedi della pipeline, senza valore per la wiki, spesso centinaia di MB in totale):

_layout.pdf, _span.pdf — PDF di debug con overlay dei bounding box
_middle.json — struttura intermedia pre-assemblaggio, ridondante rispetto a content_list.json
_model.json — output grezzo dei modelli di detection

Passaggi:

Crea raw/sources/<slug-kebab-case>/ (lo slug identifica il documento, es. costruzioni-di-macchine-9 — non serve rispecchiare il nome file originale)
Copia dentro solo i file "da tenere", eliminando il livello intermedio auto/
Non rinominare images/ né i file interni copiati: i path relativi (images/<hash>.jpg) non dipendono dal nome della cartella padre, quindi rinominare la cartella-slug è sicuro, rinominare i singoli file è inutile e rischioso se non si aggiornano anche i riferimenti nel .md/.json.

Regole generali

Non modificare mai i file dentro raw/.
Non modificare i file JSON dentro .llm-wiki/.
Ogni pagina wiki nuova va aggiunta a wiki/index.md; ogni sessione di lavoro va loggata in wiki/log.md.
Usa [[wikilink]] per collegare le pagine tra loro, non link markdown relativi.
Lingua di default per le pagine wiki: italiano (i nomi di tipo/frontmatter restano in inglese come da schema.md, es. type: entity).

7.6 KiB Raw Blame History