Che cos’è AGENTS.md e come scriverne uno in 30 minuti

Materiali pratici sul vibe coding e sul lavoro con gli agenti: documentazione Ailoot.

AGENTS.md in un paragrafo#

Di seguito, il formato viene esaminato facendo riferimento a agents.md, alla documentazione di OpenAI Codex, a JetBrains Junie, alla documentazione di Cursor Rules, al changelog di GitHub Copilot Coding Agent e al comunicato stampa della Linux Foundation sulla Agentic AI Foundation. Tutti i dati e le funzionalità sono aggiornati al 30 maggio 2026; il supporto di AGENTS.md in Claude Code è descritto secondo la documentazione di Anthropic, aggiornata il 24 settembre 2026.

Se non hai idea di cosa sia questo zoo di strumenti sul mercato o del motivo per cui abbiano bisogno di un file condiviso, leggi prima la guida «Con cosa programmare nel 2026: 8 strumenti di IA, da Claude Code ad Antigravity». Questo articolo si concentra proprio sul formato AGENTS.md e su come scriverne uno in 30 minuti.

Che cos’è AGENTS.md e da dove viene?#

In precedenza, ogni strumento di IA aveva il proprio file di regole: Anthropic aveva CLAUDE.md, Cursor .cursorrules, GitHub .github/copilot-instructions.md, Aider .aider.conf.yml e JetBrains .junie/guidelines.md. Se il tuo team aveva tre agenti diversi, questo significava tre file paralleli con gli stessi contenuti, destinati a divergere nel giro di una settimana.

OpenAI è stata la prima a stancarsi di questa situazione. Nell’agosto 2025 ha pubblicato Codex CLI e lanciato contemporaneamente agents.md come formato aperto. Dal sito:

«Considera AGENTS.md come un README per gli agenti.»

(agents.md, tradotto dall’inglese)

Il punto fondamentale è che AGENTS.md integra README. README è scritto per le persone: «cos’è il progetto, come eseguirlo in locale, come contribuire». AGENTS.md è scritto per l’agente: comandi shell esatti, criteri di completamento verificabili e limiti come «non toccare mai questo».

Dal sito:

«AGENTS.md integra README: contiene ulteriore contesto, a volte dettagliato, di cui l’agente ha bisogno: passaggi di compilazione, test e convenzioni che appesantirebbero README o che semplicemente non servono ai collaboratori umani.»

(agents.md, tradotto dall’inglese)

Entro settembre 2025, GitHub Copilot Coding Agent supportava il formato (changelog, 28.08.2025). A dicembre si erano aggiunti Cursor, Junie, Gemini CLI, Aider e un’altra dozzina di strumenti. Il 9 dicembre 2025, la Linux Foundation ha costituito la Agentic AI Foundation (AAIF): i suoi tre progetti fondatori erano AGENTS.md di OpenAI, MCP di Anthropic e goose di Block. I membri fondatori erano AWS, Anthropic, Block, Bloomberg, Cloudflare, Google, Microsoft e OpenAI. Entro il 24 febbraio 2026, la fondazione comprendeva già 146 organizzazioni, tra cui Red Hat, ServiceNow, Akamai, Lenovo, JPMorgan Chase, Huawei, UiPath e Hitachi.

Da quel momento, AGENTS.md ha smesso di essere «l’ennesima cosa di OpenAI» ed è diventato uno standard de facto.

Quali agenti di IA leggono AGENTS.md e quali no?#

Tabella del supporto aggiornata al 30 maggio 2026; la riga di Claude Code è stata aggiornata il 24 settembre 2026:

Anthropic è stata l’ultima tra i grandi operatori ad aderire. Nell’agosto 2025 è stata aperta nel repository ufficiale anthropics/claude-code la issue #6235, che chiedeva il supporto ad AGENTS.md.

