Come configurare CLAUDE.md nel 2026: modello e 6 regole

Materiali sul vibe coding: strumenti, casi di studio, errori. Guide di Ailoot.

Perché ti serve CLAUDE.md e perché senza di esso Claude dimentica il progetto?#

Apri Claude Code martedì e spieghi: «Sto lavorando a questo progetto, questi sono gli strumenti, non fare questo». Funziona.

Giovedì quella stessa chat è già terminata, quindi ripeti tutto. Sabato, di nuovo; lunedì, ancora una volta.

Ecco com’è lavorare con un agente senza CLAUDE.md: ogni nuova finestra è uno stagista che parte da zero, a cui devi ripetere le stesse cose più e più volte. Prima passavo 5-10 minuti a digitare questo riepilogo iniziale per ogni sessione. I prompt diventavano lunghi perché dovevo riportare manualmente tutto il contesto. E il risultato restava generico: l’agente non conosceva il mio pubblico, i miei numeri economici né i miei principi.

Con un CLAUDE.md aggiornato, il riepilogo iniziale scompare. Tutte le regole che ripetevi in ogni chat sono in un unico file e compaiono automaticamente all’inizio di ogni sessione. Il prompt diventa breve: «fai X», invece di «sto lavorando al progetto Y, gli strumenti sono Z, non fare A o B e, già che ci sei, ricordati anche C».

Poi smettono di ripetersi gli stessi errori.

Ogni errore dell’agente è un motivo per aggiungere una riga a CLAUDE.md. Dopo un mese, avrai una «costituzione del progetto» viva e Claude smetterà di cadere nelle stesse trappole ricorrenti.

E c’è un terzo livello: l’agente smette di scrivere nel vuoto. Tramite CLAUDE.md, indirizzo Claude verso cartelle con informazioni di contesto: dove trovare dati sul pubblico, sui prezzi e sul branding. Senza questo instradamento, l’agente scrive «soluzioni di alta qualità» senza conoscere i miei numeri economici, perciò risultano astratte, stereotipate e «uguali a tutte le altre».

Che cos’è CLAUDE.md e in quale ordine lo legge Claude?#

Anthropic descrive così CLAUDE.md nella documentazione ufficiale:

Le quattro posizioni in cui Claude Code cerca CLAUDE.md, in ordine crescente di priorità:

Tutti e quattro i file vengono caricati nel contesto contemporaneamente. Se le regole sono in conflitto, Anthropic afferma direttamente nella documentazione che non è noto quale prevarrà; Claude potrebbe sceglierne arbitrariamente una. È quindi più semplice tenere tutto ciò che è fondamentale nel CLAUDE.md del progetto ed evitare duplicati.

C’è un dettaglio tecnico di cui quasi nessuno parla, ma che spiega molti comportamenti strani.

In altre parole, CLAUDE.md non è un «prompt di sistema» in senso stretto. È il primo messaggio dell’utente che Claude vede. Le sue regole sono quindi forti raccomandazioni, non leggi. Se una regola richiede applicazione forzata, usa un hook provato per l’evento coperto e permessi o isolamento per il confine più ampio di accesso. L’esecuzione automatica non rende completi i controlli di un hook. Più avanti spiegherò il confine tra hooks e CLAUDE.md.

Come scrivere un CLAUDE.md minimo in 5 minuti (modello pronto all’uso)?#

Di seguito trovi un modello che ho testato in decine di miei progetti. Mantiene il file intorno a 80-120 righe, entro la raccomandazione Anthropic di puntare sotto le 200 righe. Con questo modello, l’agente fornisce i risultati più sensati.

# [PROJECT NAME] - project navigation

This document is the project map. Read it at the start of every session
to understand where things are and how to work with them.

## What this project is

**[NAME]** - [one sentence: what it is and who it’s for].
[1-2 sentences: what problem it solves and how].

Details are in `business/INDEX.md`.

## Reading order at the start of every session

1. `about-me/INDEX.md` - who I am and how I think
2. `business/INDEX.md` - what we do (product, audience, economics)
3. `CLAUDE.md` (this file) - repo rules, tools, navigation
4. Task area: the relevant file from `business/`, `plans/<current plan>`,
   `mastery/<area>` or the feature folder in the code

Principle: layer 1 (about me) comes before layer 2 (business) for a reason.
First, **who** is thinking, then **about what**.

## Repository structure

[NAME]/
├── CLAUDE.md            ← this file, navigation
├── about-me/            ← digital projection of you (how you think, what you value)
│   └── INDEX.md
├── business/            ← the business’s second brain
│   ├── INDEX.md
│   ├── audience/        ← customer profile
│   ├── products/        ← products, prices
│   ├── goals/           ← goals, metrics
│   └── economics/       ← unit economics, revenue
├── plans/               ← technical plans (one plan = one feature)
├── retrospectives/      ← reflections after each session
└── (project code)

