CLAUDE.md e AGENTS.md: cosa sono, cosa scriverci e perché l'agente ignora le regole

Cosa sono CLAUDE.md e AGENTS.md

Sono normali file Markdown nella radice del repository, che l'agente carica automaticamente nel contesto all'inizio della sessione. Attraverso di essi comunichi all'agente ciò che non può ricavare dal codice da solo: come avviare l'ambiente, con quali comandi verificare il lavoro, quali regole del progetto non sono negoziabili e dove si trova la documentazione dettagliata.

CLAUDE.md è il file che legge Claude Code. AGENTS.md è un formato aperto con la stessa idea, supportato da molti agenti di programmazione. Se il team usa agenti diversi, conviene tenere il contenuto principale in AGENTS.md e rimandare a esso da CLAUDE.md. Claude Code supporta l'importazione di un altro file tramite @:

# CLAUDE.md
@AGENTS.md

Così le regole vivono in un solo posto e non divergono tra due file.

Come l'agente legge questi file

Il contenuto del file di istruzioni entra nella finestra di contesto del modello insieme al prompt di sistema e vi resta per tutta la sessione. Ne derivano tre conseguenze importanti.

• Ogni riga occupa spazio nel contesto. Il file viene letto per intero a ogni avvio, anche se per il compito attuale serve solo un decimo del suo contenuto.
• Non sono regole eseguite, ma testo. Il modello le considera insieme al resto del contesto e nulla garantisce il rispetto al cento per cento. I divieti assoluti vanno rinforzati con meccanismi: verifiche, hook, permessi di accesso.
• I file possono essere annidati. Claude Code carica il CLAUDE.md della radice del progetto e quello in ~/.claude/; quelli nelle sottocartelle vengono caricati quando l'agente lavora con i file di quelle cartelle. Così le regole di un modulo possono stare accanto al modulo.

Cosa scrivere in CLAUDE.md e AGENTS.md

Un buon file di istruzioni è una mappa, non un manuale. Risponde alle domande che l'agente farebbe a un collega esperto il primo giorno.

1. Come costruire e verificare il progetto

È la sezione più preziosa. Comandi concreti che l'agente deve eseguire prima di dire "fatto": test, linter, controllo dei tipi, avvio dell'ambiente. Senza di essi l'agente verifica "a occhio".

2. Vincoli rigidi

Un elenco breve di ciò che non si può violare in nessun caso: invarianti di sicurezza e di dati. Formulali come invarianti, non come istruzioni di implementazione: "tutte le query SQL sono parametrizzate", non "usa questa funzione in questo file".

3. Mappa del progetto

Dove si trova cosa: qualche riga sulla struttura delle cartelle e su dove cercare i dettagli. Per ogni tema importante, un link a un documento separato che l'agente aprirà solo quando si occuperà di quell'argomento.

4. Dove vive lo stato del lavoro

Dove guardare per riprendere da dove si era fermata la sessione precedente: file di piano, registro di avanzamento, backlog. È la cura per l'"amnesia" dell'agente tra una sessione e l'altra.

Cosa non scrivere

• Ciò che l'agente apprende dal codice. L'elenco delle dipendenze sta in package.json o pyproject.toml, la struttura delle classi nel codice stesso.
• Consigli generici. "Scrivi codice pulito", "fai attenzione" non cambiano il comportamento e occupano solo spazio.
• La storia del progetto e note una tantum. "A marzo siamo passati da MySQL 5.7" non serve al compito attuale.
• Istruzioni dettagliate per compiti rari. La procedura di deploy o di migrazione dei dati serve una volta a settimana: spostala in un documento separato o in una skill.
• Segreti. Il file sta nel repository e va interamente al modello. Token e password vanno solo nelle variabili d'ambiente.

Perché l'agente ignora una regola scritta nel file

Storia tipica: l'agente ha sbagliato, è stata aggiunta una regola nel file. Ha sbagliato di nuovo, è stata aggiunta un'altra regola. Dopo alcuni mesi il file ha centinaia di righe e una regola di sicurezza fondamentale viene violata come se non esistesse. Di solito le cause sono quattro e agiscono insieme.

File gonfio

Un file di 600 righe equivale circa a 10.000–20.000 token. La finestra di contesto sembra enorme, ma deve contenere anche codice, output dei comandi e cronologia della conversazione. Più le istruzioni occupano spazio, meno attenzione ottiene ogni regola e meno spazio resta per il compito stesso.

Regola in mezzo

I modelli linguistici usano in modo nettamente più debole le informazioni che si trovano al centro di un testo lungo rispetto a quelle all'inizio e alla fine. Una regola alla trecentesima riga di seicento si trova nel punto più debole.

Nessuna priorità

Un divieto non negoziabile e una nota passeggera sullo stile sono scritti allo stesso modo, come una riga in un elenco. L'agente non ha modo di capire quale conti di più. Se nel file ci sono tre regole di stile in contrasto, il comportamento cambia in modo casuale da un'esecuzione all'altra.

