--- type: "Comparison" title: "AGENTS.md vs README.md (per agenti IA): quale deve guidare il suo agente di codice?" description: "AGENTS.md vs README.md per agenti di codice IA nel 2026. AGENTS.md è ormai lo standard adottato (60k+ repository, Codex, Cursor, Next.js 16.3) — ma README resta utile. Come usarli entrambi." resource: "https://www.contextstudios.ai/it/confronto/agents-md-vs-readme-for-ai-agents" language: "it" tags: ["AGENTS.md vs README", "AI context file", "human vs machine readme"] generated: by: "process:contextstudios-md/1" at: "2026-10-08T22:09:18.486Z" status: "stable" --- # AGENTS.md vs README.md (per agenti IA): quale deve guidare il suo agente di codice? Gli agenti di codice come Claude Code, Cursor e Codex leggono il suo repository prima di modificarlo — ma dove vanno le istruzioni? Per anni README.md è stato l'unica opzione; AGENTS.md è oggi lo standard creato apposta per guidare gli agenti. Non sono veri rivali: README è la porta d'ingresso umana, AGENTS.md è il foglio di istruzioni dell'agente. Questo confronto riguarda specificamente il compito del «contesto per l'agente». ## Confronto Dettagliato | Fattore | AGENTS.md | README.md (per agenti IA) | Vincitore | |--------|------|------|--------| | Scopo e pubblico | Creato apposta per gli agenti IA: un luogo dedicato a comandi di build/test, convenzioni e vincoli che l'agente deve seguire. | Scritto prima per le persone — onboarding, installazione e panoramica. Gli agenti possono leggerlo, ma non è pensato come loro foglio di istruzioni. | AGENTS.md | | Standardizzazione e supporto degli strumenti | Standard aperto gestito dalla Linux Foundation (Agentic AI Foundation); supportato da 28+ strumenti (Codex, Cursor, GitHub Copilot, Aider, Zed, Sourcegraph Amp) e presente in oltre 60.000 repository open source. | File universale, ma senza convenzione agent-specifica — ogni tool indovina quali parti del README siano istruzioni. | AGENTS.md | | Segnale invece di rumore per l'agente | Contiene solo regole utili all'agente, così il modello non viene distratto da badge, licenze o testi di marketing. | Mescola installazione, badge CI, note di contribuzione e marketing — diluendo le istruzioni davvero utili. | AGENTS.md | | Porta d'ingresso umana | Raramente letto dalle persone; GitHub/npm non lo mostrano come documento di atterraggio. | Il punto d'ingresso umano predefinito mostrato su GitHub, npm e la maggior parte dei registri — insostituibile per le persone. | README.md (per agenti IA) | | Monorepo e ambito annidato | Supporta file AGENTS.md annidati che gli agenti uniscono per pacchetto — ambito pulito nei repository grandi. | Esistono README per cartella, ma non sono un meccanismo di ambito convenzionale letto dagli agenti. | AGENTS.md | | Costo di manutenzione | Un file in più da tenere sincronizzato, ma evita che le regole per l'agente marciscano dentro la doc umana. | Un solo file da mantenere — più semplice, ma le regole per l'agente sepolte qui si datano senza che ci si accorga. | Pareggio | | Universalità e fallback | Standard più recente; alcune configurazioni di agenti più vecchie non lo cercano ancora. | Letto praticamente da ogni persona e strumento, ed è il fallback comune quando manca un AGENTS.md. | README.md (per agenti IA) | ## Statistiche Chiave - **AGENTS.md is reported across 60,000+ open-source repositories by mid-2026, supported by OpenAI Codex, Cursor and GitHub Copilot.** — [Tech With Ibrahim (Medium) — Top AI Agent Standards 2026](https://techwithibrahim.medium.com/top-ai-agent-standards-to-know-in-2026-c4a53f4b6bfd) (2026) - **In Vercel's own agent evals, a compressed 8KB docs index embedded in AGENTS.md hit a 100% pass rate, while modular skills maxed out at 79%.** — [Vercel — AGENTS.md outperforms skills in our agent evals](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals) (2026) - **Next.js 16.3 ships first-party AGENTS.md docs so agents like Claude Code, Cursor and Codex get framework context by default.** — [Next.js 16.3: AI Improvements](https://nextjs.org/blog/next-16-3-ai-improvements) (2026) - **AGENTS.md is a single standardized markdown file at the repository root that gives coding agents project-specific conventions — replacing fragmented per-tool config files.** — [AGENTS.md Guide 2026 (vibecoding.app)](https://vibecoding.app/blog/agents-md-guide) (2026) - **By 2026 AGENTS.md has become the default way engineering teams give AI coding agents the context they need — including monorepo and nested-package patterns.** — [BuildBetter — AGENTS.md Complete Guide for Engineering Teams 2026](https://blog.buildbetter.ai/agents-md-complete-guide-for-engineering-teams-in-2026) (2026) - **Studio controllato su 10 repository e 124 pull request GitHub: la presenza di un file AGENTS.md è associata a ~28,6% di riduzione del tempo di esecuzione mediano e ~16,6% di riduzione del consumo di token di output, con completamento del task comparabile.** — [arXiv 2601.20404 — Mohsenimofidi et al. (Gen 2026, v2 Mar 2026)](https://arxiv.org/abs/2601.20404) (2026) ## Scelga AGENTS.md quando... - Vuole che gli agenti IA seguano convenzioni precise di build, test e stile - Lavora in un monorepo e servono regole per l'agente annidate per pacchetto - Il suo team usa Codex, Cursor, Copilot o Claude Code ogni giorno - Vuole separare le istruzioni per l'agente dal marketing/doc rivolto agli umani ## Scelga README.md (per agenti IA) quando... - Il progetto è minuscolo e basta un singolo file leggibile - Le serve il file universale che ogni persona e strumento legge su GitHub/npm - I suoi agenti/strumenti precedono AGENTS.md e cercano solo il README - Documenta prima per le persone e poi per gli agenti ## La Nostra Raccomandazione Per dire a un agente di codice IA come lavorare nel suo repository, AGENTS.md è lo standard chiaro del 2026 — adottato in oltre 60.000 repository, supportato da Codex, Cursor e Copilot e incluso nativamente in Next.js 16.3. README.md resta dedicato all'onboarding umano ed è il fallback universale che molti agenti leggono quando manca un AGENTS.md. Buona pratica: li tenga entrambi. Metta doc umana, installazione e badge nel README; comandi di build/test, convenzioni, percorsi da non toccare e regole per l'agente nell'AGENTS.md. Non comprima le istruzioni per l'agente nel README, dove diluiscono la doc umana e vengono ignorate. ## Domande Frequenti **Q: AGENTS.md sostituisce README.md?** A: No. Servono pubblici diversi. README.md resta la porta d'ingresso umana per onboarding e installazione; AGENTS.md è il file di istruzioni leggibile dalla macchina per gli agenti di codice. Li tenga entrambi. **Q: AGENTS.md è davvero uno standard ora?** A: Sì — a metà 2026 è presente in oltre 60.000 repository ed è supportato da OpenAI Codex, Cursor e GitHub Copilot, con Next.js 16.3 che include doc AGENTS.md nativa. **Q: Cosa va in AGENTS.md vs README.md?** A: AGENTS.md: comandi di build/test, convenzioni di codice, percorsi da non toccare, regole di PR e revisione. README.md: panoramica, installazione, uso, badge e note di contribuzione umane. **Q: Un agente funziona anche solo con un README?** A: Spesso sì — molti agenti ripiegano sul README quando manca un AGENTS.md. Ma ottiene risultati migliori e più coerenti dando agli agenti un AGENTS.md dedicato con istruzioni pulite e solo per loro.