CLAUDE.md e AGENTS.md: cosa scrivo dopo 42 progetti

Aggiornamento (9 novembre 2026): sono usciti Claude Fable 5.2 e Mythos 5.2 - prezzi, accesso e benchmark nella mia guida a Claude Fable 5.2.

👁 112 letture

Sul mio disco ho 42 file di istruzioni per agenti AI: 16 CLAUDE.md e 26 AGENTS.md, ciascuno nella cartella di un progetto diverso. Il più breve ha una riga, il più lungo 402. Quest’ultimo è il doppio della lunghezza consigliata da Anthropic: parto proprio da lì, perché mostra bene cosa finisce davvero in un file del genere.

Che cos’è CLAUDE.md

È un normale file Markdown che Claude Code legge all’inizio di ogni sessione. Ogni conversazione con l’agente parte da zero, quindi tutto ciò che non si può ricavare dal codice va spiegato di nuovo. CLAUDE.md lo fa per te: contiene i comandi per i test, le regole del progetto, ciò che l’agente non deve fare e gli ostacoli in cui ti sei già imbattuto.

La documentazione di Claude Code chiarisce che si tratta di contesto, non di una configurazione vincolante. Di solito l’agente segue le istruzioni del file, ma non è obbligato a farlo. Per bloccare davvero un’azione, per esempio cancellare file o distribuire un progetto su un server, servono hook e autorizzazioni nelle impostazioni, non una frase in CLAUDE.md.

Dove si trova e quali file vengono letti

Possono esserci più file contemporaneamente. Claude Code non ne sceglie uno solo: combina tutti quelli che trova, dal più generale a quello più vicino alla cartella di lavoro.

I file nelle cartelle sopra quella da cui avvii l’agente vengono letti subito. Quelli nelle sottocartelle vengono letti solo quando l’agente inizia a consultare o modificare file al loro interno. Così, in un grande repository, le istruzioni per il frontend non occupano spazio quando l’agente lavora sul database.

Puoi generare una prima versione con il comando /init. Claude esamina il codice e salva i comandi e le convenzioni che riesce a individuare. È un buon punto di partenza, ma io aggiungo sempre il resto a mano: le righe più preziose sono quelle che non si possono ricavare dal codice.

Il mio file più lungo: 402 righe

La documentazione consiglia di mantenere ogni CLAUDE.md sotto le 200 righe, perché un file più lungo consuma contesto e l’agente tende a seguirlo meno. Il mio file per il progetto Jantaris ha 402 righe e 46.095 byte. È l’unico dei miei 16 CLAUDE.md a superare la soglia; la mediana è di 35 righe.

Non è nato tutto in una volta. È cresciuto con gli ostacoli annotati dopo ogni errore: come il server mette in cache le immagini e perché sostituire un file mantenendone il nome fa sì che le persone vedano la modifica solo dopo una settimana; quante registrazioni all’ora consente il sistema di protezione e come i test devono azzerarlo; dove si trova il server e come viene gestita la posta. Ogni riga è la traccia di un problema concreto. Alla fine, però, il file è diventato troppo lungo.

La penso così: CLAUDE.md non è la documentazione del progetto, ma una mappa delle insidie. L’agente può trovare nel codice e nel README la descrizione del funzionamento dell’applicazione. In CLAUDE.md vanno messe le cose che non si vedono nel codice e che hanno già causato problemi. Quando il file supera le 200 righe, lo divido in file tematici dentro .claude/rules/. L’importazione con @file.md aiuta a tenere tutto in ordine, ma il file importato viene comunque caricato per intero.

Il file che mostro nel corso: 34 righe

Un buon esempio è il CLAUDE.md del progetto “Baza napraw”, un’applicazione per un’officina che stiamo costruendo da zero nel mio corso SaaS in un weekend con Claude Code. Ecco il file completo, senza tagli. Il testo qui sotto è la traduzione del materiale di test originale in polacco, non un nuovo test eseguito in italiano:

# Baza napraw - note per l’agente

Prodotto, schermate e regole: @SPEC.md
Costruisci solo la sezione OBBLIGATORIO di AMBITO.md. Aggiungi
le idee fuori ambito a PIÙ AVANTI, indicando quando riprenderle,
e chiedimi conferma.

## Stack
- Node 22.13+, nessuna dipendenza npm: node:http, node:sqlite, node:test, fetch.
- SQLite in data/app.db, migrazioni in migrations/NNN_nome.sql.
- HTML renderizzato sul server, JavaScript puro nel browser.

## Comandi
- npm run dev                 server sulla porta 8080, riavvio dopo le modifiche ai file
- npm test                    node --test "test/*.test.js" (glob tra virgolette)
- npm run reset               database da zero + dati di test + account di test
- python tools/zrzuty.py URL  schermate a 1440 px e 390 px in data/shots/

## Regole
- Importi in centesimi come INTEGER. Mai numeri in virgola mobile.
- Il server controlla i limiti dei piani (R1-R3). Il browser si limita a mostrarli.
- Ogni regola R di SPEC.md deve avere un test con il relativo numero nel nome.
- Salva i file di testo con terminatori di riga LF.
- Nei contenuti usa solo il trattino semplice "-". I test controllano tutti i template.

## Divieti
- Non leggere .env. Non distribuire il progetto. Non eseguire git push, git reset o git clean.
- Non eseguire test su data/app.db (i test usano un database in memoria).
- Non importare dati proprietari (Autodata, HaynesPro, portali dei produttori):
  licenze dei produttori e tutela delle banche dati nell’UE.

## Insidie
- Git Bash modifica i percorsi: imposta MSYS_NO_PATHCONV=1 prima dei comandi con /...
- Scrivi i file con espressioni regolari usando uno strumento per i file,
  non un heredoc in bash (le barre inverse vanno perse).

