AGENTS.md: La guida basata sulla ricerca per rendere gli agenti IA il 29% più veloci
Un nuovo studio arxiv lo ha dimostrato nero su bianco: i file AGENTS.md rendono gli agenti di codifica IA 28,6% più veloci e risparmiano 16,6% di token. Mentre la maggior parte degli sviluppatori sta ancora discutendo se hanno bisogno di un tale file, noi di Context Studios utilizziamo AGENTS.md fin dal primo giorno — e la ricerca conferma ora ciò che già sapevamo dalla pratica.
In questa guida, mostriamo cosa dice la ricerca, come strutturare in modo ottimale il vostro AGENTS.md e quali contenuti specifici hanno il maggiore impatto. Con esempi reali dal nostro workspace.
Cos'è AGENTS.md?
AGENTS.md è un formato aperto per guidare gli agenti di codifica IA. Progettato come un README per gli agenti, il file è ora utilizzato da oltre 60.000 progetti open-source su GitHub e supportato da un ecosistema in crescita — tra cui OpenAI Codex, Google Jules, Cursor, Amp e Factory.
Il concetto è semplice: mentre README.md è progettato per gli esseri umani (descrizioni del progetto, quickstart, linee guida per i contributi), AGENTS.md fornisce il contesto di cui gli agenti IA hanno bisogno — passaggi di build, comandi di test, convenzioni di codifica e struttura del progetto.
Da gennaio 2026, AGENTS.md è gestito dalla Agentic AI Foundation sotto la Linux Foundation. Il formato non è uno strumento proprietario ma uno standard aperto.
La ricerca: 28,6% più veloce, 16,6% meno token
Lo studio "On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents" (Lulla et al., arxiv 2601.20404, gennaio 2026) fornisce le prime prove empiriche dell'impatto di AGENTS.md:
Design dello studio
- 10 repository, 124 pull request analizzate
- Agente: GPT-5.2-Codex (OpenAI)
- Design accoppiato: ogni compito eseguito con e senza AGENTS.md
- Ambienti Docker isolati per la riproducibilità
- Metriche: tempo di esecuzione e consumo di token
I risultati
| Metrica | Senza AGENTS.md | Con AGENTS.md | Miglioramento |
|---|---|---|---|
| Tempo mediano | 98,57s | 70,34s | −28,64% |
| Tempo medio | 162,94s | 129,91s | −20,27% |
| Token output mediano | 2.925 | 2.440 | −16,58% |
| Token output medio | 5.744 | 4.591 | −20,08% |
| Token input medio | 353.010 | 318.651 | −9,73% |
Le statistiche sono significative (test di Wilcoxon, p < 0,05).
Perché funziona?
I ricercatori ipotizzano che AGENTS.md migliori l'efficienza perché gli agenti passano meno tempo nella navigazione esplorativa. Invece di scoprire da soli la struttura e le convenzioni del progetto, ricevono queste informazioni direttamente — meno iterazioni di pianificazione, meno richieste ripetute al modello.
Nella discussione su Hacker News sullo studio, un commentatore riassume perfettamente: "AGENTS.md is context. Models have been trained to follow context since the dawn of the thing." A differenza delle Skills che gli agenti devono invocare attivamente, AGENTS.md è contesto passivo — sempre disponibile, nessuna decisione necessaria.
Cosa inserire in un buon AGENTS.md?
GitHub ha analizzato oltre 2.500 repository e identificato i pattern dei file AGENTS.md di successo. Le sei aree fondamentali da coprire:
1. Comandi
Posizionate i comandi eseguibili all'inizio — con flag e opzioni:
## Setup & Build
- Installazione: \`pnpm install\`
- Server dev: \`pnpm dev\`
- Build: \`pnpm build\`
- Lint: \`pnpm lint --fix\`
2. Istruzioni per i test
## Testing
- Test unitari: \`pnpm test\`
- Test singolo: \`pnpm vitest run -t "nome del test"\`
- Test E2E: \`pnpm playwright test\`
- Tutti i test devono passare prima del commit
3. Struttura del progetto
## Architecture
- \`src/app/\` — Pagine Next.js 16.1 App Router
- \`src/components/\` — Componenti React 19 (Shadcn UI)
- \`convex/\` — Backend Convex (Query, Mutazioni, Azioni)
- \`public/\` — Asset statici
4. Stile del codice
Un vero esempio di codice vale più di tre paragrafi di descrizione:
## Code Style
- TypeScript modalità strict
- Tailwind v4.1 per lo styling (Config CSS-First)
- Preferire i pattern funzionali
- Nessun tipo \`any\` — sempre tipi espliciti
5. Workflow Git
## Git
- Denominazione branch: \`feat/\`, \`fix/\`, \`refactor/\`
- Messaggi di commit: Conventional Commits
- Eseguire sempre \`pnpm lint && pnpm test\` prima del commit
6. Limiti (Boundaries)
Dite all'agente cosa non deve mai toccare:
## Boundaries
- ✅ Sempre: scrivere test per il nuovo codice
- ⚠️ Chiedere prima: modifiche allo schema del database
- 🚫 Mai: committare segreti, modificare file .env, toccare configurazioni di produzione
In pratica: Il nostro AGENTS.md in Context Studios
Eseguiamo i nostri workflow IA con Claude Opus 4.5 e Claude Code 2.1. Il nostro file AGENTS.md è un documento vivente cresciuto nel corso dei mesi. Ecco gli elementi chiave:
Bootstrapping della sessione
Il nostro AGENTS.md definisce cosa l'agente deve leggere ad ogni avvio di sessione — identità (SOUL.md), contesto utente (USER.md), note quotidiane e memoria a lungo termine. Questo elimina completamente la fase "Chi sono?".
Sistema di memoria
Invece di "note mentali" (che si perdono al riavvio), scriviamo tutto nei file:
- Note quotidiane:
memory/YYYY-MM-DD.md— log grezzi - Memoria a lungo termine:
MEMORY.md— ricordi curati
La regola: "Text > Brain." Ciò che non è in un file non esiste.
Linee guida di sicurezza
Limiti chiari tra "sicuro senza chiedere" e "chiedere prima":
- Libero: Leggere file, cercare sul web, lavorare nel workspace
- Chiedere prima: Inviare email, pubblicare tweet, tutto ciò che esce dalla macchina
Heartbeat proattivi
Il nostro agente non aspetta semplicemente i comandi — utilizza heartbeat regolari per controllare email, verificare calendari e svolgere lavoro di fondo.
Avanzato: AGENTS.md annidati per i monorepo
Per grandi monorepo, AGENTS.md supporta file annidati. L'agente legge automaticamente il file più vicino nell'albero delle directory. Il repository di OpenAI ha 88 file AGENTS.md per diversi sottoprogetti.
my-monorepo/
├── AGENTS.md ← Istruzioni globali
├── packages/
│ ├── frontend/
│ │ └── AGENTS.md ← Specifico per il frontend
│ ├── backend/
│ │ └── AGENTS.md ← Specifico per il backend
│ └── shared/
│ └── AGENTS.md ← Librerie condivise
Compatibilità degli agenti
AGENTS.md funziona con tutti i principali agenti di codifica:
| Agente | Supporto |
|---|---|
| OpenAI Codex | Nativo — AGENTS.md è nato qui |
| Claude Code 2.1 | Legge AGENTS.md automaticamente |
| GitHub Copilot | Supporto completo + agenti personalizzati |
| Google Jules | Supporto nativo |
| Cursor | Compatibile via Rules |
| Amp | Supporto nativo |
| Aider | Configurabile via .aider.conf.yml |
| Gemini CLI | Configurabile via settings.json |
Le sei regole più importanti per il vostro AGENTS.md
Basate sulla ricerca, l'analisi di GitHub e la nostra esperienza:
- Comandi prima — Setup, build, test, lint in cima
- Esempi di codice invece di prosa — Uno snippet vale tre paragrafi
- Definire limiti chiari — Cosa l'agente non deve mai toccare
- Nominare lo stack in modo specifico — "Next.js 16.1 con TypeScript e Tailwind v4.1", non "progetto React"
- Documento vivente — Aggiornare regolarmente quando le convenzioni cambiano
- Restare concentrati — Niente file lunghissimi; gli agenti hanno finestre di contesto
Calcolo del ROI: Perché AGENTS.md è redditizio immediatamente
Consideriamo un team di sviluppo tipico di 5 sviluppatori che eseguono 20 compiti agente al giorno:
- Senza AGENTS.md: 100 compiti × 98,57s = ~2,7 ore di esecuzione/giorno
- Con AGENTS.md: 100 compiti × 70,34s = ~1,95 ore di esecuzione/giorno
- Risparmio: ~45 minuti di esecuzione al giorno + 16,6% meno costi token
Ai prezzi attuali delle API su un anno, questo si accumula in migliaia di dollari di costi computazionali risparmiati — senza contare il tempo risparmiato dagli sviluppatori.
Domande Frequenti (FAQ)
Qual è la differenza tra AGENTS.md e README.md?
README.md è per gli umani — descrizioni del progetto, guide all'installazione, linee guida per i contributi. AGENTS.md è per gli agenti IA — comandi di build, istruzioni per i test, convenzioni di codifica e struttura del progetto. Entrambi i file si completano: il README spiega cosa fa il progetto, AGENTS.md spiega come un agente deve lavorarci.
Ho bisogno di un file di configurazione separato per ogni agente IA?
No. AGENTS.md è uno standard aperto supportato da tutti i principali agenti di codifica — OpenAI Codex, Claude Code 2.1, GitHub Copilot, Google Jules, Cursor e altri. Un singolo file AGENTS.md funziona ovunque. Alcuni agenti (come Aider o Gemini CLI) hanno bisogno di una breve riga di configurazione per leggere AGENTS.md.
Quanto dovrebbe essere lungo un file AGENTS.md?
Il più corto possibile, il più lungo necessario. Gli agenti IA hanno finestre di contesto (Claude Opus 4.5: 200K token, GPT-5.2: 400K token, Gemini 3 Pro: 2M token), e ogni istruzione non necessaria consuma capacità preziosa. I migliori file AGENTS.md si concentrano sulle sei aree chiave: comandi, test, struttura del progetto, stile del codice, workflow git e limiti.
I file AGENTS.md possono rappresentare rischi per la sicurezza?
I file AGENTS.md stessi sono puro Markdown senza codice eseguibile. Tuttavia, non dovreste mai inserire segreti, chiavi API o configurazioni sensibili nel file — questi appartengono alle variabili d'ambiente. Usate invece la sezione boundaries per definire esplicitamente quali file e directory l'agente non deve toccare.
AGENTS.md vale la pena per i piccoli progetti?
Sì. Lo studio mostra miglioramenti significativi anche per piccole pull request (≤ 100 LoC). Anche un AGENTS.md minimale con comandi di setup e istruzioni per i test può migliorare misurabilmente l'efficienza dei vostri agenti. Lo sforzo per crearne uno è di 10–15 minuti — il risparmio di tempo si ripaga dopo pochi compiti agente.
Utilizzate agenti IA nel vostro workflow di sviluppo? Context Studios vi aiuta a creare file AGENTS.md e ottimizzare i vostri workflow agente. Contattateci per una consulenza gratuita.