Un unico file di istruzioni per Claude Code, Codex e Cursor nel 2026

Per informazioni sul servizio, consulta la documentazione di Ailoot.

Cosa cambia quando usi Claude Code, Codex e Cursor insieme?#

Nell’esempio descritto, Claude Code è lo strumento principale, mentre Codex e Cursor vengono usati per attività specifiche. Il mio CLAUDE.md contiene circa 250 righe di istruzioni: cosa leggere e in quale ordine, cosa non va toccato, quali comandi usare per il deployment e le regole di formattazione dei commit. Quando ho provato per la prima volta Codex CLI sul progetto, non conosceva nessuna delle regole: ha eseguito git push --force, curiosato in .env e rinominato file senza attenzione.

All’inizio ho copiato a mano CLAUDE.md in AGENTS.md. Due settimane dopo ho scoperto che il progetto aveva già quattro versioni delle stesse istruzioni: in CLAUDE.md, AGENTS.md, .cursorrules e .windsurf/rules/. Erano tutte leggermente diverse. Non è un problema di Claude o Cursor: è la trappola di base di qualsiasi sistema con più fonti di verità. Ne parlo più nel dettaglio nella guida al lavoro multi-agente.

Nel giugno 2026, la documentazione sulla memoria di Claude Code di Anthropic proponeva una soluzione: un file condiviso più un import. Da settembre 2026, Claude Code legge direttamente AGENTS.md se il progetto non ha un CLAUDE.md; l’import serve quando hai regole specifiche per Claude. Di seguito spiego quando basta un solo AGENTS.md, come configurare un import e come separare le regole condivise da quelle specifiche per Claude.

Claude Code legge direttamente AGENTS.md?#

Prima di settembre 2026, la risposta era «no». Issue #6235, che chiedeva il supporto per AGENTS.md, era aperta dall’agosto 2025 ed è stata chiusa il 17 agosto 2026. Per tutto quel tempo, la documentazione sulla memoria indicava una sola soluzione: creare un CLAUDE.md e includervi AGENTS.md come import. Dalla versione 2.1.277, la documentazione dice qualcosa di diverso:

I file presenti nel progetto determinano esattamente cosa legge Claude Code:

Per questa verifica, contano CLAUDE.md, .claude/CLAUDE.md e CLAUDE.local.md nella directory di lavoro e in qualsiasi directory superiore. Un file personale ~/.claude/CLAUDE.md, un file gestito aziendalmente e le regole di .claude/rules/ non contano: vengono caricati insieme ad AGENTS.md.

Quando non c’è CLAUDE.md, all’avvio Claude Code legge tutti i file AGENTS.md e .claude/AGENTS.md nella directory di lavoro e in quelle superiori, e carica un file AGENTS.md in una sottodirectory quando apre un file in quella sottodirectory. Funzionano anche gli import @path all’interno di AGENTS.md. Claude Code non legge AGENTS.local.md, AGENTS.override.md né il contenuto della directory .agents/.

L’inghippo: anche un CLAUDE.local.md personale conta. Creandone uno per conservare regole non ancora confermate, Claude Code smette silenziosamente di leggere AGENTS.md. La soluzione è l’impostazione qui sotto.

Il comportamento cambia in /config, alla voce Project instructions:

Se vuoi conservare CLAUDE.local.md senza perdere AGENTS.md, imposta claude-md-and-agents-md. Non ci sarà una lettura duplicata: se AGENTS.md è già incluso tramite la riga @AGENTS.md o un link simbolico, Claude Code non lo carica una seconda volta, indipendentemente dall’impostazione.