### Where to find things

| What you need | Where to look |
|---|---|
| Why we’re building the project, and for whom | `business/INDEX.md` |
| Target customer, pains, desires | `business/audience/` |
| Product, plans, prices | `business/products/` |
| Goals and metrics | `business/goals/` |
| Economics | `business/economics/` |
| Technical plans | `plans/` |

## Tools

[INSERT TOOLS - for example: Next.js 14, TypeScript, Tailwind CSS, Prisma + PostgreSQL].

## Repo rules

1. Never hardcode dynamic data (prices, dates, figures) -
   get everything from files in `business/` and the LIVE marker.
2. Don’t publish without my explicit command.
3. Before `git push`, run `npm run build` and check that it
   builds without errors or warnings.
4. Add files by name with `git add`. Never use `git add .` or `git add -A`.
5. Don’t read `.env` in full. To check a variable, use
   `grep "^VAR=" .env`.

## Big features = a plan in `plans/`

Any task lasting more than an hour must be written up as a plan in the `plans/` folder:
1. Filename: `YYYY-MM-DD-feature-name.md`.
2. Divide the plan into phases. Mark each phase `[ ]` or `[x]`.
3. At the end of the plan, add a summary: whether it was fully implemented and what remains.

## End-of-feature cycle

After each feature is complete, go through these 5 steps:
1. Find errors → prove them with an example → fix them.
2. What was missed (edge cases, input validation, error handling).
3. Is this a real problem in our project? Check `business/` and `plans/`.
4. Take a fresh look: reread the diff as if you’re seeing it for the first time.
5. Security review. Especially: personal data and third-party materials.

## End-of-session reflection

In `retrospectives/YYYY-MM-DD_short-name.md`, record:
1. What the task was.
2. How it was solved.
3. Whether it was solved - yes / no / partially.
4. What could have been done better.
5. What was learned about the user or project.

## Language

Always respond in the user’s preferred language. Use hyphens only, not em dashes.

Per far compilare automaticamente questo modello a Claude per il tuo progetto, forniscigli questo prompt. Leggerà il contesto e compilerà i campi tra parentesi quadre:

Create a CLAUDE.md file at the project root using this template:

[INSERT THE ENTIRE TEMPLATE FROM ABOVE]

Proceed as follows:

Read about-me/INDEX.md and business/INDEX.md to understand the project context and me as the author.

Fill in all the square-bracketed fields in the template based on what you find in those folders.

If some information is missing, ask me clarifying questions one at a time, with 3-4 answer options.

Punta a mantenere il CLAUDE.md risultante sotto 200 righe. Se è più lungo, esamina duplicati e sposta procedure dettagliate in file collegati. Conserva regole essenziali su pianificazione, riflessione e repository, poi provale su attività rappresentative.

Show me the final file and ask what should be revised.

Always respond in the user’s preferred language.

Se non hai ancora le cartelle about-me/ e business/, va bene lo stesso. Claude ti farà domande di chiarimento e preparerà un CLAUDE.md minimo basandosi su ciò che è disponibile. Potrai creare le cartelle più avanti, quando saprai cosa inserirvi.

Quali 6 regole rendono CLAUDE.md un documento vivo?#

Regola 1. Mantienilo sotto le 200 righe

Anthropic lo dice in modo conciso nella documentazione ufficiale:

Un CLAUDE.md lungo è controproducente per due motivi. Primo, consuma token. Un file di istruzioni di 800 righe viene caricato in ogni finestra e usa diverse migliaia di token dal tuo budget a ogni sessione. Con un abbonamento Pro e un limite giornaliero, questo riduce sensibilmente il numero di sessioni disponibili. Secondo, il modello inizia a ignorare le regole.

La documentazione consiglia di puntare sotto le 200 righe per ridurre il contesto e migliorare l’aderenza. Non dimostra un confine netto di fallimento alla riga 201. Esamina pertinenza, contraddizioni, token caricati e risultati effettivi prima di decidere cosa spostare.

Regola 2. Concludi ogni sessione con una riflessione

Scrivi in CLAUDE.md: «Al termine di ogni sessione, registra ciò che hai fatto e imparato in retrospectives/YYYY-MM-DD_*.md». Una volta aggiunta questa riga, Claude inizierà a concludere ogni sessione con una riflessione senza che tu debba chiederglielo.

Perché riflettere:

• Due settimane dopo puoi aprire una vecchia retrospettiva e ricordare perché hai scelto quella strada.
• Quando torni al progetto dopo un mese, hai già una mappa delle decisioni recenti.
• Se lavori in team, un collega può leggere la retrospettiva e capire lo stato attuale in 2 minuti, senza fare una chiamata.

