Vai al contenuto
Cristalroi

AI per e-commerce

CLAUDE.md: che cos’è e come si scrive un file che funziona

È il primo file che vale la pena scrivere, e il più facile da rovinare allungandolo. Ogni riga pesa su ogni compito, anche quando non c'entra.

Di Gennaro Napoletano · 7 minuti di lettura

Scritto con l'aiuto dell'AI, riletto da Gennaro Napoletano.

Mano che spunta una lista su un quaderno accanto a un portatile: le istruzioni da tenere scritte

In breve

CLAUDE.md è un file di testo con le istruzioni che Claude Code legge all’inizio di ogni sessione. Deve contenere solo ciò che non si ricava dai file: i comandi di verifica, le decisioni prese, le trappole. La documentazione consiglia di restare sotto le 200 righe. Una regola scritta lì viene letta, ma non è un blocco: per quello servono permessi e hook.

Dove si mette il CLAUDE.md?

Dipende da chi deve seguirlo. Claude Code li carica tutti, dal più generale al più vicino alla cartella in cui lavori.

DoveVale perQuando viene letto
Cartella utente, ~/.claude/CLAUDE.mdTe, in tutti i progettiAll’avvio
Radice del progetto, CLAUDE.mdChi lavora al progetto: va in gitAll’avvio
CLAUDE.local.md nel progettoTe, in quel progetto: non va in gitAll’avvio
Una sottocartellaChi lavora lìQuando Claude legge o scrive un file lì dentro

Per partire c’è il comando /init, che ne prepara uno dai file del progetto: va poi tagliato, non solo letto. Se nel repository c’è già un AGENTS.md, usato da altri strumenti, Claude lo legge quando non trova nessun CLAUDE.md né CLAUDE.local.md.

Ricontrollato l’8 novembre 2026 su Claude Code 2.1.319.

Che cosa scriverci?

Solo ciò che Claude non può scoprire leggendo i file, o che ogni volta perderebbe tempo a riscoprire. Il resto occupa attenzione senza dare nulla.

SìNo
Il comando esatto per lanciare le proveL’elenco delle cartelle
Un punto in cui il codice ingannaRegole di stile già imposte da uno strumento
Una decisione che non si vede nei file, con il motivoLa cronologia delle versioni: sta in git
Ciò che hai già dovuto correggere due volteSpiegazioni generiche di una tecnologia
Dove stanno le credenzialiLe credenziali

Un esempio inventato, per un progetto che genera un feed:

# Feed del catalogo

Genera il feed per Merchant Center dal file catalogo.csv.

## Prove
Dopo ogni modifica: python test/verifica.py (deve dare 0 errori).

## Regole che il codice non dice
- I costi nel file del fornitore sono IVA esclusa: non togliere altra IVA.
- Il nome del negozio non va mai nei titoli: Google lo vieta.
- La cartella input/ non si modifica: i file li carica una persona.

Il motivo di una regola conta. «Non togliere altra IVA» è un divieto; «i costi sono già IVA esclusa» è un’informazione che aiuta anche nei casi non previsti.

Tablet su una scrivania, con una conversazione fatta di blocchi colorati senza scritte

I conti di un negozio non si indovinano

Claude può usare le tue definizioni di costo e margine solo se gliele scrivi. La pagina spiega come passargli i dati e dove i conti vanno ricontrollati.

Quanto può essere lungo?

La documentazione indica di restare sotto le 200 righe per file: un file lungo consuma contesto a ogni sessione, e le istruzioni vengono seguite peggio. Il file non viene tagliato, ma oltre la lunghezza consigliata Claude Code mostra un avviso all’avvio e in /status.

Per i file caricati su richiesta c’è invece un limite vero, dalla versione 2.1.309: con la finestra da 200.000 token sono 40.000 caratteri a file, oltre i quali Claude riceve solo l’inizio con una nota. Vale per i CLAUDE.md delle sottocartelle e per i file che questi importano, per le regole nelle .claude/rules/ delle sottocartelle e per quelle legate a un percorso. Con la finestra da un milione di token il limite sale a 150.000 caratteri sui modelli recenti.

Quando il file cresce ci sono tre strade, e nessuna richiede di buttare via nulla:

  • Regole legate a un percorso. In .claude/rules/ un file con paths: si carica solo quando si lavora su quei file.
  • Procedure in una skill. Il corpo si carica solo quando serve, come spiega la guida alle skill.
  • Documenti a parte, con un indice. Una riga dice quando leggere ogni file. Con @percorso, invece, il file viene importato e caricato sempre: non fa risparmiare contesto.