Puoi verificare se il file è stato rilevato con il comando /memory: a partire dalla versione 2.1.280, nell’elenco compare il percorso di AGENTS.md. Nelle versioni precedenti alla 2.1.277 e nelle sessioni in cui il plugin integrato agents-md è disattivato, Claude Code legge solo CLAUDE.md e in /config non compare la voce Project instructions. Prima della versione 2.1.281, le sessioni tramite Amazon Bedrock e quelle con la telemetria disattivata si comportavano allo stesso modo. Inoltre, nella prima sessione dopo l’aggiornamento da una versione precedente, AGENTS.md potrebbe non essere caricato; funzionerà dalla sessione successiva.

Cosa significa per una configurazione con un solo file? Se non hai regole riservate a Claude, puoi fare a meno di CLAUDE.md: basta AGENTS.md e lo leggeranno Claude Code, Codex e Cursor. Se invece hai regole del genere (modalità plan per directory rischiose, skills, hooks), ti serve CLAUDE.md e Claude Code smetterà di leggere direttamente AGENTS.md. In tal caso, includi AGENTS.md in CLAUDE.md con la riga @AGENTS.md; questa configurazione funziona come prima di settembre. È utile anche con le versioni meno recenti di Claude Code. Lo spiego nel dettaglio qui sotto.

Come importare @AGENTS.md all’interno di CLAUDE.md?#

Un esempio minimo funzionante tratto dalla documentazione ufficiale:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

Ecco cosa succede. La prima riga, @AGENTS.md, è una direttiva di import. Quando Claude Code analizza CLAUDE.md all’inizio di una sessione, trova questo import e inserisce al suo posto l’intero contenuto di AGENTS.md. Segue l’intestazione ## Claude Code: è semplice markdown, ma funge da sezione per «aggiunte specifiche di Claude». Sotto c’è una regola valida solo per Claude Code: usare la modalità plan per le modifiche nella directory billing. Codex CLI o Cursor non apre affatto questo file: usa il semplice AGENTS.md.

Una citazione della documentazione su come funzionano gli import:

Alcuni dettagli pratici:

• Percorsi relativi e assoluti. @AGENTS.md è relativo al file che contiene l’import. @/Users/me/shared/rules.md o @~/.claude/personal.md sono percorsi assoluti. Io uso @~/.claude/personal.md per le preferenze personali che non voglio inserire nel repository.
• Profondità di quattro livelli. AGENTS.md può importare @docs/coding-style.md, e coding-style.md può importare un altro file, fino a quattro livelli. È sufficiente per qualsiasi struttura reale.
• I backtick bloccano gli import. Se il testo dice `@README`, è solo una menzione del nome, non un import. È utile quando si spiega ai lettori come funzionano gli import senza attivarne uno.
• Autorizzazione per i file esterni al progetto. Se un import punta al di fuori della directory di lavoro, come @~/.claude/personal.md, Claude Code mostra per la prima volta una finestra di dialogo che elenca quei file. Se rifiuti, gli import esterni restano disattivati e la finestra non viene più mostrata. @AGENTS.md nella radice del progetto non fa comparire una finestra. Questo ti protegge dal caricare per sbaglio nel contesto un file non correlato.

Dopo aver adottato questa configurazione nel progetto descritto, il mio CLAUDE.md è passato da 250 righe a 60: @AGENTS.md più da cinque a sette regole applicabili solo a Claude Code (modalità plan per directory rischiose, cosa non toccare nell’area amministrativa e come formulare i commit). Tutte le regole condivise sono in AGENTS.md, che Codex e Cursor leggono.

Quando scegliere un link simbolico e quando un import?#

La documentazione mostra l’opzione del link simbolico così:

ln -s AGENTS.md CLAUDE.md

E subito dopo avverte chiaramente dei problemi su Windows:

Tabella comparativa:

Nel progetto descritto uso gli import. Ecco perché:

