CLAUDE.md spiegato:il file che previene gli errori dell'AI

CLAUDE.md spiegato: è un file di testo semplice nella radice del tuo progetto che il tuo strumento di coding con AI legge prima di ogni risposta — e previene circa il 90% degli errori che l'AI commette nel tuo codice. Non è codice. È il regolamento: gli schemi del tuo progetto, i tuoi punti non negoziabili, gli errori che l'AI non deve mai ripetere.

La maggior parte di chi costruisce con l'AI non sa nemmeno che esiste. Ecco cos'è, perché cambia tutto e cosa mettere nel tuo.

CLAUDE.md spiegato: l'analogia del manuale del dipendente

Immagina di assumere un collaboratore esterno brillante che tra una riunione e l'altra soffre di amnesia totale. Ogni mattina arriva senza sapere nulla di come funziona la tua azienda — i tuoi standard, il tuo sistema di archiviazione, le tue decisioni passate. Ogni mattina gli rispieghi tutto, e ogni mattina commette gli stessi errori finché non lo fai.

Ora immagina di consegnargli un manuale del dipendente che rilegge all'inizio di ogni riunione. All'improvviso si presenta già conoscendo le tue regole.

Questo è CLAUDE.md. Gli strumenti di coding con AI iniziano ogni conversazione da zero — non ricordano le correzioni di ieri. CLAUDE.md è il manuale che leggono automaticamente prima di rispondere a qualsiasi cosa. Pensalo come la costituzione del tuo codice: le regole che l'AI deve seguire, gli schemi che deve usare, gli errori che non deve mai commettere.

Perché senza di esso l'AI continua a ripetere gli stessi errori

Ecco cosa è successo a me. Stavo costruendo un sistema di revisione delle candidature per la mia piattaforma — logica di punteggio complessa, flussi in più passaggi, decine di tabelle di database. Ho detto a Claude: "Costruisci il servizio di revisione delle candidature."

Claude ha generato il codice. Funzionava. Ed era sbagliato in cinque modi:

• Ignorava la struttura che ogni altra parte del mio codice segue
• Inventava definizioni di dati che non corrispondevano al mio vero database
• Aggiungeva una gestione degli errori in conflitto con il sistema che avevo già
• Usava un output di debug sbrigativo invece della mia configurazione dei log
• Dimenticava il multi-tenancy — l'etichetta del cliente che deve stare su ogni query

Ho corretto tutto a mano. Poi il file successivo che ho chiesto? Gli stessi errori. Di nuovo. Combattevo con Claude su ogni singolo file — non perché Claude sia scarso, ma perché aveva l'amnesia sulle regole del mio progetto. Senza CLAUDE.md riaddestri la tua AI da zero a ogni conversazione.

Il libroThe Solopreneur RevolutionLuis Gonçalves su come costruire un'attività da solopreneur con l'IA mentre sei ancora dipendente.Scopri il libro →

Cosa va in un file CLAUDE.md

Un buon CLAUDE.md ha sette sezioni. Nessuna richiede di scrivere codice — richiedono di enunciare decisioni, che è esattamente il lavoro dell'architetto:

Le sezioni più potenti sono le ultime due. L'AI è una macchina che riconosce schemi: mostrale un esempio reale di codice fatto bene e lo imiterà ovunque. Mostrale l'errore esatto che ha commesso la settimana scorsa, etichettato "non farlo mai", e l'errore sparisce.

Cosa è cambiato dopo aver scritto il mio

Stessa richiesta — "Costruisci il servizio di revisione delle candidature" — dopo aver aggiunto CLAUDE.md. Claude ha letto prima le regole, poi ha generato codice che seguiva la mia struttura, corrispondeva esattamente al mio database, etichettava ogni query per il multi-tenancy, gestiva gli errori a modo mio e metteva ogni file al posto giusto. Al primo tentativo. Zero correzioni.

Il momento in cui ho capito che era magia: mi serviva una funzionalità di abbinamento con i mentori — logica complessa, più tabelle. Prima di CLAUDE.md, significava ore a correggere l'output dell'AI. Dopo, ho detto "costruisci l'abbinamento dei mentori con gli stessi schemi della revisione delle candidature". Claude ha letto il regolamento, ha studiato la funzionalità precedente e ha costruito tutto seguendo ogni schema. Ci sono voluti 15 minuti e funzionava perfettamente.

Senza il file, aspettati circa 30 minuti di correzioni su ogni file generato — schemi sbagliati, protezioni mancanti, file nel posto sbagliato. Moltiplicalo per centinaia di file e CLAUDE.md è la differenza tra consegnare e annegare.

Come iniziare il tuo oggi

Non scrivere un capolavoro. Parti con cinque regole — i cinque errori che la tua AI continua a fare nel tuo progetto — più una riga che descrive cosa stai costruendo e il tuo stack tecnologico. Tutto qui.

Poi trattalo come un documento vivo. Ogni volta che l'AI fa un nuovo errore, aggiungi una regola. Ogni volta che genera qualcosa di ottimo, copia quel codice nella sezione degli esempi. Il punto ideale è tra 200 e 400 righe: sotto le 100 righe dà troppo poco contesto, oltre le 500 l'AI ci annega.

Un confine da conoscere: CLAUDE.md contiene le tue regole globali, sempre vere. Per le funzionalità grandi e una tantum ti servirà anche un brief specifico per il compito, con i requisiti esatti e il contesto di quella funzionalità — è uno strumento diverso, il metodo PRP, e i due lavorano insieme: la costituzione per ogni giorno, il progetto esecutivo per ogni costruzione.

12 settimaneLa carriera aziendale non è mai stata il pianoCandidati al Solopreneur Accelerator.Candidati ora →

Domande frequenti

Che cos'è un file CLAUDE.md?

Un file markdown (testo semplice) nella radice del tuo progetto che Claude Code legge prima di ogni risposta. Contiene le regole del tuo progetto, gli schemi, lo stack tecnologico, esempi di codice reali e anti-pattern — così l'AI segue i tuoi standard al primo tentativo invece di essere riaddestrata a ogni conversazione.

Devo saper programmare per scriverne uno?

No. Il file è scritto in italiano semplice: cos'è il prodotto, le regole che devono valere sempre, ciò che non deve mai succedere. Per la sezione degli esempi, incolli codice che l'AI stessa ha generato quando ha fatto qualcosa di giusto. Enunciare le decisioni è il lavoro del fondatore; implementarle è il lavoro dell'AI.

Quanto dovrebbe essere lungo un file CLAUDE.md?

Parti oggi con cinque regole. Fallo crescere verso le 200–400 righe — abbastanza lungo da contenere i tuoi schemi, abbastanza corto perché l'AI lo usi tutto. Sotto le 100 righe è troppo scarno; oltre le 500, sfoltisci. Rivedilo ogni settimana: aggiungi nuovi schemi, elimina le regole superate.

CLAUDE.md basta da solo per costruire funzionalità?

Copre le regole globali — gli errori che altrimenti si ripeterebbero su ogni file. Per una funzionalità complessa ti serve anche una specifica per il compito, con i requisiti esatti, i dati e i passaggi di validazione di quella funzionalità. È il metodo PRP; CLAUDE.md più un PRP è il modo per costruire le funzionalità bene al primo colpo.