La issue è rimasta aperta per quasi un anno ed è stata chiusa il 17 agosto 2026; la versione 2.1.277 con supporto per AGENTS.md è uscita il 18 settembre. La logica di Anthropic è la seguente: CLAUDE.md ha la precedenza e AGENTS.md viene letto quando non c’è CLAUDE.md nella cartella di lavoro o in una delle sue cartelle genitrici. Secondo la documentazione, funziona così:

Il punto è che anche un file personale CLAUDE.local.md viene considerato e, in sua presenza, Claude Code smette di leggere AGENTS.md. Puoi modificare questo comportamento in /config, nella sezione Project instructions, per esempio per far leggere a Claude Code entrambi i file contemporaneamente. Nelle versioni precedenti alla 2.1.277, AGENTS.md non viene caricato automaticamente; la riga @AGENTS.md in CLAUDE.md resta la soluzione alternativa.

In che modo AGENTS.md è diverso da CLAUDE.md e .cursorrules?#

Confronto tra i quattro formati aggiornato al 30 maggio 2026:

L’idea chiave è che AGENTS.md può contenere le istruzioni condivise del progetto, mentre il caricamento e le impostazioni personali richiedono ancora una configurazione distinta per ogni client. Claude Code ha CLAUDE.local.md per questo e Cursor ha file .mdc locali sotto user. AGENTS.md da solo non offre questa possibilità: occorre combinarlo con altri file oppure accordarsi in team per scrivere le regole personali in sezioni escluse da git.

Un altro dettaglio importante riguarda i monorepo. Codex e Cursor applicano la regola «vince l’AGENTS.md più vicino»:

«In un monorepo, inserisci un AGENTS.md separato in ogni pacchetto. Gli agenti leggono automaticamente il file più vicino nella struttura delle directory e quello più vicino prevale.»

(agents.md, tradotto dall’inglese)

Il sito agents.md menziona che il monorepo principale di OpenAI contiene 88 file AGENTS.md per diversi sottopacchetti. Se lavori in un monorepo, distribuisci le regole su più livelli: regole generali alla radice, regole specifiche nelle sottocartelle.

Cosa dovrebbe contenere un buon AGENTS.md?#

Il sito agents.md propone un formato flessibile, «qualsiasi Markdown». Ma l’80% dei buoni file esistenti contiene le stesse otto sezioni. Regola principale: ogni voce dovrebbe essere un comando esatto o un esempio concreto. Un’idea astratta come «scrivi codice pulito» verrà ignorata dall’agente.

1. Panoramica del progetto — 2–3 righe. Cos’è il progetto, a chi è destinato e qual è il suo obiettivo principale. Niente marketing. Esempio: «Bot Telegram per l’onboarding a un workshop a pagamento. Stack: Next.js 14, Prisma, PostgreSQL. Si attiva quando viene aggiunto un nuovo record a purchases.»
2. Comandi di configurazione — comandi shell esatti per l’esecuzione in locale. npm install, npm run dev, npm run build. Niente «di solito facciamo così».
3. Stile del codice / convenzioni — regole specifiche con un esempio, non «scrivi in modo pulito». Per esempio: «TypeScript strict, apici singoli, niente esportazioni predefinite, nomi dei componenti in PascalCase, gli hook iniziano con use.»
4. Suggerimenti per l’ambiente di sviluppo — dove si trovano le cose importanti. Quali variabili servono in .env, dove sono conservati i segreti, quali porte sono in uso e come lavorare con il DB locale.
5. Istruzioni per i test — come eseguire un test specifico e cosa significa che è «verde». Per esempio: npm test -- --testPathPattern=user-auth; ci si aspetta il 100% dei test superati.
6. Linee guida per PR / commit — formato dei messaggi di commit, checklist prima della PR (test, linter, documentazione) e chi approva.
7. Considerazioni sulla sicurezza — cosa non deve mai accadere. «Non eseguire mai il commit di .env. I segreti devono stare solo in Vault. Non mostrare nei log i dati personali degli utenti.»
8. Limiti / Non fare mai questo — divieti con un’alternativa. «Non usare git push --force su main. Se devi annullare una modifica, usa git revert o git reset su un feature branch.»