1. Il team usa sistemi diversi. Io uso Mac; nell’esempio, il team è diviso all’incirca a metà tra Windows e Mac. Se nel repository compare un link simbolico, per chi usa Windows senza la modalità sviluppatore verrà effettuato il checkout come normale file di testo contenente una sola riga, AGENTS.md. Questo causa bug strani: a volte le regole funzionano, a volte no, e non si capisce perché.
2. Voglio regole solo per Claude. Sotto @AGENTS.md, il mio CLAUDE.md ha una sezione «Claude Code» con queste regole: usare --effort high per le attività di architettura, eseguire npm run build prima di git push e non chiamare a mano /api/v1/deploy. Codex non capisce questi comandi.
3. È più facile fare debug. Quando qualcosa va storto, apro CLAUDE.md e vedo l’import e le mie eccezioni. Un link simbolico non indica che «questo è stato aggiunto qui». Per saperne di più sul debug delle impostazioni di Claude Code, consulta la guida alla modalità sicura.

Se non hai regole specifiche per Claude, a partire dalla versione 2.1.277 il link simbolico non serve più: elimina CLAUDE.md e Claude Code leggerà direttamente AGENTS.md. Mantieni il link solo se qualcuno del team usa una versione precedente alla 2.1.277 e non può aggiornare. Se hai regole specifiche per Claude, un import è più comodo in nove casi su dieci.

Cosa leggono Codex, Cursor, Copilot, Windsurf e Gemini CLI?#

Una mappa dei sette strumenti principali (basata sulla documentazione ufficiale di ciascuno):

Quali sono le conseguenze? Se un repository ha AGENTS.md (più un CLAUDE.md con un import quando servono regole specifiche per Claude), cinque dei sette strumenti ricevono automaticamente istruzioni aggiornate. Cursor e Windsurf, che hanno file nativi propri, possono restare così come sono (AGENTS.md viene letto anche da loro) oppure si può aggiungere un import @AGENTS.md; la sintassi però è diversa e non sempre supportata.

La strategia più semplice per un nuovo progetto:

1. Metti tutte le regole condivise in AGENTS.md: il 95% delle regole appartiene a quel file.
2. Crea CLAUDE.md se ti servono regole solo per Claude: inserisci @AGENTS.md come prima riga, poi aggiungi una sezione con le regole specifiche per Claude. Se non ci sono regole del genere, CLAUDE.md non serve; Claude Code legge direttamente AGENTS.md dalla versione 2.1.277.
3. Tieni .cursor/rules/ per Cursor nei rari casi in cui serva qualcosa di specifico per Cursor (i comandi @Codebase e @Docs).
4. Fai lo stesso per Windsurf: lascia perdere il vecchio .windsurfrules; usa il nuovo .windsurf/rules/ solo quando servono schemi per la sua sintassi.

Questo approccio offre l’80% dei vantaggi con il 20% del lavoro. Per esperienza, quando mettevo ordine nei team misti di «Antigravity», mantenere più di due fonti di verità (condivisa più regole solo per Claude) diventa faticoso. Se qualcuno del team aggiunge una regola a .cursorrules e si dimentica di AGENTS.md, una settimana dopo Cursor e Codex non saranno d’accordo.

Come fa /init in Claude Code a rilevare un AGENTS.md esistente?#

Anthropic descrive /init così nella documentazione:

Cosa significa in pratica? Il repository descritto aveva un .cursorrules risalente a quando avevo provato Cursor (circa 80 righe) e un AGENTS.md (120 righe, messo insieme a mano). Quando ho eseguito claude /init, il comando ha preso entrambi i file, eliminato le regole simili e assemblato un CLAUDE.md pulito in un minuto. L’ho controllato in seguito e ho apportato piccole modifiche: ho rimosso le voci non più attuali e aggiunto una struttura con intestazioni. È stato più veloce che riscriverlo da zero.

La modalità interattiva, nella quale /init legge anche AGENTS.md, si attiva tramite una variabile d’ambiente:

CLAUDE_CODE_NEW_INIT=1 claude

