What Is AGENTS.md? The One File Every AI Coding Agent Reads
AGENTS.md is a plain Markdown file you place at the root of your repository to tell AI coding agents how your project works. Think of it as a README for agents: where README.md is written for humans, AGENTS.md carries the build steps, test commands, conventions and boundaries an agent needs to work correctly. Most major tools read it natively, and it is now stewarded by the Linux Foundation.
Why It Exists
Open a fresh repository in any AI coding agent and it faces the same problem: it does not know how your project works. It can read your code, but the conventions that live outside the code are invisible to it — that you build with one command and test with another, that a directory is generated and must never be edited. So it guesses, and the guesses are where the wrong work comes from. AGENTS.md removes the need to guess.
From a Pile of Files to One Standard
For a while, every tool solved this with its own file — one name for one agent, a different name for another. Teams running more than one agent ended up maintaining the same context in several places, and those copies drifted apart the moment someone updated one and forgot the rest. AGENTS.md is the convention the ecosystem converged on instead: one file, one predictable name, read by every major agent.
Where It Lives and How Agents Find It
Place a single AGENTS.md at the root of your repository. An agent looks for it when it begins working and loads it as always-on context — there is nothing to register or configure. In a larger project you can add more files inside subdirectories; agents read the nearest one in the directory tree, so a file deep in a package overrides the root for work in that package.
Who Reads It
AGENTS.md is read natively by a long list of agents and frameworks — Codex, Cursor, GitHub Copilot, Gemini CLI, Devin, Factory, Jules, Amp, VS Code and Windsurf among them — and it is used across more than sixty thousand open-source projects. The one notable exception is Claude Code, which reads its own file; a one-line symlink bridges that gap, which we cover separately.
Why It Is Worth Getting Right
Because the file is read on every task, its quality compounds. A precise, well-pruned AGENTS.md pays off on every session for the life of the project — every task starts from a correct understanding instead of a guess. A vague or bloated one imposes a small tax on every interaction. Few files in your repository have this much leverage, which is exactly why it is worth writing with care.