Dai contesto a Claude: CLAUDE.md e prompt migliori

Claude Code funziona bene fin da subito, ma diventa notevolmente più efficace una volta che conosce le convenzioni del tuo progetto e una volta che adotti alcune abitudini di prompt. Questa guida copre entrambi gli aspetti.

CLAUDE.md è un file markdown semplice che Claude legge automaticamente all'inizio di ogni sessione in quella directory. Pensalo come il briefing che daresti a un nuovo collega capace nel loro primo mattino: come il team fa le cose, cosa evitare e dove vivono i pezzi importanti.

Non è necessario fare riferimento ad esso nei prompt o allegarlo manualmente. Se il file esiste, Claude l'ha già letto.

Claude cerca in alcuni posti e unisce quello che trova, dal generale allo specifico:

La maggior parte dei team ha bisogno solo del file nella radice del progetto. Committalo su git in modo che l'intero team ne benefici.

CLAUDE.md viene letto una volta, all'inizio della sessione, e inserito verbatim nel prompt di sistema di Claude. Non c'è riassunto o troncamento, e non viene riletto dal disco ad ogni turno; lo stesso contenuto rimane in contesto per l'intera conversazione. Se modifichi il file durante la sessione, il cambiamento non ha effetto fino a quando non inizi una nuova sessione.

Per i clienti Claude for Enterprise, il quadro dei costi è migliore di quanto "caricato ad ogni richiesta" potrebbe suggerire. Claude Code applica il prompt caching di Anthropic al prompt di sistema, che include CLAUDE.md. La prima richiesta in una sessione paga il prezzo completo dei token di input per il file; le richieste successive entro circa cinque minuti l'una dall'altra colpiscono la cache e vengono fatturate al tasso molto più basso di lettura della cache. La cache è indirizzata per contenuto, quindi qualsiasi modifica a CLAUDE.md l'invalida e la richiesta successiva paga il prezzo completo di nuovo.

In pratica questo significa che un CLAUDE.md considerevole costa token completi una volta per sessione, più una volta dopo qualsiasi pausa di inattività abbastanza lunga da far scadere la cache, piuttosto che una volta per messaggio. Vale comunque la pena mantenere il file snello per lo spazio della finestra di contesto e il rapporto segnale-rumore, ma non è necessario razionare le righe puramente per controllare la spesa per messaggio. Nel dashboard di utilizzo di Enterprise, l'impronta del file apparirà quasi interamente come token di lettura della cache piuttosto che token di input standard.

In qualsiasi progetto, digita /init. Claude esplorerà la base di codice e preparerà un CLAUDE.md per te, coprendo comandi di build, comandi di test, una panoramica della struttura e tutte le convenzioni che rileva. Rivedi la bozza, rimuovi tutto ciò che è inesatto e committalo. Questo richiede circa cinque minuti e ripaga permanentemente.

Punta a un file che sia breve e denso di segnale—poche centinaia di righe al massimo. Ogni riga viene caricata in contesto ad ogni richiesta, quindi ognuna dovrebbe valere il suo costo.

Vale la pena includere:

Non vale la pena includere:

Trattalo come un documento di onboarding vivo, non come una specifica.

Puoi anche aggiungervi durante la sessione: digita # seguito da un'istruzione (ad es. # usa sempre async/await, mai .then()) e Claude ti offrirà di aggiungerla al CLAUDE.md giusto per te.

Questi non sono suggerimenti generici di prompt engineering; sono le abitudini che contano di più specificamente quando Claude sta leggendo e modificando una vera base di codice.

Claude può esplorare la base di codice stesso. Digli cosa vuoi e perché, e lascia che scopra dove.

❌ "Apri userService.ts, trova la funzione validate, aggiungi un controllo null alla riga 42."

✅ "Gli utenti senza email stanno causando il crash del passaggio di validazione. Fallo gestire gracefully e aggiungi un test."

Incolla la traccia dello stack completa piuttosto che riassumerla. Il nome file esatto, il numero di riga e il messaggio sono quello che permette a Claude di trovare la posizione giusta rapidamente.

Per qualsiasi cosa che tocchi più di un paio di file, premi Shift+Tab in Plan Mode e chiedi:

"Pianifica come aggiungeresti il rate limiting all'API pubblica. Non cambiare nulla ancora."

Rivedi il piano, regolalo nella conversazione, poi cambia modalità e di' "fai il passaggio 1." Questo cattura i malintesi prima che si trasformino in un diff di dodici file.

Claude può cercare nella base di codice da solo, ma se conosci già il file rilevante, dillo — è più veloce e usa meno token. Usa @ per fare riferimento ai percorsi, ad esempio @src/auth/login.ts.

Gli esempi includono "i test passano," "corrisponde allo stile degli altri handler," o "nessuna nuova dipendenza." Dichiarare i criteri di accettazione in anticipo è più efficiente di diversi round di revisione.

Le sessioni lunghe accumulano rumore. Quando passi da "correggi il bug di login" a "refactorizza il modulo di fatturazione," esegui /clear e ricomincia da capo. Il tuo CLAUDE.md porta il contesto durevole in avanti, quindi la cronologia della chat non ha bisogno di farlo.

Se la prima risposta è sbagliata, non è necessario riformulare l'intera richiesta. Semplicemente di' cosa c'è di sbagliato — ad esempio, "Questo cambia l'API pubblica; mantieni la firma uguale." Claude manterrà tutto il resto e regolerà solo quel punto.