Passa al contenuto principale

AGENTS.md e interoperabilità tra strumenti

Intermedio

Conosci già CLAUDE.md — il briefing di progetto di Claude Code. Ma il tuo repo è probabilmente toccato da più di un agente: un collega usa Codex, la CI usa un coding bot, qualcuno apre il repo in Cursor. AGENTS.md è lo standard aperto che questi strumenti concordano di leggere, così scrivi le istruzioni del tuo progetto una sola volta invece di mantenere un file diverso per ogni strumento.

What you'll learn
  • Cos'è AGENTS.md e chi lo governa
  • Perché Claude Code legge CLAUDE.md e non AGENTS.md
  • Tre modi affidabili per mantenere un'unica fonte di verità tra gli strumenti
  • Come si fondono i file AGENTS.md annidati e globali
  • Cosa va nel file — e cosa tenere fuori

Cos'è AGENTS.md​

AGENTS.md è un semplice file Markdown nella root del tuo repo — pensalo come un README scritto per gli agenti invece che per gli umani. Spiega a un coding agent come compilare, testare e contribuire al progetto. Il formato non ha campi obbligatori: gli agenti semplicemente leggono la prosa.

È uno standard aperto governato dalla Agentic AI Foundation (AAIF) sotto la Linux Foundation e, a metà 2026, è usato da oltre 60.000 progetti open-source e letto da più di 30 strumenti — tra cui OpenAI Codex, Jules e Gemini CLI di Google, Cursor, Windsurf, Devin, Zed, Warp, Aider, goose, Amp e il coding agent di GitHub Copilot.

What you'll learn
  • AGENTS.md è una convenzione, non un runtime: ogni strumento decide come scoprire, fondere e iniettare il file.
  • Nessuno schema è imposto — una prosa chiara batte una struttura rigida.
  • Completa il tuo README; non lo sostituisce.

L'inghippo di Claude Code​

Ecco il punto su cui le persone inciampano: Claude Code legge CLAUDE.md, non AGENTS.md. Se il tuo repo ha solo un AGENTS.md, Claude Code lo ignora di default. Non è un bug — precede lo standard — ma significa che un repo multi-strumento ha bisogno di una strategia di sincronizzazione deliberata, altrimenti le tue istruzioni divergono silenziosamente.

Watch out
  • Non dare per scontato che Claude Code ricada su AGENTS.md — non lo legge automaticamente.
  • Due file mantenuti a mano (CLAUDE.md e AGENTS.md) divergeranno. Scegli un'unica fonte di verità.
  • Verifica il comportamento attuale nella documentazione ufficiale sulla memoria prima di affidarti a qualsiasi affermazione di fallback.

Mantieni un'unica fonte di verità​

Tre pattern mantengono CLAUDE.md e AGENTS.md sincronizzati senza duplicare i contenuti. Scegli in base alla piattaforma del tuo team.

Guided walkthrough1 of 3
  1. Rendi CLAUDE.md un symlink ad AGENTS.md. Claude Code segue i symlink e legge il target byte per byte — un solo file reale, zero logica di merge. Avvertenza: su Windows, creare un symlink richiede la Developer Mode o i diritti di amministratore, quindi i team cross-platform potrebbero preferire il metodo import.

Crea un symlink da CLAUDE.md allo standard condiviso (macOS / Linux)

ln -s AGENTS.md CLAUDE.md

Oppure tieni un CLAUDE.md di una riga che lo importa

@AGENTS.md
Pro tip
  • Usa il symlink quando tutto il team è su macOS/Linux — è ciò che richiede meno manutenzione.
  • Usa @import quando ci sono contributor su Windows.
  • Committa quello che scegli, così tutto il team ottiene lo stesso comportamento.

Come si fondono i file annidati e globali​

Gli agenti più sofisticati trattano AGENTS.md in modo gerarchico — lo stesso modello mentale della gerarchia di memoria di CLAUDE.md. Codex, per esempio, parte da un file globale nella tua home directory e scende attraverso la root Git fino alla cartella corrente, concatenando man mano:

I file più vicini al lavoro vincono, perché vengono concatenati per ultimi e sovrascrivono le indicazioni precedenti. Così un services/payments/AGENTS.md eredita le istruzioni della root del repo e aggiunge regole valide solo all'interno di quel servizio — metti le indicazioni specializzate il più vicino possibile al codice specializzato.

L'interoperabilità a colpo d'occhio
Premi Invio o Spazio per girare la carta. Usa le frecce sinistra e destra per spostarti tra le carte.Termine mostrato.
1 / 5

Cosa metterci dentro​

La stessa disciplina di un buon CLAUDE.md — lo standard suggerisce solo alcune sezioni comuni:

  • Panoramica del progetto — cos'è, in due frasi.
  • Comandi di build e test — come eseguire, testare e fare il lint.
  • Stile del codice — convenzioni che un agente non può dedurre.
  • Istruzioni di test — cosa significa "fatto".
  • Considerazioni di sicurezza — cosa non toccare o committare mai.
  • Linee guida per commit / PR — formato dei messaggi, regole sui branch.
Watch out
  • Gli agenti seguono il file alla lettera — istruzioni obsolete o velleitarie fanno attivamente male, esattamente come CLAUDE.md.
  • Tienilo breve e veritiero; descrivi come funziona il progetto oggi.
  • Non committare mai segreti; rimanda ai documenti voluminosi invece di incollarli.

Mettiti alla prova​

Mettiti alla prova

0/3
  1. Claude Code legge AGENTS.md automaticamente?
  2. Il tuo team è interamente su macOS e Linux. Qual è il modo con meno manutenzione per condividere un unico file di istruzioni tra Claude Code e Codex?
  3. Quando gli agenti fondono un AGENTS.md globale, uno nella root del repo e uno in una sottocartella, quale vince in caso di conflitto?
Key takeaways
  • AGENTS.md è lo standard aperto, governato dalla Linux Foundation, che oltre 30 coding agent leggono — un README per gli agenti.
  • Claude Code legge CLAUDE.md, non AGENTS.md, quindi i repo multi-strumento devono mantenerli sincronizzati.
  • Crea un symlink da CLAUDE.md → AGENTS.md su Mac/Linux, oppure usa un import @AGENTS.md di una riga per i team cross-platform.
  • I file annidati si fondono globale → root → sottocartella, con il file più vicino che vince.
  • Riempilo come un ottimo CLAUDE.md: panoramica, comandi di build/test, convenzioni, sicurezza e guardrail — breve e veritiero.

Prossimi passi​

Fonti e approfondimenti​