Dopo l’avvio di /init, Claude pone una serie di domande di chiarimento: quali elementi configurare (CLAUDE.md, skills, hooks), quale stack usa il progetto e quali comandi usare per i test. Poi un subagent esplora la codebase leggendo package.json, README.md e i file di configurazione, e completa le parti mancanti. Alla fine, mostra una proposta che puoi modificare prima di salvarla. Per maggiori informazioni sulla configurazione di Claude Code all’avvio di un progetto, consulta la guida dedicata.

E ora lo svantaggio. Se il progetto ha già un AGENTS.md attivo, /init creerà accanto un CLAUDE.md che ne contiene una copia delle regole. Da quel momento, per impostazione predefinita Claude Code legge solo CLAUDE.md, quindi ci sono di nuovo due fonti di verità: tu aggiorni AGENTS.md, mentre Claude continua a lavorare dalla vecchia copia. Il comando /import fa qualcosa di simile: aggiunge una copia una tantum di AGENTS.md a CLAUDE.md. Per mantenere un’unica fonte, dopo /init metti l’import @AGENTS.md come prima riga di CLAUDE.md e rimuovi da CLAUDE.md tutto ciò che ripete AGENTS.md.

/init è il punto di partenza giusto per un nuovo progetto o per uno che stai trasferendo da Cursor o Copilot. Non serve cercare online il «miglior modello di CLAUDE.md»: Anthropic tiene già conto di ciò che è nel repository. Se il progetto ha già un AGENTS.md attivo e non ci sono regole specifiche per Claude, /init non serve: Claude Code leggerà direttamente AGENTS.md.

Come separare le istruzioni condivise da quelle specifiche per Claude?#

Le separo seguendo questo principio. Regole condivise da inserire in AGENTS.md:

• Cosa non toccare nel codice. Le cartelle .env, node_modules, prisma/migrations (solo tramite prisma migrate), .next/, .git/.
• Come nominare gli elementi. Branch: feat/, fix/, chore/. Commit: prefissi feat:, fix:, docs: più una breve descrizione. File dei componenti in kebab-case.
• Comandi per test e lint. npm run build, npm run lint, npm test. Quale comando eseguire prima di git push.
• Principi architetturali. Cosa va in src/lib/, cosa in src/components/, dove vive la logica di business e dove si trova l’interfaccia utente.
• Sicurezza. Non eseguire mai il commit di segreti. Accedi al database di produzione solo tramite prod-psql. Accedi alla produzione via SSH solo tramite l’alias prod, non con root@IP.

Regole specifiche per Claude da inserire in CLAUDE.md (sotto @AGENTS.md):

• Modalità plan. Usa la modalità plan per modifiche in directory rischiose (per esempio, src/billing/).
• Livello di effort. Usa --effort high per le attività di architettura e medium per il lavoro di routine.
• Skills. Quali agenti AI e skills avviare nelle varie situazioni. Per esempio: «quando lavori a una guida, avvia la skill build-masterskaya-guide».
• Memoria di Claude. Cosa inserire nella memoria automatica e cosa in CLAUDE.local.md. Per saperne di più sulla memoria di Claude, consulta la guida a Memory e CLAUDE.md.
• Hooks. Se .claude/settings.json contiene hooks configurati, descrivi in CLAUDE.md cosa fanno (Codex e Cursor non li conoscono e non ne hanno bisogno).
• Skills e comandi. Un elenco dei comandi slash che uso spesso (/init, /cd, /memory, /plan).

Il confine non è sempre netto. Per esempio, «non eseguire mai git push --force su main» è chiaramente una regola condivisa e va in AGENTS.md. Ma «quando esegui git push su un branch hot, usa prima la modalità plan» è specifico per Claude Code e va in CLAUDE.md. La prova da fare è: «Se domani eliminassi Claude Code e tenessi solo Codex, questa regola sarebbe ancora valida?». Se sì, mettila in AGENTS.md. Se no, mettila in CLAUDE.md.

Cosa va in AGENTS.md e cosa in CLAUDE.md o .claude/rules?#

