Come scrivere AGENTS.md e CLAUDE.md: cosa fanno 100 repo

A cosa servono AGENTS.md e CLAUDE.md

Un agente di coding inizia ogni sessione senza conoscere il progetto. Il file di regole è il posto in cui scrivi una volta sola ciò che altrimenti spiegheresti ogni volta: i comandi di build e di test, le convenzioni del codice, la struttura delle directory, le cose per cui dici «non farlo mai». Questo articolo spiega come scrivere quel file: che nome dargli, cosa metterci dentro, quanto tenerlo lungo.

AGENTS.md non appartiene a un singolo strumento. È un formato aperto gestito dall’Agentic AI Foundation, che fa parte della Linux Foundation; secondo il suo sito lo usano più di 60.000 progetti open source. È un semplice file Markdown, senza campi obbligatori. CLAUDE.md invece è il file che Claude Code legge all’inizio di ogni sessione. Anche questo è Markdown semplice, ma con alcune funzioni in più: può importare altri file (@percorso) e avere livelli specifici per l’utente o per l’organizzazione.

Noi costruiamo uno strumento che legge questi file ogni giorno: diffox, quando esamina una pull request, legge anche il file di regole del repository (come funziona lo raccontiamo in un altro articolo). Le misurazioni qui sotto sono un sottoprodotto di quel lavoro.

Quale strumento legge quale file

Abbiamo compilato la tabella qui sotto il 13 ottobre 2026, dalla documentazione dei cinque strumenti. Può cambiare con le nuove versioni; il nome di ogni strumento rimanda alla sua fonte.

Fonte: la documentazione di ciascuno strumento, 13 ottobre 2026. La riga di Claude Code vale per la versione 2.1.277 e successive.

Dalla tabella emergono due cose. Primo, tutti e cinque gli strumenti possono leggere AGENTS.md: Gemini CLI con un’impostazione, Claude Code se accanto non c’è un CLAUDE.md. Secondo, ogni strumento tratta le sottocartelle a modo suo: Codex unisce tutto dalla radice in giù, Copilot prende il file più vicino, Claude Code carica il file di una sottocartella solo quando apri un file lì.

Il 18 giugno 2026 Google ha smesso di servire Gemini CLI agli utenti gratuiti e agli abbonati Google AI Pro e Ultra, indirizzandoli ad Antigravity CLI; con una chiave API a pagamento o una licenza aziendale puoi continuare a usare Gemini CLI. Il 28 ottobre 2026 abbiamo letto la documentazione di Antigravity sulle regole. Legge un file chiamato AGENTS.md o GEMINI.md senza bisogno di alcuna impostazione. Carica il file di una sottocartella non appena l’agente legge o modifica un file in quella cartella. Unisce i file che trova; se le regole sono in conflitto, vale quella della sottocartella. Il limite è di 24 KB per file. CLAUDE.md non è tra i file che la documentazione elenca; se le tue regole sono in AGENTS.md, le legge anche Antigravity.

AGENTS.md è più diffuso di CLAUDE.md

Per vedere quale file è più diffuso abbiamo scelto i repository con un solo criterio: i 100 repository con più stelle di GitHub, il 13 ottobre 2026. Buona parte della lista non è software da compilare (elenchi di risorse, libri, corsi). Abbiamo lasciato la lista così com’è, perché li abbiamo scelti senza guardare se avessero un file di regole.

Dei 100 repository, 47 hanno nella radice almeno uno di questi due file. 42 repository hanno AGENTS.md, 24 hanno CLAUDE.md; quelli con solo CLAUDE.md sono 5. I file degli altri strumenti sono più rari: quello di Copilot è in 11 repository, la cartella di regole di Cursor in 4, GEMINI.md in 3. Il vecchio file .cursorrules è rimasto in 1 repository; .windsurfrules e .clinerules non ci sono in nessuno.

Contando anche i file nelle sottocartelle e quelli degli altri strumenti, i repository con almeno uno di questi file diventano 55.

Se ci sono entrambi i file, Claude Code legge solo CLAUDE.md

È il punto su cui ci si sbaglia più spesso. Per molto tempo Claude Code non ha letto affatto AGENTS.md, e molte fonti lo scrivono ancora oggi. Dalla versione 2.1.277 lo legge, ma a una condizione: che nella directory di lavoro o in quelle superiori non ci sia un CLAUDE.md (o un CLAUDE.local.md). Se ci sono entrambi, il comportamento predefinito è leggere solo CLAUDE.md.

In pratica: se accanto c’è un CLAUDE.md, una regola che aggiungi ad AGENTS.md non arriva a Claude Code. Codex invece, per impostazione predefinita, legge solo AGENTS.md. Devi tenere i due file allineati a mano.