Ogni sezione ha una ragione precisa:

• Rimando alle specifiche. La descrizione del prodotto è in SPEC.md e CLAUDE.md si limita a importarla. L’istruzione di attenersi alla sezione OBBLIGATORIO mantiene l’agente entro i limiti del progetto. Senza, dopo un’ora potresti ritrovarti con funzionalità che nessuno aveva chiesto.
• Comandi con la sintassi esatta. Mettere il glob tra virgolette nel comando dei test è un dettaglio facile da trascurare, ma da cui dipende l’esecuzione di tutti i file di test.
• Regole verificabili. Importi in centesimi, limiti controllati dal server, un test per ogni regola. Niente formule vaghe come “scrivi codice pulito”, perché non si possono verificare.
• Divieti. Ripeto i più importanti anche nelle impostazioni delle autorizzazioni, perché il file da solo è solo una richiesta.
• Insidie dell’ambiente. Windows e Git Bash possono alterare i percorsi che iniziano con una barra. L’agente non lo sa finché un comando non fallisce.

La riga che mi è costata un ciclo di editing

Un esempio concreto lo mostra bene. Il 30 ottobre, durante la revisione dei testi della rivista DYGOT, uno script che recupera lo stato aggiornato dal server è stato avviato tra una modifica e il caricamento. Ha sovrascritto le modifiche locali e il primo ciclo di editing è andato perso. Da quel giorno, nel file di istruzioni di quel progetto c’è scritto: “Eseguilo SOLO prima di iniziare a lavorare: tra una modifica e il caricamento sovrascrive i tuoi cambiamenti”. Nessun generatore l’avrebbe scritto, perché dal codice dello script non si capisce quando è sicuro avviarlo.

AGENTS.md, lo stesso approccio per altri agenti

AGENTS.md è un file di istruzioni analogo, ma con un nome letto da diversi strumenti: Codex di OpenAI, Cursor, Gemini CLI, l’agente GitHub Copilot e una dozzina di altri. Il formato è gestito dalla Agentic AI Foundation presso la Linux Foundation. Ne ho 26: sono brevi, con una mediana di 8 righe, perché la maggior parte descrive singole attività grafiche per Codex.

Anche Claude Code sa leggere AGENTS.md, dalla versione 2.1.277. Per impostazione predefinita lo fa solo se nel progetto non esiste un file CLAUDE.md. Se sono presenti entrambi, Claude legge il suo e ignora AGENTS.md. Per far ricevere le stesse regole a entrambi gli strumenti, la soluzione più semplice è inserirle in AGENTS.md e aggiungere in CLAUDE.md una riga con l’importazione @AGENTS.md. Nel mio articolo come passare da Claude Code a Codex spiego come trasferire l’intera configurazione, comprese le skill e i server MCP.

Nei progetti su cui si alternano Claude e Codex, aggiungo un’altra regola alla fine del file: dopo il lavoro, scrivere una voce nel registro condiviso degli agenti, con la data, il nome dell’agente e l’elenco delle modifiche. L’agente successivo legge il registro prima di iniziare e sa cosa ha cambiato il precedente. È più semplice che sincronizzare la memoria dei due strumenti.

Cosa non inserisco

• Chiavi e password. Il file del progetto spesso finisce nel repository. Nei miei file troverai piuttosto il divieto di leggere .env, non il suo contenuto.
• La struttura delle cartelle. L’agente può scoprirla da solo in pochi secondi e la descrizione nel file invecchierebbe al primo cambiamento.
• Indicazioni vaghe. “Punta sulla qualità” non cambia nulla. “Ogni regola deve avere un test con il suo numero” sì.
• Regole in conflitto. La documentazione avverte che, in presenza di due istruzioni contraddittorie, Claude può scegliere liberamente. Ogni tanto rileggo i miei file ed elimino le regole non più valide.
• Note per le persone. Se devono restare, le inserisco in un commento HTML <!-- -->. Claude Code elimina questi commenti prima di leggere il file, quindi non consumano contesto.

Da dove iniziare

Se stai iniziando con Claude Code, non scrivere CLAUDE.md in anticipo. Esegui /init, tieni ciò che ha senso e aggiungi una riga ogni volta che l’agente ripete lo stesso errore. Dopo una settimana avrai un file che descrive il tuo progetto, non un progetto preso da una guida. Nel mio articolo Claude Code: installazione spiego come installarlo e muovere i primi passi; in quanto costa Claude Code parlo dei costi dei piani.

Nel corso SaaS in un weekend con Claude Code scriviamo passo passo le specifiche e CLAUDE.md: 30 lezioni, dalla verifica della domanda per un’idea fino a database, accesso, pagamenti e distribuzione su un server personale. Il corso fa anche parte del pacchetto kombAIn, insieme ad altri 27 corsi del laboratorio formativo.

Fonti e data di verifica

Situazione al 6 novembre 2026.

• File CLAUDE.md e AGENTS.md dei miei progetti: 42 file dopo aver escluso le copie e i repository di terzi, conteggiati il 6 novembre 2026
• Claude Code - documentazione: How Claude remembers your project (CLAUDE.md, AGENTS.md, importazioni, limite di 200 righe)
• AGENTS.md - descrizione del formato
• Laboratorio formativo - programma del corso SaaS in un weekend con Claude Code

// continua a leggereProgettare il bagno con l’AI: visualizzalo da una fotoGuideClaude Duet in Italia: non c’è ancora, cosa usareGuideKling 4.0 MCP e CLI: collegare Kling a Claude e ChatGPTGuide

Kinetyra