--- type: "Comparison" title: "AGENTS.md vs README.md (for AI Agents): Which Should Guide Your Coding Agent?" description: "AGENTS.md vs README.md for AI coding agents in 2026: 60k+ repos, 28+ tools, ~29% faster agents (arXiv study). Which file carries what, and why you need both." resource: "https://www.contextstudios.ai/comparisons/agents-md-vs-readme-for-ai-agents" language: "en" tags: ["AGENTS.md vs README", "AI context file", "human vs machine readme"] generated: by: "process:contextstudios-md/1" at: "2026-10-08T20:58:08.873Z" status: "stable" --- # AGENTS.md vs README.md (for AI Agents): Which Should Guide Your Coding Agent? Coding agents like Claude Code, Cursor and Codex read your repo before they touch it — but where should the instructions live? README.md was the only option for years; AGENTS.md is now the purpose-built standard for agent guidance. They are not really rivals: README is the human front door, AGENTS.md is the agent's instruction sheet. This compares them for the agent-context job specifically. ## Detailed Comparison | Factor | AGENTS.md | README.md (for AI Agents) | Winner | |--------|------|------|--------| | Purpose & audience | Purpose-built for AI agents: a dedicated place for build/test commands, conventions and guardrails the agent must follow. | Written for humans first — onboarding, install and project overview. Agents can read it but it isn't designed as their instruction sheet. | AGENTS.md | | Standardization & tool support | Open standard stewarded by the Linux Foundation's Agentic AI Foundation; adopted by 28+ tools (Codex, Cursor, GitHub Copilot, Aider, Zed, Sourcegraph Amp) and present in 60,000+ open-source repos. | Universal file, but no agent-specific convention — every tool guesses which parts of the README are instructions. | AGENTS.md | | Signal vs noise for the agent | Contains only agent-relevant rules, so the model isn't distracted by badges, licenses or marketing copy. | Mixes install steps, CI badges, contribution notes and marketing — diluting the actual instructions an agent needs. | AGENTS.md | | Human front door | Rarely read by people; GitHub/npm don't render it as the landing document. | The default human entry point rendered on GitHub, npm and most registries — irreplaceable for people. | README.md (for AI Agents) | | Monorepo & nested scoping | Supports nested AGENTS.md files that agents merge per package — clean scoping in large repos. | Per-folder READMEs exist but aren't a conventional, agent-read scoping mechanism. | AGENTS.md | | Maintenance overhead | An extra file to keep in sync, though it keeps agent rules from rotting inside human docs. | One file to maintain — simpler, but agent rules buried here drift out of date quietly. | Tie | | Universality & fallback | Newer standard; a few older agent setups still don't look for it. | Read by essentially every human and tool, and the common fallback when no AGENTS.md is present. | README.md (for AI Agents) | ## Key Statistics - **Controlled study of 10 repositories and 124 GitHub pull requests: the presence of an AGENTS.md file was associated with ~28.6% lower median agent runtime and ~16.6% reduced output token consumption, with comparable task completion.** — [arXiv 2601.20404 — Mohsenimofidi et al. (Jan 2026, v2 Mar 2026)](https://arxiv.org/abs/2601.20404) (2026) - **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) - **By 2026, AGENTS.md is supported by 28+ tools including OpenAI Codex, Cursor, Sourcegraph Amp, Aider, Zed and Google Jules; .cursorrules is now legacy, replaced by the .cursor/rules/.mdc format.** — [BuildBetter — AGENTS.md vs .cursorrules vs Claude Skills (2026)](https://blog.buildbetter.ai/agents-md-vs-cursorrules-vs-claude-skills-2026-comparison) (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) ## Choose AGENTS.md when... - You want AI agents to follow specific build, test and style conventions - You work in a monorepo and need nested, per-package agent rules - Your team uses Codex, Cursor, Copilot or Claude Code daily - You want agent instructions separated from human-facing marketing/docs ## Choose README.md (for AI Agents) when... - The project is tiny and a single human-readable file is enough - You need the universal file every human and tool reads on GitHub/npm - Your agents/tooling predate AGENTS.md and only look for README - You are documenting for people first, agents second ## Our Recommendation For telling an AI coding agent how to work in your repo, AGENTS.md is the clear 2026 standard — now stewarded by the Linux Foundation's Agentic AI Foundation, present in 60,000+ open-source repositories, and supported by 28+ tools including Codex, Cursor, GitHub Copilot, Aider, Zed and Sourcegraph Amp (shipped first-party in Next.js 16.3). The research backs the practice: a 2026 arXiv study of 10 repositories and 124 real GitHub pull requests found that a well-structured AGENTS.md cut median agent runtime by ~29% and output token consumption by ~17% while keeping task completion comparable. README.md still owns human onboarding and remains the universal fallback that agents read when no AGENTS.md exists. Best practice: keep both. Put human docs, install steps and badges in README; put build/test commands, conventions, do-not-touch paths and agent rules in AGENTS.md. Don't cram agent instructions into the README, where they dilute human docs and get ignored — and keep AGENTS.md short (the spec emphasizes 100–300 words of high-signal instructions over long prose). ## Frequently Asked Questions **Q: Does AGENTS.md replace README.md?** A: No. They serve different audiences. README.md remains the human front door for onboarding and install; AGENTS.md is the machine-readable instruction file for coding agents. Keep both. **Q: Is AGENTS.md actually a standard now?** A: Yes — by mid-2026 it's reported across 60,000+ repositories and supported by OpenAI Codex, Cursor and GitHub Copilot, with Next.js 16.3 shipping first-party AGENTS.md docs. **Q: What goes in AGENTS.md vs README.md?** A: AGENTS.md: build/test commands, code conventions, do-not-touch paths, PR and review rules. README.md: project overview, install steps, usage, badges and human contribution notes. **Q: Will an agent still work if I only have a README?** A: Usually yes — many agents fall back to README when no AGENTS.md exists. But you get better, more consistent results by giving agents a dedicated AGENTS.md with clean, agent-only instructions.