Come scrivere un AGENTS.md che aiuti davvero il tuo agente di coding IA

Se hai usato un agente di coding IA su un progetto reale, probabilmente hai raggiunto il momento in cui esegue il comando di test sbagliato, ignora il tuo formatter o reinventa un helper che hai già. La soluzione di solito non è un modello più intelligente — è dare all'agente il contesto specifico del progetto che non può dedurre. È a questo che serve un file AGENTS.md.

Cos'è AGENTS.md

AGENTS.md è un formato Markdown semplice e aperto che dà agli agenti di coding un posto prevedibile dove trovare il contesto e le istruzioni del progetto. È nato come collaborazione tra OpenAI Codex, Amp, Google Jules, Cursor e Factory, ed è ora gestito dall'Agentic AI Foundation sotto la Linux Foundation. Oltre 25 strumenti lo leggono — inclusi Codex, Cursor, VS Code, GitHub Copilot, Aider, Windsurf, JetBrains Junie, Zed e goose — e compare in più di 60.000 repository open-source.

Pensalo come un README scritto per l'agente invece che per un umano: il README spiega il tuo progetto a un nuovo contributore; AGENTS.md dice all'agente le cose che altrimenti indovinerebbe sbagliando. (Gli utenti di Claude Code riconosceranno CLAUDE.md come l'equivalente; molti team tengono entrambi, o fanno un symlink da uno all'altro.)

Dove va

Metti AGENTS.md nella radice del repository. In un monorepo, aggiungi file annidati dentro ogni package — gli agenti leggono il file più vicino nell'albero delle directory, così un packages/api/AGENTS.md ha la precedenza su quello della radice quando l'agente lavora in quella cartella. Questo permette a un servizio Python e a un frontend TypeScript di ricevere ciascuno istruzioni su misura.

Cosa metterci

Il formato è solo Markdown — usa le intestazioni che preferisci. Sezioni comunemente utili includono:

• Comandi di build e test — i comandi esatti, non approssimazioni
• Stile del codice — formatter, linter e ogni convenzione che un linter non intercetta
• Istruzioni di test — come eseguire un singolo test, cosa deve passare prima che una modifica sia conclusa
• Considerazioni di sicurezza — file o operazioni da non toccare mai
• Convenzioni di commit / PR — formato del messaggio, denominazione dei branch
• Passi di deployment — solo se ci si aspetta che l'agente li tocchi

Ecco un esempio minimale e ad alto segnale:

# AGENTS.md

## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev` (do NOT run in CI)
- Test a single file: `pnpm vitest run path/to/file.test.ts`
- Lint + typecheck before any commit: `pnpm check`

## Conventions
- Use the existing `db()` helper in `src/lib/db.ts`; never open a raw client.
- Dates are stored as UTC ISO strings. Never use `Date.now()` in tests.

## Do not touch
- `src/generated/**` is codegen output. Edit the schema, then run `pnpm gen`.

Nota cosa non c'è: nessuna lezione di architettura, nessuna ripetizione della struttura delle cartelle, nessun "questa è una moderna web app costruita con le best practice." È deliberato.

Di solito più corto è meglio

C'è la tentazione di chiedere all'agente di generare un gigantesco AGENTS.md per te. Resisti. Uno studio dell'ETH di Zurigo del 2026, riportato da InfoQ, ha misurato l'impatto reale di questi file e ha scoperto che l'effetto è marginale e contraddittorio. I file di contesto generati da LLM hanno in realtà ridotto i tassi di successo dei task di circa il 3% in media, alzando al contempo i costi di inferenza di oltre il 20%. I file scritti da umani hanno aiutato modestamente — circa un 4% di guadagno nel successo — ma hanno comunque spinto gli agenti a fare più passi, aumentando il costo fino a ~19%.

Il meccanismo è istruttivo: gli agenti seguono diligentemente qualunque cosa dica il file, così un documento sterminato dice loro di eseguire test extra, leggere più file ed effettuare controlli di qualità non necessari per il task in questione. La raccomandazione dei ricercatori: salta del tutto i file di contesto autogenerati e limita le istruzioni scritte da umani ai dettagli non deducibili — il tooling specifico e i comandi personalizzati che l'agente davvero non può scoprire da solo.

In altre parole, ogni riga dovrebbe guadagnarsi il posto prevenendo un errore concreto che hai effettivamente visto fare all'agente.

Un workflow che funziona

1. Parti vuoto. Non scrivere AGENTS.md finché non hai visto l'agente sbagliare qualcosa.
2. Aggiungi la correzione, non la teoria. Quando esegue il comando di test sbagliato, aggiungi quello giusto. Quando riformatta un file a modo suo e il linter protesta, aggiungi la regola.
3. Tienilo stringato. Se una riga ribadisce solo ciò che l'agente potrebbe leggere da package.json o dai nomi delle cartelle, cancellala.
4. Usa l'annidamento per i monorepo così il file di ogni package resta piccolo.
5. Rileggilo ogni mese. Le istruzioni obsolete sono peggio di nessuna — un agente che segue un comando di build superato fallisce con sicurezza.

I migliori file AGENTS.md si leggono come una concisa scheda di onboarding per quell'unico compagno di team che non dimentica mai ma che nemmeno deduce mai. Scrivi le cose che non possono indovinare, e nient'altro.