Regola 3. Crea un commit dopo ogni attività completata

Il mio CLAUDE.md dice: «Dopo ogni attività completata, crea un commit git con un messaggio significativo». Claude inizia da solo a suddividere il lavoro in commit atomici.

Questo ti dà due vantaggi. Primo, se qualcosa si rompe, puoi annullare una singola operazione, non «tutto quello che ho fatto oggi». Secondo, la cronologia dei commit diventa un registro del lavoro che mostra cosa è cambiato e in quale ordine.

Regola 4. Consulta sempre la cartella business/

Per qualsiasi attività che coinvolga clienti, prodotti o testi, l’agente dovrebbe prima aprire business/INDEX.md e il file pertinente indicato lì. Il mio CLAUDE.md dice esplicitamente: «Quando lavori sull’interfaccia utente o sui testi, consulta prima business/audience/avatar.md e business/assets/brand-guidelines.md».

Senza questa regola, Claude scrive testi «nello stile generale di un sito web di qualità». Con la regola, i testi rispecchiano il tuo stile, si rivolgono ai tuoi clienti ed evitano le parole vietate.

Regola 5. Aggiungi una regola dopo ogni errore dell’agente

Questa è la regola fondamentale per mantenere vivo CLAUDE.md.

Esempi dal mio CLAUDE.md, aggiunti dopo errori specifici:

• «Non includere mai i file WIP di altri con git add .: aggiungi i file allo staging uno per volta, indicandone il nome».
• «Prima di inviare modifiche a main, controlla git log origin/main..main --oneline: se l’output non è vuoto, non inviarle».
• «Non inventare valori: ricavali da .env o dal codice. Soprattutto URL, nomi utente e token».

Ognuna di queste righe è la traccia di un incidente specifico. Una volta un agente ha incluso il branch incompleto di un collaboratore. Una volta ho incluso commit di qualcun altro che non erano ancora stati inviati. Una volta un agente ha inventato un URL inesistente. Ogni errore diventa una regola e impedisce che la stessa ferita autoinflitta si ripresenti.

Regola 6. Inserisci le regole di sicurezza in .claude/settings.json, non in CLAUDE.md

In CLAUDE.md puoi scrivere «non toccare .env», ma è solo una richiesta: Claude potrebbe violarla perché CLAUDE.md viene caricato come messaggio dell’utente, non come una legge. Per la sicurezza critica, usa .claude/settings.json, dove puoi bloccare determinati comandi in modo rigoroso.

La lista di blocco che aggiungo a ogni nuovo progetto:

• rm -rf (eliminazione ricorsiva di qualsiasi file).
• Lettura integrale di .env (Read .env).
• export e curl nello stesso comando (una modalità per far trapelare segreti all’esterno).
• git push --force senza approvazione esplicita.

Trovi altre guide su Ailoot.

Come è strutturato CLAUDE.md in un’attività reale (anatomia di un file di 280 righe)?#

La maggior parte degli esempi di CLAUDE.md online sono modelli tecnici per sviluppatori: «Usa TypeScript», «Non scrivere test più lunghi di 50 righe». Per un imprenditore, un CLAUDE.md del genere è inutile: non copre gli aspetti aziendali.

Di seguito trovi la struttura del mio CLAUDE.md operativo. Ho rimosso le regole specifiche e i percorsi perché riflettono le mie attività interne. Ma struttura e logica delle sezioni si possono applicare a qualsiasi progetto: inserisci le tue circostanze e otterrai un file operativo.

1. Breve descrizione del progetto (15 righe). Cosa facciamo, a chi ci rivolgiamo e quali prodotti offriamo. Non un riepilogo del sito di marketing, ma una sintesi per l’agente, così capisce «dove stiamo andando».

2. Su di me (10 righe). Un riferimento alla cartella about-me/: una proiezione digitale del mio modo di pensare. Tono, valori, principi, parole vietate. Quando Claude scrive testi «come se fossi io», consulta prima questa cartella per rispecchiare la mia voce.

3. Struttura del repository (20 righe). Un albero con commenti: dove si trova il codice, dove sono le informazioni aziendali, dove si trovano piani e retrospettive. Senza questa mappa, Claude cerca i file alla cieca ogni volta.

4. Tabella «Dove trovare le cose» (25 righe). Instradamento da «domanda → file». Per esempio, per un’agenzia immobiliare potrebbe indicare «ti servono i termini del mutuo → business/products/mortgage.md» oppure «ti serve il tono di voce dei post → business/assets/voice.md». Sostituisci gli esempi con i tuoi file. Questa tabella è il cuore di CLAUDE.md. Senza, l’agente indovina quale file contiene la risposta. Con, va direttamente alla fonte.