Per ogni sezione, applica il principio «un comando invece di un’idea». L’agente ignorerà «fai attenzione alle migrazioni». Seguirà invece «Prima di alembic upgrade head, esegui alembic check. Se segnala un errore, non applicare la migrazione; chiedimelo».

Modello AGENTS.md pronto all’uso (copia e adatta)#

# AGENTS.md

## Project overview

<project-name> - <one phrase describing its purpose>.
Stack: <Next.js / Python / Go / ...>.
Main entities: <users, orders, posts ...>.
Details for people are in README.md.

## Setup commands

```bash
# first install
npm install
cp .env.example .env  # then fill in manually; see list below

# run
npm run dev           # dev server on :3000
npm run build         # production build
npm run start         # run production build
```

## Dev environment

- Node 20+ (via nvm: `nvm use 20`)
- PostgreSQL 16 locally on :5432 (`docker-compose up postgres`)
- Redis is optional, needed only for queues (`docker-compose up redis`)
- `.env`: `DATABASE_URL`, `STRIPE_KEY`, `RESEND_API_KEY`, `JWT_SECRET`
- Never read the entire `.env` file. If you need one variable: `grep "^VAR=" .env`

## Code style

- TypeScript strict mode
- Single quotes, no semicolons (unless ESLint requires them)
- Imports: external first, then internal via `@/`, then relative
- Components in PascalCase; hooks start with `use`
- No `any` without an explicit comment explaining “why it can’t be typed”

Example of a good module:

```ts
import { z } from 'zod'

const UserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(2),
})

export function parseUser(raw: unknown) {
  return UserSchema.parse(raw)
}
```

## Testing

```bash
npm test                                # all tests
npm test -- --testPathPattern=auth      # auth only
npm test -- --watch                     # watch mode
```

All tests must pass (be green) before committing. If a test is red, don’t commit; ask me what to do.

## Pull request guidelines

- Commit format: `<type>(<scope>): <description>` (`feat(auth): add magic-link`)
- Before PR: `npm run build && npm test && npm run lint`
- PR description = what changes, why, and how to test
- Don’t approve your own PR—always wait for human review

## Security

- Secrets only in `.env` and Vault, never in code
- Don’t log personal data (email, phone, name)
- When working with the production DB, use read-only queries only unless explicitly authorized
- Don’t hardcode external service API keys (Stripe, OpenAI) in tests

## Never do this

- Don’t `git push --force` to main. If you need to roll back, use `git revert` or open a new PR
- Don’t run DB migrations without `alembic check` (or the equivalent in your ORM)
- Don’t use `npm install -g` or `sudo` for project dependencies
- Don’t add dependencies without approval (especially heavy ones: webpack plugins, ORM)

In media, il modello contiene 80–120 righe. Se il file supera le 150 righe, è un segnale che serve riorganizzarlo: sposta qualcosa in docs/, aggiungi un collegamento o comprimi qualcosa in una riga. In pratica, i file di 100–150 righe funzionano meglio; oltre quel punto, i miglioramenti della qualità iniziano a invertirsi.

Quali 5 regole rendono AGENTS.md davvero utile?#

1. Comandi invece di idee. Un agente non capisce «fai attenzione alle migrazioni». Seguirà alembic check prima di alembic upgrade head. Gli agenti lavorano con comandi e condizioni, non con stati d’animo. Formula tutte le regole chiave come «fai X, altrimenti Y».

2. Divieti accompagnati da un’alternativa. Un semplice «non eseguire un force push» viene ignorato silenziosamente dall’agente dopo due o tre prompt. Funziona l’abbinamento «non fare X; fai Y invece». Esempio: «non usare git push --force su main; se devi annullare una modifica, usa git revert o apri una nuova PR».