Un CLAUDE.local.md che aggiungi per le tue note personali ha lo stesso effetto: finché quel file c’è, Claude Code non legge AGENTS.md. Per fargli leggere entrambi, in /config imposta «Project instructions» su claude-md-and-agents-md.

In 19 dei 100 repository i due file stanno insieme nella radice. Abbiamo guardato uno per uno come questi repository li collegano.

8 repository fanno puntare CLAUDE.md direttamente ad AGENTS.md: 5 scrivendo @AGENTS.md in CLAUDE.md, 3 con un link simbolico. In n8n, AutoGPT, RustDesk e Clash Verge Rev, CLAUDE.md è fatto di una sola riga. In 2 repository CLAUDE.md rimanda ad AGENTS.md con una semplice frase; secondo la documentazione di Claude Code, l’agente vede quel file solo se decide di aprirlo. 3 repository tengono lo stesso testo in due file, e in 1 di essi le due copie non hanno più lo stesso numero di regole. Nei 6 restanti i due file contengono testi diversi: lì Claude Code e Codex leggono istruzioni diverse nello stesso progetto.

Due modi per far puntare CLAUDE.md ad AGENTS.md

Anche i dati vanno in questa direzione: tieni le regole in un solo file e fai puntare l’altro lì. Il testo vero va in AGENTS.md, che leggono più strumenti. Mettici accanto questo CLAUDE.md:

@AGENTS.md

## Claude Code
Qui le note che valgono solo per Claude Code.

La riga di importazione carica AGENTS.md come parte di CLAUDE.md; sotto scrivi solo le note specifiche per Claude Code. Se non hai note del genere, va bene anche un link simbolico: ln -s AGENTS.md CLAUDE.md.

Il link simbolico ha due difetti. Chi clona il repository su Windows può trovare, al posto del link, un file di testo di una riga. E Claude Code si rifiuta di scrivere attraverso il link e modifica il file vero. Se nel team qualcuno usa Windows, la riga di importazione è più sicura.

Anche tenere solo AGENTS.md ormai è un’opzione, perché le versioni recenti di Claude Code lo leggono direttamente. Lasciare il CLAUDE.md di una riga per le versioni vecchie non fa danni: Claude Code non carica due volte lo stesso file.

Cosa scrivono nel file i repository popolari

Per vedere cosa ci scrivono, abbiamo guardato i titoli dei 47 file letti. Se un file dà a un argomento un titolo tutto suo, lo abbiamo contato come file che ne parla.

L’argomento più frequente sono le regole su commit e pull request (29 file). Seguono i comandi di installazione ed esecuzione (26), lo stile del codice (26), la struttura delle directory (21), i test (16) e la sicurezza (7). A prescindere dai titoli, 36 dei 47 file contengono un comando, in un blocco di codice o scritto nel testo. Il conteggio guarda solo le parole dei titoli, quindi è una misura grezza, ma l’ordine è chiaro: l’agente vuole sapere prima di tutto cosa eseguire e come, e come consegnare la modifica.

Due buoni esempi, da Kubernetes e AutoGPT

Entrambi gli esempi sono tra i file letti in questo conteggio. L’AGENTS.md di Kubernetes ha 38 righe. Ogni regola dice cosa non fare e cosa fare al suo posto; accanto a ogni comando è scritto a cosa serve:

## Constraints

- **Generated files are read-only.** Never hand-edit `zz_generated.*` or `generated.pb.go`. Run `make update`.
- **go.mod/go.work are generated.** Use `hack/pin-dependency.sh` + `hack/update-vendor.sh`. Never `go mod tidy`.
…
## Commands

Run `make help` for all available targets. Common workflows:

```
make test WHAT=./pkg/kubelet GOFLAGS=-v     # Unit tests (one package)
make test-integration WHAT=./test/integration/scheduler
make verify                                 # All verification checks
make update                                 # ALL generators and formatters
```

L’AGENTS.md di AutoGPT ha 92 righe; descrive la struttura delle directory, il comando di test di ogni parte e regole misurabili per le pull request. Il suo CLAUDE.md invece è fatto solo della riga @AGENTS.md: il modo di collegarli che proponiamo sopra.

## Testing

- Backend: `poetry run test` (runs pytest with a docker based postgres + prisma).
- Frontend integration tests: `pnpm test:unit` (Vitest + RTL + MSW, primary testing approach).
…
## Pull requests

…
- Keep out-of-scope changes under 20% of the PR.

I due file usano frasi che possono verificare sia un agente sia una persona: «non modificare a mano il file generato, esegui make update» oppure «le modifiche fuori ambito non superino un quinto della pull request». Le citazioni vengono dal commit letto nel conteggio; «…» indica le righe omesse.

Un modello di AGENTS.md da cui partire