5. Principi fondamentali del progetto (40 righe, 10-15 voci). Questa sezione si arricchisce lentamente e richiede più impegno. Ogni voce è la traccia di un errore specifico. Per un negozio online, per esempio, le regole potrebbero essere «non inserire mai prezzi e tempi di consegna fissi nel codice», «non pubblicare un prodotto senza un comando esplicito» e «prima di pubblicare una scheda prodotto, controlla lo stile nel glossario del brand». Questa sezione è la «costituzione del progetto».

6. Pianificazione operativa (20 righe). Una tabella di trigger che associa «frase dell’utente → azione». Per esempio: «Quando dico “pianifica la settimana”, apri ops/monthly.md e crea il file della settimana». Così Claude diventa un assistente operativo che capisce il contesto dei comandi.

7. Strumenti (5 righe). Tecnologie. In breve, senza fronzoli.

8. Pubblicazione (15 righe). Una procedura passo passo per pubblicare le modifiche in produzione: quali comandi eseguire, in quale ordine e cosa controllare. Prima dovevo spiegarlo ogni volta. Ora Claude lo sa.

9-12. Sicurezza (35 righe). Quattro sottosezioni distinte: regole per lavorare con .env, accesso al database di produzione, comandi sicuri per le dimostrazioni (registrazioni dello schermo, streaming, schermate, per evitare di esporre accidentalmente i token) e regole per ruotare i segreti.

13. La cartella plans/ (10 righe). Lo standard dei piani: nome del file, struttura delle fasi e contenuto del riepilogo finale.

14. La cartella retrospectives/ (5 righe). Lo standard delle riflessioni: modello, nome del file e contenuti previsti.

15. Dati dal database in tempo reale (15 righe). Una regola per contrassegnare i «dati aggiornati»: quando un file richiede cifre attuali, l’agente le recupera dalla fonte anziché usare quelle vecchie. Così si evita che Claude usi i dati di ieri.

16. Lingua (3 righe). «Rispondi sempre nella lingua preferita dall’utente. Usa solo trattini, non trattini lunghi».

Circa 280 righe in totale. Superano l’obiettivo di concisione senza invalidare il file. Nell’esempio restava utile: conservarlo deve dipendere dal consumo di contesto misurato e da verifiche rappresentative. Le tabelle non costano automaticamente meno token della prosa.

Che cosa fa il comando /init e perché non basta?#

Anthropic descrive così il comando nella documentazione:

Cosa fa bene /init:

• Identifica gli strumenti in package.json, Cargo.toml e pyproject.toml.
• Elenca i comandi di build e test.
• Rileva le convenzioni dai file esistenti (.eslintrc, .prettierrc).
• Rileva le regole Cursor esistenti (.cursorrules, .cursor/rules/) e le regole Copilot e ne incorpora le parti pertinenti. Rileva AGENTS.md in modalità CLAUDE_CODE_NEW_INIT=1.

Cosa non farà /init:

• Non saprà chi è il tuo cliente.
• Non includerà le parole vietate per i testi.
• Non aggiungerà regole sugli errori dell’agente, perché non ce ne sono ancora stati.
• Non creerà una tabella «dove trovare le cose» per la struttura della tua attività.

Quindi, il flusso di lavoro corretto è:

1. Esegui /init in Claude Code

   Otterrai un CLAUDE.md iniziale di 30-50 righe con strumenti e comandi. È la base tecnica.

2. Aggiungi il modello dell’articolo

   Usa la sezione «Un CLAUDE.md minimo in 5 minuti». Aggiungi sezioni per la navigazione, l’instradamento e i principi.

3. Compila i campi tra parentesi quadre

   Chiedi a Claude di «leggere il mio progetto e compilare il modello». Se non esistono le cartelle business/ e about-me/, Claude ti farà domande di chiarimento.

4. Fai uno stress test

   Di’ a Claude: «Leggi il mio CLAUDE.md e trova 10 ambiguità che potrebbero portarti, come agente, a fraintendermi». Otterrai una lista di correzioni.

5. Poi usa il file nel lavoro quotidiano

   Aggiungi una riga dopo ogni errore dell’agente. Dopo un mese avrai un CLAUDE.md operativo, adattato alla tua attività.

Prompt per il quarto passaggio:

I have a CLAUDE.md. Tomorrow I’ll be building a feature based on it.

Your task is to stress-test it. Find 10 reasons we could potentially fail:

where CLAUDE.md is ambiguous and you, as an agent, might misunderstand it

where there are gaps that would force you to make things up

where rules contradict one another

where I overestimate how much can be done in one day

