AGENTS.md e CLAUDE.md: il file di contesto che l'agente legge

L'agente non “ricorda” il repo tra una sessione e l'altra. Quello che trovi in root — AGENTS.md, CLAUDE.md, .cursor/rules — è il pezzo di contesto che torna ogni volta. Se è lungo, vago o in contraddizione con il codice, lo ignora in silenzio. Tu torni a ripetere le stesse correzioni in chat.

Questo pezzo è il seguito pratico di perché l'AI ti suggerisce sempre lo stesso stack: lì il default nasce dal training; qui nasce da un file che *tu* controlli. Vive nell'hub Vibe coding e in AI Engineering.

In breve: Tieni una fonte di verità breve (idealmente AGENTS.md o un CLAUDE.md che lo importa). Mettici comandi reali, vincoli verificabili e never-do. Togli romanzi, stack obsoleto e stile che già fa il linter. Se usi più tool (Cursor, Claude Code, Codex), allinea i file invece di copiare tre versioni che divergono.

Tabella rapida: quale file per cosa

AGENTS.md — contratto di repo per Cursor, Codex, Claude Code e altri; nested nei monorepo.
CLAUDE.md — istruzioni Claude Code (Cursor lo legge come AGENTS.md); target doc sotto ~200 righe; può importare @AGENTS.md.
`.cursor/rules/*.mdc` — scope per path, intelligent o @mention; serve frontmatter (.md plain ignorato).
`.cursorrules` — legacy: migrare a rules Always Apply o assorbire in AGENTS.md.

Cosa sono questi file (e a chi parlano)

AGENTS.md è un file markdown di istruzioni per coding agent: vive in root (e, se serve, nelle sottocartelle) ed è pensato come “README per gli agenti”. Comandi di build/test, stile, security, workflow. Non ha schema obbligatorio. La specifica vive su agents.md; Codex documenta come lo carica in Custom instructions with AGENTS.md.

CLAUDE.md è il file di istruzioni persistenti di Claude Code: progetto (./CLAUDE.md o ./.claude/CLAUDE.md), utente (~/.claude/CLAUDE.md), e policy gestite. Claude lo legge all'inizio di ogni sessione. La doc ufficiale è How Claude remembers your project. Claude Code può anche leggere AGENTS.md. Da solo o insieme a CLAUDE.md, a seconda dell'impostazione *Project instructions*.

