Come scrivere un file AGENTS.md perché qualsiasi agente di coding IA capisca il tuo progetto

Se ti è mai capitato di vedere un agente di coding IA eseguire il comando di test sbagliato, formattare il codice in uno stile vietato dal tuo progetto, o reinventare un helper che esiste già, la soluzione di solito non è un modello più intelligente — è il contesto. AGENTS.md è il modo standard per fornire agli agenti quel contesto, e funziona su quasi tutti gli strumenti.

Cos'è davvero AGENTS.md

AGENTS.md è "un README per agenti": un semplice file Markdown che collochi nella radice del tuo repository per spiegare agli strumenti di coding IA come funziona il tuo progetto (agents.md). Non è un nuovo linguaggio di configurazione — non ci sono campi obbligatori né sintassi speciale. Usa qualsiasi intestazione Markdown tu voglia.

Il formato conta perché è genuinamente cross-tool. A metà 2026 viene letto nativamente da OpenAI Codex, GitHub Copilot, Cursor, Windsurf, Devin, Aider, Zed, VS Code, JetBrains Junie e decine di altri — oltre 28 strumenti e più di 60.000 repository open-source (agents.md; Codersera). È ora gestito dalla Agentic AI Foundation della Linux Foundation, accanto al Model Context Protocol di Anthropic. Anche Claude Code legge AGENTS.md, sebbene il suo formato nativo più ricco resti CLAUDE.md (DeployHQ).

Un solo file, e la maggior parte dei tuoi strumenti si comporta in modo coerente.

Perché un file batte il ripetersi in chat

Quando incolli le istruzioni in un messaggio di chat, esse vivono per esattamente una conversazione. La sessione successiva — o il prossimo collega, o un agente cloud che esegue il tuo compito durante la notte — riparte da zero. Un AGENTS.md viene caricato automaticamente all'inizio di ogni esecuzione, così le tue convenzioni vengono applicate per impostazione predefinita invece di dipendere dal fatto che tu ti sia ricordato di menzionarle. È tutto qui il punto: spostare la conoscenza del progetto fuori dalla tua testa e fuori dalle chat usa-e-getta, dentro un file che gli strumenti leggono ogni volta.

Cosa metterci dentro

Pensa a ciò di cui avrebbe bisogno un nuovo collega competente al primo giorno — è esattamente ciò di cui ha bisogno un agente. Le sezioni più utili sono:

• Panoramica del progetto — un paragrafo su cos'è e sullo stack tecnologico.
• Comandi di setup e build — i comandi esatti per installare, avviare e compilare.
• Testing — come eseguire i test, e la regola che i test devono passare prima che una modifica sia considerata conclusa.
• Stile del codice — formatter, linter, convenzioni di denominazione, pattern da preferire o evitare.
• Linee guida per commit e PR — formato dei messaggi, regole sui branch, cosa non toccare.
• Insidie — qualsiasi cosa non ovvia che manda in errore le persone.

Sii concreto. "Scrivi codice pulito" non dice nulla a un agente. "Usa pnpm, non npm; esegui pnpm test prima di concludere; non modificare mai i file in src/generated/" è applicabile.

Un esempio concreto

Ecco un AGENTS.md compatto per una tipica web app:

# AGENTS.md

## Project
Next.js 15 + TypeScript storefront. Package manager is pnpm.

## Setup & commands
- Install: `pnpm install`
- Dev server: `pnpm dev`
- Build: `pnpm build`

## Testing
- Run all tests: `pnpm test`
- All tests must pass before a task is considered done.

## Code style
- TypeScript strict mode; no `any`.
- Format with Prettier (`pnpm format`) — do not hand-format.
- Prefer named exports. Reuse helpers in `src/lib/` before writing new ones.

## Do not touch
- `src/generated/**` is auto-generated. Never edit by hand.
- Never commit `.env` files.

Passalo a Claude Code, Cursor o Copilot e ciascuno di essi recepirà le stesse regole.

Monorepo: usa file annidati

In un monorepo puoi collocare un AGENTS.md in ogni pacchetto oltre a uno nella radice. Quando un agente lavora all'interno di una sottodirectory, vince il file più vicino (agents.md). Tieni le convenzioni condivise nella radice e i comandi specifici del pacchetto nei file annidati, così un agente che modifica packages/api/ ottiene automaticamente i comandi di build e di test di quel pacchetto.

AGENTS.md vs CLAUDE.md vs regole di Cursor

Potresti già avere file specifici per strumento come CLAUDE.md o .cursor/rules. Non devi buttarli via. In pratica, i team mettono le convenzioni condivise e indipendenti dallo strumento in AGENTS.md — ciò di cui ogni agente ha bisogno — e mantengono gli extra specifici nel file nativo dello strumento che supporta funzionalità più ricche (DeployHQ). Claude Code, per esempio, legge entrambi, con CLAUDE.md come suo formato più espressivo. Un pattern comune è mantenere un unico AGENTS.md canonico e, dove uno strumento ha bisogno di un proprio file, far puntare quel file ad AGENTS.md così da avere un'unica fonte di verità. Inizia con AGENTS.md; ricorri al file specifico dello strumento solo quando ti serve una funzionalità che soltanto esso supporta.

Tienilo breve e specifico

Di più non è meglio. Un AGENTS.md gigantesco che ribadisce l'intera tua guida di stile compete per l'attenzione del modello e seppellisce le regole che contano davvero. Punta a quella manciata di cose che un agente sbaglierebbe senza indicazioni — il comando non ovvio, la directory da non toccare, il pattern che il tuo codebase preferisce. Se una regola è già ovvia dal codice, probabilmente non hai bisogno di scriverla.

Come tenerlo utile

Un AGENTS.md si guadagna il suo posto solo se resta veritiero. Trattalo come codice: quando un comando o una convenzione cambia, aggiorna il file nello stesso commit. E quando un agente commette lo stesso errore due volte, non limitarti a correggerlo in chat — scrivi la regola. Quell'unica abitudine trasforma ogni passo falso in una correzione permanente, ed è la cosa a più alto impatto che puoi fare per rendere gli agenti IA affidabili sul tuo progetto.