3. Una sola fonte di verità. L’AGENTS.md nella radice è la fonte di verità per l’intero progetto. Se hai un monorepo, usa file AGENTS.md annidati nelle sottocartelle, seguendo la regola «vince quello più vicino». Niente file paralleli con istruzioni in conflitto.

4. Criteri di completamento verificabili. «I test devono passare» non serve a nulla. Un criterio preciso è: npm test restituisce il codice di uscita 0 e non stampa FAIL su stdout. Anche «il codice deve essere pulito» non serve a nulla. Un criterio preciso è: npm run lint termina senza avvisi. Un agente capisce cosa significa «completato» solo se descrivi esplicitamente la condizione.

5. Un file più corto di 150 righe. Oltre le 150 righe, le metriche iniziano a peggiorare: l’agente impiega più contesto a leggere il file e si perde le regole importanti. Se non ci sta, sposta i dettagli in docs/architecture.md e collegalo da AGENTS.md, lasciando nel file solo comandi e limiti.

Quali 10 errori trasformano AGENTS.md in spazzatura?#

1. Regole vaghe senza comandi. L’agente ignorerà «fai attenzione alle migrazioni»: per lui è una frase vuota. Funziona solo un comando specifico con una condizione: «Esegui alembic check prima di alembic upgrade head. Se c’è un errore, non applicare la migrazione; chiedimelo».

2. «Codice pulito». Una frase inutile. Sostituiscila con uno schema specifico: «Usa componenti funzionali con hook. Esempio: function LoginForm() { const [email, setEmail] = useState(''); ... }».

3. Prosa senza struttura. Se AGENTS.md contiene 300 righe di prosa senza titoli, l’agente impiegherà 80K token di contesto in passaggi irrilevanti e si perderà ciò che conta. Usa titoli H2/H3, sezioni brevi ed elenchi puntati.

4. Un file più lungo di 150 righe. Le metriche di qualità peggiorano oltre questa soglia. Dividilo in un file principale e collegamenti ai dettagli in docs/.

5. Oltre 30 divieti senza alternative. Se il file contiene un lungo elenco di «non fare X, non fare Y» senza spiegare «fai invece Z», l’agente procederà a tentoni.

6. Duplicare README.md. Se hai già scritto in README «come installare ed eseguire», non copiarlo in AGENTS.md. Rimanda invece a README con una riga e descrivi in AGENTS.md ciò di cui l’agente ha bisogno ma i collaboratori umani no.

7. Includere segreti nel codice. AGENTS.md potrebbe essere pubblico, perché si trova in git. Non inserire chiavi API, token o password reali. Includi solo riferimenti agli archivi dei segreti: «Vedi Vault: secret/staging/db».

8. Priorità in conflitto senza gerarchia. «Procedi velocemente» + «mantieni una copertura dei test del 90%» lascia l’agente indeciso su cosa scegliere. Ordinale esplicitamente: «Prima copertura dei test ≥80%, poi velocità. Se sono in conflitto, hanno la precedenza i test».

9. Documentazione obsoleta. Una descrizione dell’architettura che parla di REST + polling quando ormai si usano WebSocket. L’agente segue la descrizione obsoleta e compromette l’architettura. Regola: aggiorna AGENTS.md nella stessa PR del codice ogni volta che cambia l’architettura.

10. Eccesso di architettura per un compito semplice. Se qualcuno ha chiesto di modificare due righe in una configurazione, l’agente non dovrebbe dover leggere l’intera topologia di 14 microservizi. Sposta l’architettura «approfondita» in docs/architecture.md; in AGENTS.md lascia solo «se il compito riguarda l’architettura, leggi docs/architecture.md».

Lo studio del GitHub Blog su oltre 2.500 repository AGENTS.md riporta la conclusione principale:

«La maggior parte dei file per agenti non funziona perché è troppo generica. “Sei un assistente di programmazione disponibile” non funziona.»