Attenzione a non aggirare il limite: cento righe da cinquemila caratteri pesano come mille righe normali.

Perché a volte non viene rispettato?

Perché è un testo che il modello legge, non un blocco. La documentazione distingue due tipi di istruzioni: quelle che il modello legge e decide come applicare, come richieste, CLAUDE.md e skill, e quelle che lo strumento applica comunque, come un hook o una regola di divieto.

Se vuoiUsa
Un’indicazione da seguire con giudizioCLAUDE.md
Che un file non venga mai lettoUna regola deny nei permessi
Che le prove partano a ogni modificaUn hook

Quando una regola viene ignorata, prima domanda: è stata caricata? /context mostra che cosa c’è nel contesto. Se non c’è, spesso hai aperto un’altra cartella. Se c’è, la regola è forse vaga o in contrasto con un’altra: un’istruzione funziona quando è abbastanza concreta da poter essere verificata. Altri casi sono nella guida agli errori comuni, e le regole che non ammettono eccezioni sono nella guida a hook e permessi.

Che cos’è la memoria automatica, e come si differenzia?

È fatta di appunti che Claude scrive da solo mentre lavora con te: correzioni, preferenze, stato dei lavori. Il CLAUDE.md lo scrivi tu, la memoria la scrive lui. Si caricano le prime 200 righe o 25 KB dell’indice MEMORY.md, e vale per il repository git: sottocartelle e copie separate la condividono.

Una regola vale in CLAUDE.md quando è una decisione del progetto; un appunto va bene in memoria quando è un dettaglio di come lavori. Il comando /memory apre i file e accende o spegne la memoria automatica.

Per un e-commerce il CLAUDE.md è il posto giusto per le definizioni che fanno sbagliare i conti: IVA inclusa o esclusa, che cosa entra nel costo del prodotto, quale margine si usa. Un modello non le può indovinare, come spiega la pagina su Claude per e-commerce. Se non hai ancora deciso quale margine usare, parti dalla differenza fra margine e ricarico.

Domande frequenti

Quante righe può avere un CLAUDE.md?

La documentazione consiglia di restare sotto le 200 per file. Non viene tagliato oltre quella soglia, ma ricevi un avviso e le istruzioni vengono seguite peggio.

Il CLAUDE.md va messo in git?

Quello di progetto sì, perché vale per chi ci lavora. CLAUDE.local.md no: contiene le tue preferenze personali per quel progetto.

Posso metterci password e chiavi?

No. Scrivi dove sono conservate, non il loro valore: il file viene letto a ogni sessione e, se è in git, resta nella storia.

Come faccio a sapere se è stato letto?

Con il comando /context, che mostra che cosa è caricato nella conversazione. Un CLAUDE.md di una sottocartella compare solo dopo che Claude ha letto un file lì dentro.

Fonti

Gennaro Napoletano, esperto di digital analytics e Google Tag Manager, sorride nella sede Google di Dublino

Gennaro Napoletano

Esperto di digital analytics e Google Tag Manager, da oltre 15 anni lavora sui dati degli e-commerce. Nel 2023 Google lo ha invitato nella sua sede di Dublino per i risultati di alcuni e-commerce gestiti da lui. Ha realizzato il portale di marginalità per e-commerce e aiuta aziende e agenzie a fidarsi dei propri numeri. Scopri chi è.

Continua a leggere

Come chiedere bene a Claude Code: richieste che funzionano

Che cosa scrivere a Claude Code, che cosa non serve spiegare, perché dargli una prova da lanciare e quando ricominciare: con esempi su feed e margini.

Skill di Claude Code: che cosa sono e come se ne crea una

Una skill è una procedura che Claude Code carica quando serve. Dove si mette, come si scrive la description e perché a volte non parte: con un esempio.

Hook e permessi di Claude Code: le regole che valgono sempre

Le modalità dei permessi, le regole allow, ask e deny, i file di impostazioni e gli hook: come far valere una regola senza dipendere dal modello.

Dai file ai tuoi numeri

Che cosa può fare Claude per chi vende online

Legge file, scrive formule e cerca fonti, ma i tuoi costi non li conosce. Ecco dove aiuta davvero, dove no e come passargli i dati.