From d9f16f28441e9bad18f770e2a4d87a9876893aee Mon Sep 17 00:00:00 2001 From: Davide Grilli Date: Tue, 22 Sep 2026 14:13:07 +0200 Subject: [PATCH] Regola in CLAUDE.md: i doc si aggiornano nello stesso commit del codice docs/ descrive il programma com'e' adesso, non com'e' stato: e' la prima cosa che si legge per capirlo, quindi un doc che racconta un comportamento che non esiste piu' fa prendere decisioni sbagliate - e' peggio di un doc mancante. Aggiunta la regola, la tabella di quale doc ospita cosa, e la richiesta di annotare anche il sintomo quando il cambiamento nasce da un fallimento di Creo: i suoi messaggi non nominano ne' il file ne' la causa, e senza quel ponte la volta dopo si riparte da zero. --- CLAUDE.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index eb66c52..517fc18 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -36,6 +36,31 @@ i test possono chiamare direttamente `Indexer.ParseFilename` e `AssemblyComponentScanner.EstraiCodiciReferenziati` senza esporli come API pubblica. +## Documentazione: va tenuta allineata + +`docs/` non è un archivio di note storiche: descrive **il programma com'è adesso**, ed è la +prima cosa che si legge per capirlo. Ogni modifica strutturale — un passo in più o in meno nel +flusso delle fasi, un nuovo modo di leggere il `.asm`, un cambio nello schema del DB o nel +criterio con cui si sceglie un file — va riflessa nei doc **nello stesso commit** del codice, +non "dopo". Un doc che descrive un comportamento che non esiste più è peggio di un doc +mancante: fa prendere decisioni sbagliate. + +Dove scrivere cosa: + +| Doc | Contenuto | +|---|---| +| `CLAUDE.md` (questo file) | il flusso essenziale e i punti che si sbaglierebbero senza saperli | +| [`docs/architettura.md`](docs/architettura.md) | il processo delle 5 fasi e la mappa file-per-file | +| [`docs/formato-asm-record.md`](docs/formato-asm-record.md) | parser esatto dei record `.asm`, con §7 per i casi limite | +| [`docs/formato-asm.md`](docs/formato-asm.md) | euristica testuale di fallback | +| [`docs/db-cad-index.md`](docs/db-cad-index.md) | schema e vista di `cad_index.db` | +| [`docs/copia-raw-parallela.md`](docs/copia-raw-parallela.md) | parallelizzazione della copia in `raw/` | + +Quando il cambiamento nasce da un fallimento reale di Creo, scrivere anche **il sintomo**: i +messaggi di Creo non nominano il file o la causa, e senza quel ponte la prossima volta si +riparte da zero (i §7.3/§7.4/§7.5 di `formato-asm-record.md` sono l'esempio del formato +atteso). + ## Architettura Il programma è tutto in `PrepStep/` (nessun altro progetto nella solution). Dettaglio