Degrado

Aggiungere una regola non costa nulla, eliminarla fa paura: "e se qualcosa dipende da essa?" Così il file cresce in continuazione e la quota di righe utili diminuisce. Conviene misurarlo come rapporto segnale/rumore: quante righe servono davvero per un compito tipico e quante no?

La soluzione: un router al posto del muro di testo

Correggere una sola causa non basta: se accorci il file ma non ne cambi la struttura, le regole restano mescolate. Funziona un insieme di misure.

1. Trasforma il file d'ingresso in un router. 50–150 righe: comandi di verifica, vincoli rigidi, mappa del progetto e link ai documenti tematici.
2. Sposta i temi in file separati. Per esempio docs/agents/deploy.md, docs/agents/database.md. L'agente li apre quando servono. In Claude Code, per le procedure ricorrenti, sono utili le skills: si caricano solo quando necessarie.
3. Porta in alto ciò che è critico. I vincoli rigidi all'inizio del file, in un blocco breve con l'indicazione esplicita MUST.
4. Elimina le contraddizioni. Per ogni tema, una sola regola. Se c'è un'eccezione, scrivila accanto alla regola.
5. Rinforza la regola con un meccanismo. Se la violazione non è ammissibile, il testo non basta. Serve una verifica che la intercetti: linter, test, hook pre-commit, hook dell'agente o un divieto a livello di permessi.
6. Revisiona regolarmente. Fissa un limite di righe e, a ogni aggiunta, chiediti che cosa si può eliminare o spostare altrove.

Regola o verifica?

Esempio di AGENTS.md compatto

# AGENTS.md — backend dei pagamenti (FastAPI, PostgreSQL)

## MUST — non violare
- Gli importi sono int in centesimi, mai float
- SQL solo parametrizzato, niente f-string
- Non modificare le migrazioni applicate, solo aggiungerne di nuove
- I segreti si leggono solo dalle variabili d'ambiente

## Verifica prima di dire "fatto"
docker compose up -d     # ambiente
make lint                # ruff + mypy
make test                # pytest
make e2e                 # scenario dell'ordine
Unit test verdi senza e2e non significano "fatto".

## Mappa
- app/payments/   — calcolo importi, sconti, webhook dei provider
- app/api/        — gestori HTTP
- tests/e2e/      — scenari dell'utente
Dettagli: docs/agents/architecture.md, docs/agents/database.md

## Stato del lavoro
- PLAN.md      — obiettivo attuale, criteri di completamento, prossimo passo
- PROGRESS.md  — cosa è stato fatto e come verificato, vicoli ciechi
- BACKLOG.md   — cose notate per strada: annotale qui, non correggerle ora

Alla fine della sessione aggiorna PROGRESS.md e il prossimo passo in PLAN.md.

Nota anche ciò che non c'è: l'elenco delle librerie, i consigli di stile, la storia del progetto. Tutto questo si deduce dal codice, è fissato da verifiche oppure sta nei documenti tematici.

Amnesia tra le sessioni: file di istruzioni e file di piano

Il file di istruzioni descrive come lavorare nel progetto, ma non che cosa sta succedendo adesso. Per questo serve un file di stato separato, che l'agente legge all'inizio e aggiorna alla fine della sessione. Vi devono comparire: l'obiettivo, il lavoro svolto con l'indicazione di come è stato verificato, le decisioni prese con le relative motivazioni, le alternative scartate e una sola formulazione del prossimo passo. Il controllo di qualità è semplice: apri una nuova sessione, scrivi "continua" e verifica se l'agente inizia un lavoro utile senza fare domande.

Non confondere i due file. Le istruzioni cambiano raramente e riguardano tutti i compiti. Il piano cambia a ogni sessione e riguarda solo il compito attuale. Se i due si mescolano, il file di istruzioni si riempie rapidamente di note superate.

Come verificare che il file funzioni

Anche il file di istruzioni va verificato. Prendi alcuni compiti tipici — una correzione di bug, una piccola funzionalità, un refactoring — e osserva che cosa fa l'agente senza suggerimenti: esegue i comandi giusti, apre il documento tematico corretto, rispetta i vincoli rigidi? Se una regola viene violata, chiediti prima: è visibile, c'è una contraddizione, può essere sostituita da una verifica automatica? Aggiungere una nuova riga è l'ultima risorsa.

Conclusione

CLAUDE.md e AGENTS.md sono il punto d'ingresso dell'agente nel progetto. Funzionano quando restano una mappa breve: comandi di verifica, vincoli rigidi in alto, link ai dettagli e al file di piano. Se una regola viene ignorata, di solito il motivo è un file gonfio e privo di struttura; le regole davvero critiche vanno rinforzate con verifiche e hook. Come costruire la struttura delle istruzioni e dello stato è illustrato in un corso pratico su un lavoro reale.