Uno scheletro breve di AGENTS.md, ricavato dai titoli più frequenti nei repository popolari e dai due esempi qui sopra. È solo un esempio; l’abbiamo scritto in inglese, perché gli agenti che leggono questi file e la maggior parte dei team lavorano in inglese. Sostituisci i comandi e i percorsi con quelli del tuo progetto:

# Project name

## Commands
- Install: `pnpm install`
- Test one package: `pnpm test --filter api`
- Lint and format: `pnpm lint && pnpm format`

## Project structure
- `apps/web` - Next.js front end
- `packages/api` - API service

## Code style
- TypeScript strict mode. Never use `any`; use `unknown`.

## Testing
- Add or update the test that covers your change.

## Commits and pull requests
- Conventional commits: `feat(api): ...`
- Keep unrelated changes out of the pull request.

## Never
- Never hand-edit files under `generated/`. Run `pnpm generate`.
- Never commit secrets; read them from the environment.

Se usi Claude Code, mettici accanto il CLAUDE.md di una riga: @AGENTS.md. Ogni riga del modello è un comando o una regola verificabile; spiegare cosa fa il progetto è compito del README.

Come scrivere una buona regola

Su cosa scrivere nel file, il criterio più utile è quello della documentazione di Claude Code: un’istruzione deve essere abbastanza concreta da poter essere verificata. «Usa un’indentazione di 2 spazi» invece di «formatta bene il codice»; «esegui npm test prima del commit» invece di «testa le tue modifiche». Ecco sei punti che uniscono questo criterio a quello che abbiamo imparato scrivendo il nostro file:

• Di’ all’agente cosa fare. Una frase che dice «fai questo» o «non fare mai quello» si può verificare; una presentazione del progetto no. In 3 dei 47 file che abbiamo letto non c’è nemmeno una frase così; il file mediano ne ha 10.
• Scrivi il comando così com’è. Da «esegui i test» l’agente non può capire quale comando intendi; se scrivi pnpm test --filter api, esegue quello.
• Scrivi accanto alla regola il suo perché. Nel nostro file, accanto a ogni regola c’è l’errore che ce l’ha fatta scrivere. Una regola senza motivo la cancella il primo a cui dà fastidio.
• Non scrivere ciò che gli strumenti controllano già. Aggiungere al file una regola che il formatter e il linter verificano già consuma righe; più il file si allunga, meno le istruzioni vengono rispettate.
• Scrivi ogni regola in un posto solo. Se la stessa regola è scritta in due file, una delle due copie invecchia, ed è quella del file letto meno.
• Aggiungi quando un errore si ripete, cancella quando la regola non serve più. Scrivi la regola quando l’agente fa lo stesso errore una seconda volta. In Claude Code, /doctor prompt-audit elenca le istruzioni superate e quelle in contraddizione.

Il primo di questi punti conta direttamente per diffox. Quando esamina una pull request, diffox legge il file di regole nella radice del repository: prima AGENTS.md, altrimenti CLAUDE.md. Segue anche il link simbolico e la riga @AGENTS.md. Le frasi che dicono cosa fare le passa agli agenti specializzati come regole di review. Una regola verificabile, quindi, serve anche alla review.

La maggior parte dei file di regole sta sotto le 200 righe

Sulla lunghezza, la documentazione di tre strumenti dà tre limiti diversi. Claude Code punta a meno di 200 righe per file, perché un file lungo consuma più contesto e l’agente segue meno le istruzioni. Cursor consiglia meno di 500 righe per regola. Codex smette di aggiungere file quando quelli che ha unito arrivano a 32 KiB in totale.

Dei 47 file che abbiamo letto, la mediana è 92 righe; il più corto ne ha 4, il più lungo 1.017. 14 superano le 200 righe, 2 le 500. File che superano da soli il limite di 32 KiB di Codex: 1.

In un monorepo una sottocartella ha il suo file di regole

Nei repository grandi le regole non stanno in un solo file. Dei 98 repository di cui abbiamo potuto leggere tutto l’albero, 27 hanno un AGENTS.md o un CLAUDE.md anche in una cartella diversa dalla radice: 278 file in tutto.

Il file di una sottocartella vale per le modifiche fatte in quella cartella: le regole del front end stanno nella cartella del front end, quelle del back end nel back end. Il file nella radice resta breve, e l’agente carica solo le regole del punto in cui lavora.

Quanto spesso serva l’abbiamo visto in una nostra misurazione di settembre 2026: nei 17 repository con un file di regole in una sottocartella, 202 delle ultime 417 pull request unite modificavano almeno un file in una cartella di questo tipo.

Attenzione però: ogni strumento tratta le sottocartelle a modo suo. Se scrivi lo stesso argomento a due livelli in due modi diversi, quale frase vale dipende dallo strumento. Non lasciare frasi che si contraddicono.