Se le regole superano le 200 righe, è ora di suddividerle. La documentazione di Anthropic consiglia di puntare a 200 righe per file, perché i file CLAUDE.md lunghi iniziano a far perdere silenziosamente aderenza: sembra che Claude li legga, ma li segue meno spesso.

Una struttura per un progetto grande che funziona per me:

my-project/
├── AGENTS.md                    # 100-150 lines, shared
├── CLAUDE.md                    # 30-50 lines: @AGENTS.md + Claude-only
└── .claude/
    ├── CLAUDE.md                # alternative to root file, same file
    └── rules/
        ├── api.md               # with paths: ['src/api/**']
        ├── components.md        # with paths: ['src/components/**']
        ├── testing.md           # without paths, always active
        └── security.md          # without paths, always active

Ogni file in .claude/rules/ può avere un frontmatter:

---
paths:
  - "src/api/**/*.ts"
---

# API rules
- Every endpoint validates input with zod
- Errors use the standard `{error, code}` format
- OpenAPI comments are required

Claude carica queste regole solo quando lavora con file che corrispondono a questo schema. Se tocca src/components/Button.tsx, le regole API non vengono aggiunte al contesto. In questo modo, nella finestra di contesto finisce solo ciò che è pertinente. La directory .claude/rules/ funziona anche senza CLAUDE.md: se il progetto contiene solo AGENTS.md, le relative regole vengono caricate insieme a esso e non disattivano la lettura diretta di AGENTS.md.

Cursor e Windsurf supportano lo stesso approccio tramite le directory .cursor/rules/ e .windsurf/rules/. Lo standard AGENTS.md può fare riferimento a queste directory, ma la sintassi tra strumenti non è ancora del tutto stabile. È più sicuro tenere le regole condivise in AGENTS.md e duplicare le regole basate sui percorsi in .claude/rules/ e .cursor/rules/: sono casi specifici e rari, non la maggior parte delle regole.

Posizioni utili per CLAUDE.md (dalla più generale alla più specifica):

Un esempio di ~/.claude/CLAUDE.md potrebbe contenere due regole: «rispondi nella lingua preferita dall’utente» e «scrivi Ailoot esattamente così». Queste regole valgono per ogni progetto, quindi non serve duplicarle in ogni repository.

Di questi quattro livelli, solo CLAUDE.md a livello di progetto e CLAUDE.local.md disattivano la lettura diretta di AGENTS.md. Un ~/.claude/CLAUDE.md personale e una policy gestita non interferiscono: Claude Code li legge insieme ad AGENTS.md.

Cosa fare se AGENTS.md nel tuo progetto è già obsoleto?#

Nel progetto descritto avevo un AGENTS.md del maggio 2025: 180 righe, molte ormai obsolete (menzionava endpoint API Anthropic che nel frattempo erano cambiati, esempi con la sintassi claude --tools che non esiste più e regole su ~/.claude/projects/ basate su una struttura non più attuale).

Il piano che ho usato per aggiornarlo:

1. Esaminalo con claude in modalità plan. Apro il repository, eseguo claude --safe-mode e chiedo: “Rileggi AGENTS.md e suggerisci un elenco di elementi obsoleti o ripetuti. Non modificarlo; limitati a elencarli.” In due minuti ho ricevuto un elenco di 23 elementi da rivedere.
2. Rimuovi gli elementi chiaramente obsoleti. Dei 23, 9 erano chiaramente superati: sintassi dei comandi, endpoint e nomi dei flag. Ho eliminato quelle righe.
3. Accorpa i duplicati. Altri 6 elementi ripetevano gli stessi concetti con parole diverse («non forzare il push», «non usare mai --force», «evita git push -f»). Li ho riuniti in una sola riga.
4. Aggiungi nuovi elementi. Ho aggiunto ciò che avevo notato che Claude/Codex sbagliavano regolarmente nel mese precedente, seguendo la regola «una riga per schema di errore». Ne sono risultati 8 nuovi elementi.
5. Avvia un subagent per una revisione finale. Ho richiesto una revisione di Claude con l’istruzione «trova contraddizioni, ambiguità e duplicati». Ha trovato tre formulazioni da rendere più chiare. Le ho sistemate.