where I underestimate things (this is even worse)

Don’t hold back. Criticize it harshly. I want to find these issues now, not in production.
At the end, give me a list of specific changes: what to change and how, so these problems don’t happen.

CLAUDE.md vs AGENTS.md vs MEMORY.md: chi legge cosa nel 2026?#

La domanda che confonde di più chi inizia è: Claude Code legge AGENTS.md? Prima di settembre 2026 la risposta era «no»: la documentazione di Anthropic consigliava di creare un CLAUDE.md che importasse AGENTS.md. Dalla versione 2.1.277 (rilasciata il 18 settembre 2026), Claude Code legge direttamente AGENTS.md, ma solo se nella cartella di lavoro o nelle directory superiori non c’è un CLAUDE.md, .claude/CLAUDE.md o CLAUDE.local.md.

Se il progetto ha un CLAUDE.md, Claude Code legge solo quello per impostazione predefinita e ignora AGENTS.md. Puoi cambiare questa impostazione in /config, sotto Project instructions: per esempio, il parametro claude-md-and-agents-md gli fa leggere entrambi i file. C’è anche un altro metodo, valido in tutte le versioni: aggiungi un’importazione a CLAUDE.md:

@AGENTS.md

## Claude Code

Additional rules for Claude Code that other agents don’t need.

La sintassi @filename importa un altro file. Claude lo legge e lo carica nel contesto insieme a CLAUDE.md. L’importazione non fa sì che il file venga letto due volte, anche se Claude Code è già in grado di leggere AGENTS.md autonomamente.

Quando serve AGENTS.md. Se lavori in parallelo con Claude Code e Codex CLI, Cursor o Copilot, crea un AGENTS.md come unica fonte di verità, inserisci @AGENTS.md in CLAUDE.md e aggiungi le eventuali regole specifiche per Claude. Se non hai regole specifiche, non serve creare CLAUDE.md: dalla versione 2.1.277 Claude Code leggerà direttamente AGENTS.md. Se lavori solo con Claude Code, non ti serve AGENTS.md: usa un unico CLAUDE.md. Per vedere tutte le opzioni passo passo, consulta la guida per usare AGENTS.md e CLAUDE.md nello stesso progetto.

Che cos’è MEMORY.md? Dopo un aggiornamento recente, Claude Code conserva automaticamente note su di te in ~/.claude/projects/<project-name>/memory/MEMORY.md. Tra queste ci sono abitudini conversazionali («l’utente preferisce risposte brevi»), frasi ricorrenti («ha vietato le emoji nel codice») e osservazioni sul comportamento («lavora su macOS, usa zsh»).

È un sistema di memoria separato, non CLAUDE.md. Non lo scrivi tu: lo scrive Claude in base alle tue conversazioni. Se MEMORY.md contiene qualcosa che dovrebbe diventare una regola, spostala in CLAUDE.md. Se contiene informazioni inutili o sbagliate, puoi eliminarle manualmente: è un file di testo.

Qual è una dimensione utile per CLAUDE.md e come rivedere un file lungo?#

In ogni finestra di Claude Code, vengono caricati nel contesto diversi livelli: il prompt di sistema di Anthropic (stimato in decine di migliaia di token), il tuo CLAUDE.md, i file importati con @, MEMORY.md, la cronologia della chat corrente e il contenuto dei file aperti da Claude. Tutto deve rientrare nel contesto del modello (200K token per Sonnet, 1M per Opus).

Più CLAUDE.md cresce, meno spazio resta per il lavoro corrente. Un file di 1.000 righe equivale a circa 8.000 token, ripetuti a ogni sessione. Con un abbonamento Pro (nella mia esperienza, circa 10-12 prompt «intensi» al giorno), questo riduce la tua capacità di un quarto.

Il costo è solo un aspetto. L’aderenza può peggiorare con istruzioni lunghe, irrilevanti o contraddittorie; non esiste un numero universale di istruzioni seguite in modo affidabile. Prova attività rappresentative che esercitino le regole critiche, registra i fallimenti e confronta il comportamento dopo una modifica mirata.

Ecco quindi una regola pratica sulla dimensione:

• 80-120 righe: una gamma iniziale comoda per una mappa concisa, non un punteggio garantito di aderenza.
• 150-200 righe: un invito a rivedere la pertinenza e spostare procedure dettagliate in file collegati.
• 200-300 righe: esamina token, duplicati e risultati; l’esempio aziendale da 280 righe può ancora funzionare.
• 400+ righe: un forte motivo per una revisione mirata, non prova di inutilizzabilità. Conserva i vincoli essenziali e sposta dettagli dopo aver verificato regole e collegamenti.