(GitHub Blog, tradotto dall’inglese)

Come mantenere AGENTS.md e CLAUDE.md nello stesso repository?#

La principale questione pratica è come convivere con entrambi i file senza duplicare i contenuti. Ci sono tre scenari:

Scenario 1: solo Claude Code. Tieni CLAUDE.md e usa tutte le funzionalità di Claude Code: ~/.claude/CLAUDE.md per le istruzioni a livello utente, CLAUDE.md per il progetto, CLAUDE.local.md per le personalizzazioni personali, @import per includere altri file e .claude/skills/ per le skill specializzate. AGENTS.md non serve.

Scenario 2: più client di programmazione. Conserva le regole condivise in AGENTS.md, poi collega e verifica ogni client separatamente. Gemini CLI permette di configurare il nome del file di contesto; Aider può caricare un file tramite la configurazione di lettura. Sono percorsi espliciti, non una scoperta automatica identica.

In un repository di prova innocuo, avvia una sessione nuova e aggiungi un’istruzione univoca innocua, come «includi il marcatore instructions-loaded nella risposta di prova». Controlla la vista documentata dei file caricati o i log del client, oltre alla risposta. Ripeti per ogni client e versione che usi davvero. Una risposta del modello che afferma di aver letto il file non è una prova indipendente del caricamento; un test riuscito non dimostra il supporto in tutti gli altri strumenti.

Scenario 3: team misto (Claude Code + altri strumenti). È la configurazione più comune nel 2026. La soluzione è rendere AGENTS.md il file principale. Se non hai regole riservate a Claude Code, non creare affatto CLAUDE.md: dalla versione 2.1.277, Claude Code legge AGENTS.md quando il progetto non contiene CLAUDE.md. Se invece hai regole di questo tipo, crea CLAUDE.md come collegamento simbolico o come breve file di rimando con un’importazione @AGENTS.md.

Prima di modificare i file, esaminali e salvane una copia. Se esistono entrambi, unisci le istruzioni condivise non contraddittorie in AGENTS.md e conserva quelle specifiche di Claude in CLAUDE.md con @AGENTS.md. Conserva i collegamenti simbolici esistenti anziché sostituirli.

Solo per un CLAUDE.md regolare quando AGENTS.md è assente, questo controllo macOS/Linux rifiuta di sovrascrivere un file o collegamento già presente:

if [ -e AGENTS.md ] || [ -L AGENTS.md ]; then
  printf '%s\n' 'STOP: AGENTS.md esiste; unire prima i due file.' >&2
elif [ -f CLAUDE.md ] && [ ! -L CLAUDE.md ]; then
  mv CLAUDE.md AGENTS.md && ln -s AGENTS.md CLAUDE.md
else
  printf '%s\n' 'STOP: esaminare prima il percorso CLAUDE.md esistente.' >&2
fi

Dopo la rinomina riuscita, CLAUDE.md è un collegamento simbolico ad AGENTS.md. Tutti gli agenti che leggono AGENTS.md vedono gli stessi contenuti. Claude Code, che legge CLAUDE.md, vede le stesse istruzioni tramite il collegamento simbolico.

Su Windows, creare un collegamento simbolico richiede la Modalità sviluppatore (o i privilegi di amministratore), cosa che potrebbe non essere comoda per tutto il team. Un’alternativa è un CLAUDE.md breve che importa AGENTS.md:

# CLAUDE.md

@AGENTS.md

## Claude Code specific

- Use .claude/skills/ for specialized prompts
- When working with Skills, consult .claude/skills/INDEX.md
- Use Plan Mode before major changes (Shift+Tab)

In Claude Code, questa sintassi importa AGENTS.md con una sola riga e aggiunge sotto le specificità di Claude Code. Se in seguito vuoi rimuovere AGENTS.md, basta eliminare l’importazione. Questa riga non provoca una doppia lettura: secondo la documentazione di Claude Code, il file AGENTS.md non viene caricato due volte, neanche se è già accessibile autonomamente.