Dopo un’ora, AGENTS.md era lungo 110 righe, aggiornato, e conoscevo personalmente ogni riga. È stato facile ricavarne un CLAUDE.md di 30 righe. In seguito, Codex è diventato sensibilmente più attento ai test: sospetto che alcune sue decisioni «strane» derivassero da istruzioni obsolete che aveva seguito in buona fede.

I principi fondamentali per mantenere attuale un AGENTS.md:

• Ogni regola risponde a un errore ricorrente. Se durante il mese non mi è mai venuta in mente una certa regola, non c’è motivo di mantenerla.
• Scrivi regole come comandi, non come teoria. «Usa due spazi» è una regola. «Lo stile del codice dovrebbe essere ordinato» non lo è.
• I dettagli prevalgono sulle generalità. «Esegui npm run build prima di git push» è una regola. «Testa le modifiche» non lo è.

Cosa NON funziona assolutamente con questa configurazione?#

Alcune cose che ho imparato a mie spese in sei mesi di lavoro con questa configurazione:

1. Il completamento automatico di Cursor non usa AGENTS.md. Quando Cursor suggerisce il completamento di una riga nell’editor, non legge AGENTS.md in tempo reale: c’è un motore rapido separato. Le regole in AGENTS.md contano solo quando invii una richiesta in chat dentro Cursor. Questo significa che scrivere «non usare var, usa const» in AGENTS.md non influenzerà il completamento automatico; devi configurarlo tramite ESLint o la configurazione TypeScript.

2. Gli hooks di Claude Code in AGENTS.md non funzionano per Codex. Se .claude/settings.json ha configurato un hook PreToolUse per bloccare una certa azione, questa informazione è utile solo a Claude. Codex non conosce gli hooks: per lui è «decide lo strumento stesso». Ha senso scrivere «non fare X» in AGENTS.md e «c’è un hook che blocca fisicamente X» in CLAUDE.md, sotto l’import.

3. Copilot e .github/copilot-instructions.md. GitHub Copilot legge il proprio file e ancora non legge molto bene AGENTS.md. Se il tuo team usa Copilot attivamente, aggiungi un .github/copilot-instructions.md separato con una versione abbreviata delle regole oppure usa Copilot Extensions che conoscono AGENTS.md. La situazione cambia rapidamente, quindi tra tre e sei mesi il quadro potrebbe essere diverso.

4. Git non registra un link simbolico come modifica a CLAUDE.md. Se esegui ln -s AGENTS.md CLAUDE.md e aggiorni AGENTS.md una settimana dopo, Git mostrerà una differenza solo per AGENTS.md. È normale, ma un collega che esamina la PR potrebbe non accorgersi che anche CLAUDE.md è stato aggiornato tramite il link simbolico. Soluzione: scrivi esplicitamente nella descrizione della PR: «aggiornato AGENTS.md; Claude Code vede lo stesso file tramite il link simbolico».

5. Gli import profondi sono difficili da analizzare. Se AGENTS.md importa @docs/coding-style.md, che importa @docs/typescript.md, e una regola entra in conflitto con un’altra, il debug è difficile. Limito gli import a un livello (CLAUDE.md → AGENTS.md) e non li annido ulteriormente. Anthropic offre un hook InstructionsLoaded che registra quali file sono stati caricati: utile per il debug delle configurazioni a livelli. Nota: l’hook si attiva per AGENTS.md incluso tramite import o link simbolico, ma non per AGENTS.md letto direttamente da Claude Code.

La configurazione completa per una serata di vibe coding: clone AI + Second Brain + context engineering.

Scopri Ailoot.