Il solo numero di righe non dimostra successo o fallimento. Dopo la modifica ripeti le stesse attività rappresentative e verifica le regole importanti, senza inventare percentuali di conformità.

Anthropic propone un test diretto nella documentazione:

Applicalo a ogni riga. Se la risposta è «continuerebbe a fare la cosa giusta», elimina la riga. CLAUDE.md non è il posto per documentazione, cronologia delle decisioni o filosofia. Serve soltanto a dare all’agente le regole necessarie per evitare errori.

Quali 7 errori rendono inutile CLAUDE.md?#

Errore 1. «Sii un bravo ingegnere»

L’errore più comune. Le persone scrivono desideri generici in CLAUDE.md: «scrivi codice pulito», «usa le best practice», «pensa come un ingegnere senior».

Queste parole non significano nulla. Claude scrive già «codice pulito» in senso generale. Queste righe occupano spazio nel contesto senza influire su alcuna decisione.

Sostituisci «scrivi codice pulito» con «usa l’indentazione di 2 spazi», «non usare any in TypeScript» o «le funzioni non devono superare 30 righe». Regole specifiche e verificabili.

Errore 2. Ripetere ciò che Claude già sa

Descrizioni delle convenzioni standard dei linguaggi («in JavaScript le funzioni sono oggetti di prima classe», «TypeScript è tipizzato staticamente»). Spiegazioni del funzionamento di npm, git o docker.

Claude ha imparato tutto questo durante l’addestramento. Ripeterlo in CLAUDE.md non aggiunge nulla: consuma solo il tuo contesto.

Errore 3. Istruzioni lunghe e passo passo in CLAUDE.md

Istruzioni lunghe su «come distribuire il progetto», «come scrivere una migrazione del database» o «come configurare un nuovo componente». Decine di righe passo passo.

Questo non è il posto per istruzioni lunghe passo passo. È il posto per regole di una riga. Inserisci le istruzioni lunghe in skills/ (un meccanismo separato di Claude Code che si carica quando serve) o in docs/. In CLAUDE.md usa un rimando di una riga: «Quando crei una nuova migrazione, apri docs/migrations.md».

Errore 4. Regole già verificate da un analizzatore automatico del codice

«Usa i punti e virgola», «non lasciare importazioni inutilizzate», «non usare var». ESLint, Prettier e Biome rilevano già tutto: sono linter (strumenti automatici di controllo del codice).

Un linter è deterministico: viene eseguito, trova un errore e lo corregge. Una regola in CLAUDE.md è probabilistica: l’agente può dimenticarla. Non c’è bisogno di duplicarla, è più semplice configurare il linter.

Errore 5. Segreti in CLAUDE.md

Ho visto password di account di test, token API per sandbox e link a pannelli di amministrazione autenticati. Tutto in un file salvato in git e caricato nel contesto del modello di Anthropic.

Mai. I segreti appartengono a .env, che è in .gitignore. Al massimo, CLAUDE.md dovrebbe dire: «Non leggere tutto .env; usa grep per una variabile specifica».

Errore 6. CLAUDE.md di oltre 500 righe, usato come deposito di appunti e mai ripulito per sei mesi

CLAUDE.md è cresciuto, duplica metà di docs/, si contraddice in diversi punti e nessuno ricorda cosa contiene. L’agente inizia a ignorarne gran parte. Il team si lamenta che «Claude non segue le istruzioni» e aggiunge altre regole, peggiorando la situazione.

Segnali che CLAUDE.md è trascurato: più di 300 righe, regole ripetute in sezioni diverse, link obsoleti a file che non esistono più e note «storiche» come «nel 2024 abbiamo deciso di fare così, poi abbiamo cambiato idea».

La soluzione: ogni due settimane, chiedi a Claude di rivederlo usando il test di Anthropic: «Se questa riga fosse rimossa, l’agente commetterebbe un errore?». Elimina tutto ciò per cui la risposta è «no».

Errore 7. CLAUDE.md creato e poi dimenticato

È l’opposto dell’errore precedente. Il file è stato creato una volta, due mesi fa, e da allora non è più stato toccato. Nel frattempo, gli strumenti sono cambiati, sono state aggiunte nuove cartelle e sono emersi nuovi errori dell’agente. CLAUDE.md non sa nulla di tutto questo perché nessuno lo ha aggiornato.

Un segnale rivelatore: ripeti la stessa istruzione in ogni sessione. «Non fare X», «non toccare Y», «ricordati Z». Se l’hai ripetuta più di due volte, la regola deve stare in CLAUDE.md, non nella tua testa.

Come rendere CLAUDE.md capace di apprendere con una regola di «aggiornamento a fine sessione»?#

Il mio CLAUDE.md ha una breve sezione:

## Self-learning