Disposizione canonica per un team che usa più strumenti nel 2026:

repo-root/
├── AGENTS.md                              # fonte di verità, ≤150 righe
├── CLAUDE.md                              # solo se ci sono regole specifiche per Claude: collegamento simbolico → AGENTS.md OPPURE @AGENTS.md + aggiunte
├── .cursor/rules/                         # eccezioni mirate solo per Cursor
├── .github/copilot-instructions.md        # “Vedi AGENTS.md”, se usato
└── docs/architecture.md                   # architettura approfondita richiamata da AGENTS.md

Maggiori informazioni su CLAUDE.md sono disponibili nella guida «Come configurare correttamente CLAUDE.md». Per approfondire il motivo per cui un agente ha bisogno di un file di istruzioni lungo, leggi «Che cos’è il context engineering».

Cosa è cambiato nel 2026: perché AAIF ha portato AGENTS.md sotto la Linux Foundation?#

La principale vicenda politica del maggio 2026 nella programmazione con IA non è stata un’altra uscita di un modello, ma il consolidamento dei formati. In precedenza, ogni fornitore aveva il proprio file di regole: una soluzione comoda per i fornitori ma scomoda per i team che lavoravano con diversi strumenti.

In un comunicato stampa del 9 dicembre 2025, la Linux Foundation ha annunciato la Agentic AI Foundation come riferimento comune per tre formati:

• AGENTS.md di OpenAI — un formato di file di istruzioni per agenti
• Model Context Protocol (MCP) di Anthropic — un protocollo per collegare strumenti esterni agli agenti
• goose di Block — un framework open source per agenti

Dal comunicato stampa della Linux Foundation:

«Riunire questi progetti sotto l’ombrello della AAIF garantisce che possano svilupparsi con la trasparenza e la stabilità che solo una governance aperta può offrire.»

(comunicato stampa della Linux Foundation, 9 dicembre 2025, tradotto dall’inglese)

Entro il 24 febbraio 2026, 146 organizzazioni facevano parte della AAIF (97 nuovi membri in due mesi). Tra i nuovi membri Gold c’erano Red Hat, ServiceNow, Akamai, Lenovo, JPMorgan Chase, Huawei, Hitachi, UiPath, American Express e Autodesk. Anthropic è al livello Platinum e promuove MCP. OpenAI è al livello Platinum e promuove AGENTS.md. Block è al livello Platinum con goose.

Questo cambia il posizionamento di AGENTS.md: da «formato OpenAI» a standard di settore. Nella primavera del 2026, Claude Code era ancora in disparte, ma a settembre, con la versione 2.1.277, ha imparato a leggere autonomamente AGENTS.md. CLAUDE.md non è scomparso e, per impostazione predefinita, ha ancora la precedenza se è presente nel progetto.

Un punto di partenza pratico è conservare le regole condivise del progetto in AGENTS.md e configurare per ogni client l’importazione, il file intermedio o la lettura esplicita richiesti. Per Claude Code, verifica la versione installata e la precedenza dei file di istruzioni prima di scegliere un’importazione in CLAUDE.md o un collegamento simbolico. Verifica il caricamento in ogni client: qui non è stata accertata alcuna percentuale di copertura.

E adesso?#

AGENTS.md è il primo elemento fondamentale per «mettersi d’accordo con un agente affinché lavori in modo prevedibile». Il secondo è una cartella di conoscenze del progetto, che contiene il contesto aziendale, il pubblico, i prodotti e i prezzi. Il terzo è il context engineering, che riunisce tutto: quali file vede l’agente a ogni passaggio, come viene conservato lo stato tra le sessioni e come passare da un modello all’altro.

Materiali pratici: documentazione Ailoot.

Altri materiali e strumenti: Ailoot.