Regole di Cursor (.cursor/rules/*.mdc) sono istruzioni con frontmatter: alwaysApply, globs, description. Servono quando vuoi scope per path o regole manuali con @. Cursor tratta anche AGENTS.md (root e nested) come alternativa semplice. Legge CLAUDE.md come AGENTS.md, sempre applicato. Vedi Rules e help: Rules.

`.cursorrules` in root è legacy: Cursor lo marca come da deprecare e indica la migrazione verso .cursor/rules con Always Apply.

Cosa carica davvero l'agente

Non è magia. È injection nel contesto.

In Cursor, le regole applicabili e AGENTS.md / CLAUDE.md entrano all'inizio del contesto Agent. Le nested AGENTS.md si combinano con i parent; quelle più specifiche pesano di più. Un .md plain in .cursor/rules senza frontmatter viene ignorato dal sistema regole: serve .mdc (o usa AGENTS.md).

In Claude Code, CLAUDE.md / CLAUDE.local.md lungo l'albero (e regole in .claude/rules/) vengono concatenati; i file nelle sottocartelle possono caricarsi on-demand quando tocchi quei path. La doc spinge a restare sotto ~200 righe per file: oltre, peggiora l'aderenza e brucia contesto. Gli import @path espandono altro markdown a launch — organizzano, ma non “risparmiano” token.

In Codex (e nella convenzione AGENTS.md), la catena è globale → root → directory corrente; i file più vicini al working directory vincono; c'è un tetto di byte (project_doc_max_bytes, default 32 KiB nella doc Codex).

Il vincolo comune: il modello tratta queste istruzioni come contesto, non come policy hard. Per bloccare un'azione (comando pericoloso, path off-limits) serve il meccanismo del tool (hook, deny list, sandbox), non solo una riga “never do X”.

Un caso tipo (senza inventare il repo)

Il pattern ricorrente nei setup reali è questo.

Parti con un AGENTS.md di 300 righe: overview, storia del prodotto, elenco dipendenze, stile da libro, e tre comandi di test di cui solo uno esiste ancora in package.json. L'agente lo carica. Poi propone lo stack di moda, salta il test che non trova, e ignora il never-do sepolto a metà file.

La correzione che tiene non è “scrivi di più”. È tagliare a comandi verificabili, vincoli di path, never-do in cima, e spostare lo stile sul linter. Se Claude Code e Cursor devono convivere, un import @AGENTS.md da CLAUDE.md batte due file che divergono dopo una settimana.

Cosa mettere: comandi, vincoli, never-do

Metti ciò che un collega nuovo sbaglierebbe al primo giorno — e che l'agente ripete senza il file.

Comandi veri, copiabili:

Install / dev / test / lint / typecheck (con package manager reale: pnpm, non “usa npm o yarn”)
Come lanciare un singolo test o un filter
Dove sta la CI (path del workflow), se l'agente deve allinearsi

Vincoli di repo, non preferenze da forum:

Dove vivono handler, migration, skill, harness
Formato commit/PR se è policy di squadra
Stack *deciduto* (es. Workers + D1, non “qualche database”)

Never-do concreti e verificabili:

Non toccare dist/ / generated
Non inventare API che non esistono nel repo
Non installare pacchetti suggeriti senza verificarli: nome, autore, età. I nomi inventati dall'AI possono essere registrati da altri (slopsquatting e controlli prima di npm install)
Non fare force-push / skip hook senza conferma
Non loggare secret; non committare .env

Esempi e puntatori, non paste interi: “segui @src/services/example.ts”, non 80 righe di template nel file di contesto. Cursor e Claude Code permettono riferimenti a file; usali.

Questo è lo stesso spirito di tool engineering: la descrizione deve essere inequivocabile, altrimenti il loop “funziona” e sbaglia in silenzio.

Cosa togliere (perché l'agente lo ignora)

Pattern tipici che gonfiano il file e abbassano l'aderenza:

Romanzo di architettura che ripete il README o un diagramma già nel codice
Style guide da stile libro (“scrivi codice pulito”, “usa best practice”) — lascia fare a ESLint/Prettier/ruff
Comandi ovvi che il modello già conosce (git status, npm install generico) senza il *tuo* comando reale
Stack stale: “usiamo Create React App” quando il repo è già su Vite; l'agente obbedisce al file e litiga con package.json
Tre copie divergenti: AGENTS.md dice pnpm, CLAUDE.md dice npm, una rule Cursor dice yarn
Edge case rari nel file always-on: meglio una rule con globs / paths, o una skill on-demand

Se correggi lo stesso errore due volte in chat, aggiorna il file. Se non lo aggiorni, stai addestrando solo quella sessione.

Una sola fonte di verità

La domanda non è “quanti file supporta il vendor?”. È: dove vive la verità quando Cursor, Claude Code e Codex aprono lo stesso repo? Se stai ancora decidendo quale agente usare, il confronto su terminale, review e confini del repo è in Claude Code vs Cursor vs Copilot in un progetto.

Setup che tiene in produzione, in ordine di semplicità:

1. Solo `AGENTS.md` in root — funziona con Cursor, Codex e (nelle versioni recenti) Claude Code quando non c'è un CLAUDE.md che lo maschera. 2. `CLAUDE.md` che importa `@AGENTS.md`, più eventuali note solo-Claude sotto l'import — un file condiviso, senza duplicare. Claude Code documenta esplicitamente questo pattern. 3. Symlink `CLAUDE.md` → `AGENTS.md` — ok su Unix; su Windows e clone Git senza core.symlinks spesso si rompe: preferisci l'import. 4. `.cursor/rules/*.mdc` per ciò che deve essere *scoped* (solo *.tsx, solo migrations/**), non per riscrivere tutto il contratto del repo.

Nested AGENTS.md / CLAUDE.md nei package di un monorepo: sì, quando le regole del package front-end non devono inquinare il backend. Root resta corto; il dettaglio sta vicino al codice.

Evita di “risolvere” i conflitti aggiungendo ancora testo. Rimuovi la copia vecchia.

Passo per passo: mettere in piedi il file

1. Inventaria cosa l'agente sbaglia già: package manager, path test, “non toccare X”, default di stack sbagliato (vedi di nuovo la trappola dello stack default).

2. Crea un solo file corto in root — parti da AGENTS.md con sezioni: Overview (3–5 righe), Setup commands, Code / architecture constraints, Never-do, PR/test gate.

3. Collega gli altri tool senza clonare il testo: import o lettura nativa di AGENTS.md; migra .cursorrules in una rule Always Apply o assorbi il contenuto utile in AGENTS.md e cancella il legacy.

4. Scope il rumore: ciò che vale solo per un path va in .cursor/rules con globs o in .claude/rules con paths, non nel file always-on.

5. Verifica il load: in Claude Code, /context e /memory; in Cursor, controlla che le rule risultino applicate (tipo Always / glob / @mention). Poi fai un task piccolo e guarda se ripete l'errore noto.

6. Chiudi il feedback loop: quando correggi l'agente, chiedigli di aggiornare AGENTS.md *nella stessa PR*. Codex e la convenzione AGENTS.md lo dicono esplicitamente: il file è documentazione viva, non un rituale di kickoff.

Anti-pattern da evitare

File da 800 righe “così l'agente sa tutto”
Istruzioni che contraddicono CI o pre-commit (l'agente le “segue”, la pipeline fallisce)
Never-do senza alternativa (“non usare fetch” — e poi cosa?)
Contesto di prodotto che cambia ogni sprint (mettilo in issue/ticket, non nel file always-on)
Usare il file di contesto al posto di un agente che non serve: se il lavoro è un cron + script, non serve un romanzo di regole

Il pezzo su prompt, context, loop e graph inquadra dove sta questo layer: è context engineering di repo, non un nuovo prompt magico ogni chat.

Cosa conviene fare adesso

Se non hai nulla: aggiungi un AGENTS.md di 40–80 righe con comandi e never-do reali.
Se hai AGENTS.md + CLAUDE.md + .cursorrules + cinque .mdc always-on: fondi, importa, migra il legacy, taglia sotto la soglia che il tuo tool documenta (centinaia di righe / decine di KiB).
Se l'agente propone ancora lo stack “di moda”: il file di contesto deve dichiarare lo stack *deciso*, non “scegli tu”.
Se l'errore è di tool/API verso l'agente: sistema le descrizioni dei tool, non solo il markdown in root.

Il file giusto non rende l'agente infallibile. Rende ripetibile ciò che altrimenti riscriveresti ogni mattina.