At the end of every session, check:
- Have I learned anything new about the user or how to work with them?
- Did I break any rule that should now be recorded?

If so, create or update a file in `about-me/feedback/` in this format:
Rule (one-line rule) → Why (why it was added)
→ How to apply (when it applies).

I don’t write the rules by hand - I say, “not like that, because this is how,”
and you put it into a file.

Dopo aver aggiunto questa sezione a CLAUDE.md, Claude ha iniziato a chiedere alla fine di ogni sessione: «C’è qualcosa di nuovo che vale la pena registrare?». Se c’era, proponeva una bozza di regola; io la chiarivo e veniva creato un file.

Dopo due mesi di lavoro in questo modo, ho più di due dozzine di file in about-me/feedback/, con regole apprese da errori specifici. Ogni file è una pagina nel formato Regola → Perché → Come. La cartella è diventata una «seconda memoria» che registra le mie preferenze e i miei tabù personali.

Ogni errore non si ripete perché diventa una regola, e le regole si accumulano e si rafforzano a vicenda. Dopo sei mesi, Claude conosce il mio progetto meglio di quanto io lo ricordi dopo una pausa di un mese.

Come aggiungere regole legali, marketing e operative a CLAUDE.md?#

Per la maggior parte dei team, CLAUDE.md è un documento puramente tecnico: strumenti, comandi di build, convenzioni di programmazione. È utile, ma rappresenta solo un terzo del valore.

Quando un imprenditore mantiene CLAUDE.md, ha senso aggiungere sezioni aziendali. Le tre più importanti sono:

Regole legali (per mercati regolamentati)

Se pubblichi testi in un settore regolamentato (finanza, medicina, pubblicità di farmaci, prodotti per bambini), le parole vietate hanno rilevanza legale e appartengono a CLAUDE.md sotto forma di regole esplicite. Non nella testa di qualcuno, non in una schermata dell’editor: in un file che l’agente vede a ogni sessione.

Esempio per un progetto fintech senza licenza bancaria:

Nota redazionale: quanto segue mostra il formato di una regola interna per un progetto specifico. Non costituisce un’autorizzazione generale a usare i termini elencati: l’accettabilità di un’affermazione dipende dalla legge applicabile e dallo status della società.

🚨 CRITICO - sono vietate le formulazioni finanziarie. Nei materiali rivolti ai clienti, non usare: «deposito», «rendimento garantito» o «prodotto di investimento». Usa: «conto di risparmio», «rendimento atteso» e «prodotto a tasso variabile». Il motivo sono i requisiti legali applicabili alla pubblicità dei servizi finanziari per questo progetto.

Questo blocco in CLAUDE.md fa una cosa semplice: ogni volta che chiedi a Claude di scrivere testi rivolti ai clienti, l’agente li verifica rispetto a questi divieti. Senza la regola, le parole vietate spuntano in una campagna su tre. Con la regola, ti dimentichi che esistono.

Lo stesso approccio funziona per:

• Progetti medici (niente affermazioni secondo cui qualcosa «cura» o «guarisce»).
• Pubblicità di farmaci (niente affermazioni «più efficace»; avvertenze obbligatorie).
• Qualsiasi settore regolamentato con proprie regole pubblicitarie.

Stile di marketing e formato dei testi

Se pubblichi testi regolarmente (social media, newsletter, siti web), conviene documentarne il formato in un paragrafo di CLAUDE.md. Ecco un esempio di cosa potrebbe scrivere un influencer o un’agenzia che gestisce un canale di messaggistica:

Quando scrivi post per il canale, consulta style/posts.md. Usa i marcatori di formattazione consentiti dal canale ed evita i caratteri speciali «pericolosi». Concludi con una CTA dotata di tag UTM secondo questa convenzione: utm_source=<channel>&utm_medium=<type>&utm_campaign=<slug>.

Claude scriveva post «nello stile generale di un sito di marketing». Ora segue il tuo formato, usa i tuoi UTM e non lascia trasparire che i testi sono stati scritti dall’IA.

Abitudini operative

Tabelle di trigger. Quando pronunci una frase specifica, l’agente sa quali file aprire e quali azioni eseguire. Ecco un esempio per un team che pianifica settimana per settimana:

«Pianifica la settimana» → apri ops/monthly.md, crea YYYY-WNN.md nella stessa cartella e sposta le attività da ops/backlog.md nei giorni appropriati. «Cosa c’è nel backlog?» → leggi ops/backlog.md e mostra le attività in un elenco. «Chiudi la settimana» → compila la sezione «Riepilogo della settimana» nel file della settimana corrente.

Con tabelle così, Claude passa da «assistente che scrive codice» a «operatore» che conosce le routine della tua attività. Ogni lunedì dico «pianifichiamo la settimana» e Claude apre i file giusti, legge gli obiettivi mensili e suggerisce come suddividerli.

Come verificare CLAUDE.md con una lista di controllo in 12 punti in 5 minuti?#

1. Dimensione. È conciso, con circa 200 righe come obiettivo di revisione anziché soglia di successo o fallimento?
2. Nome. Si chiama esattamente CLAUDE.md, con le lettere maiuscole, e non claude.md?
3. Posizione. Si trova nella directory principale del progetto o in ./.claude/CLAUDE.md?
4. Descrizione del progetto. Le prime 5 righe chiariscono cos’è il progetto e a chi si rivolge?
5. Strumenti. Le tecnologie sono elencate esplicitamente e senza fronzoli?
6. Struttura. C’è uno schema del repository con spiegazioni?
7. Instradamento. C’è una tabella «domanda → file» che mostra dove trovare le risposte?
8. Principi. C’è una sezione con regole che iniziano con «mai» e «sempre»?
9. Specificità. Ogni regola è verificabile? («Usa 2 spazi», non «scrivi in modo elegante».)
10. Aggiornamento autonomo. C’è una regola per «controllare cosa aggiungere alla fine della sessione»?
11. Riflessione. C’è una regola per «registrare il riepilogo della sessione in retrospectives/»?
12. Sicurezza. I divieti fondamentali (.env, rm -rf) sono inclusi anche in .claude/settings.json?

Se hai più di cinque risposte «no», apri Claude e forniscigli questo prompt:

Leggi il mio CLAUDE.md e confrontalo con questa checklist. Per ogni voce indica sì / no / in parte e cosa correggere.

Checklist:

Abbastanza compatto per il compito; revisione intorno alle 200 righe senza limite rigido

Descrizione del progetto nelle prime 5 righe

Strumenti elencati esplicitamente

Schema della struttura del repository

Tabella «domanda → file»

Sezione dei principi con regole

Ogni regola specifica e verificabile

Regola di aggiornamento alla fine della sessione

Regola di riflessione alla fine della sessione

Divieti critici inclusi in .claude/settings.json

Nessun duplicato della stessa regola in sezioni diverse

Nessun collegamento a file inesistenti

Dopo l’audit indica modifiche specifiche che rendano il file utile e aggiornabile.

Che cosa usare dopo CLAUDE.md: Plan Mode, Skills o sub-agents?#

CLAUDE.md è il fondamento. Quando funziona, puoi aggiungere tre meccanismi di Claude Code che si rafforzano a vicenda.

Plan Mode. Una modalità in cui Claude crea prima un piano delle modifiche, aspetta la tua approvazione e solo dopo inizia a lavorare. Attivala con Shift+Tab o con il comando /plan. Risolve il principale punto dolente del vibe coding: «Ho chiesto a Claude di correggere una cosa e ha riscritto metà del progetto». In Plan Mode non succede: vedi il piano prima che l’agente tocchi qualsiasi file.

Skills. File .md separati nella cartella .claude/skills/ che contengono conoscenze per uno specifico tipo di attività. Per esempio, una skill «come scrivere una migrazione del database» include una procedura specifica, un modello ed esempi. Queste informazioni non sono in CLAUDE.md perché sono troppo ampie. Quando Claude incontra un’attività come «scrivi una migrazione», carica la skill pertinente e la segue.

Sub-agents. Quando un’attività richiede molto contesto (per esempio, la revisione di una funzionalità ampia), Claude può avviare un sub-agent separato nel proprio contesto pulito. Il sub-agent svolge il lavoro e restituisce il risultato senza appesantire il contesto della chat principale.

Tutti e tre i meccanismi usano CLAUDE.md come punto di ingresso: lo leggono all’inizio del lavoro per capire il contesto del progetto. Ecco perché funzionano male anche queste funzionalità senza un CLAUDE.md aggiornato. Prima il fondamento, poi gli strati successivi.

Prossimo passo. Crea un file CLAUDE.md nella directory principale del progetto, copia il modello all’inizio dell’articolo e compila i campi tra parentesi quadre usando il prompt di supporto. Poi usa il file nel lavoro quotidiano: trasforma ogni errore dell’agente in una nuova riga. Dopo due o tre settimane, CLAUDE.md smetterà di essere «un documento scritto e dimenticato» e diventerà qualcosa che Claude consulta davvero a ogni sessione.

Se vuoi costruire un framework completo intorno a CLAUDE.md - una cartella business/ per un Secondo Cervello, una cartella about-me/ per una proiezione digitale di te, skill di base e una Plan Mode configurata - segui i passaggi e gli esempi di questo articolo. Guide di Ailoot.

Continua con Ailoot.