AGENTS.md, Explained: The README Your Coding Agent Actually Reads

Your AI coding agent has never read your README. It reads a different file, and if you have not written that file, it is working off guesses about your project every single time you prompt it.

That file is AGENTS.md, and in the last year it has quietly become the closest thing the industry has to a standard. Over 60,000 open-source projects now ship one, and every major agent, Cursor, Claude Code, GitHub Copilot, Codex, Windsurf, Aider, has agreed to look for it. If you have been building with an agent and wondering why it keeps using the wrong test command, importing the wrong way, or "fixing" things you told it never to touch, the answer is usually that nobody wrote down the rules where the agent would see them. The hypothesis for this post is simple: AGENTS.md is where your project's how lives, the durable instructions an agent needs to work in your repo, and it is essential precisely because it stops the agent from reinventing your conventions on every run. But it has a hard ceiling, and knowing where that ceiling is matters as much as knowing what the file does.

#What AGENTS.md actually is

Start with the plain version, because the docs bury it under "agent-native repos" and "deterministic parsing."

A README.md is written for a human. It has a quick-start, a description of what the project does, maybe a contributing guide. It assumes a person is reading it, skimming, filling in gaps with judgment. An AGENTS.md is written for a machine. It sits at the root of your project, and when a coding agent starts working in your repo, it reads that file first to learn the things it cannot infer: how to build the project, how to run the tests, what conventions to follow, and what it must not do.

The official spec puts it in one line:

Think of it as a README for agents.

That is the whole idea. It is standard Markdown, no special syntax, no framework. You write down the stuff a new engineer would need on their first day, except the "new engineer" is an agent that starts fresh every session and has no memory of the last one. Exact build and test commands. The linter rules you actually enforce. Which directories hold what. The "never do this" and "always ask first" boundaries that keep it from making a confident, destructive mistake.

Here is the analogy that makes it stick. AGENTS.md is the onboarding doc you would hand a contractor who is genuinely skilled but has never seen your codebase and will forget everything the moment they walk out the door. You would not explain what a database is. You would tell them "we use pnpm, not npm," "run pnpm test before you commit," "the auth logic lives in src/auth and you do not touch it without asking." That is exactly what belongs in AGENTS.md. Skilled worker, zero context about your specific project. The file supplies the context.

#Why it caught on so fast

The reason AGENTS.md spread is not that it is clever. It is that the alternative was chaos.

Before the standard, every tool wanted its own instruction file. Cursor read .cursorrules. Claude Code read CLAUDE.md. Copilot read .github/copilot-instructions.md. If you used more than one agent, or switched between them, you were maintaining three or four files that all said roughly the same thing and drifted apart the moment you updated one and forgot the others. AGENTS.md collapsed that into one file that every agent agreed to read. Write your instructions once, and they travel across tools.

And the payoff is measurable, not vibes. GitHub studied the pattern across more than 2,500 repositories and found the same thing the whole community keeps rediscovering: an agent's success is tied directly to the quality of the instructions it is given. A vague or missing AGENTS.md means the agent guesses at your build command, your import style, your file layout, and gets a meaningful fraction of those guesses wrong. A good one means it gets them right on the first try, which is the difference between a clean pull request and three rounds of "no, we use the other pattern."

Consider the concrete before and after. Without an AGENTS.md, you ask the agent to add a feature and it runs npm install, writes tests in a style you abandoned six months ago, and puts a new component in the wrong folder. You spend twenty minutes correcting things that have nothing to do with the actual feature. With a good AGENTS.md, the agent reads "use pnpm, tests go in __tests__ next to the file, components live in src/components and use the existing Button primitive," and the first draft already matches your conventions. Same agent. Same model. The only variable is whether the rules were written down where it looks.

#What belongs in it, and what does not

This is where most of the pain lives, and where the file gets misused.

AGENTS.md is for the durable, project-wide how. The things that are true across every feature you will ever build in this repo. Build and test commands. Coding conventions and the linter rules you enforce. The tech stack and versions. Directory structure and where things live. Hard boundaries: files not to touch, patterns to never use, "ask before you run a migration." The rule of thumb: if it would be true no matter what feature you are working on today, it belongs in AGENTS.md.

What does not belong in it is the what of any specific piece of work. The requirements for the feature you are building right now. What "done" means for this particular task. The acceptance criteria for the checkout flow you are adding this afternoon. Those are not ambient facts about your project; they are the definition of one job, and they change with every job. Stuffing them into AGENTS.md is how the file rots.

And it does rot, which is the failure mode worth naming honestly. The whole design of AGENTS.md is that it loads into the agent's context at the start of a session, once, always on. That is its strength and its trap. Because it is always loaded, every line you add is a line the agent carries through every single task, whether or not it is relevant. The sharpest version of the critique came from a builder on LinkedIn who called AGENTS.md "the new 'just add more comments'", a lazy solution everyone adopted because no one questioned it, one flat file that grows until it is noise. There is even research suggesting that verbose, poorly structured AGENTS.md files can reduce an agent's success rate, because you are spending the context window on instructions the agent does not need for the task at hand and diluting the ones it does.

So the trade-off is real: the file is only useful while it stays lean. Lead with the commands. Keep the boundaries tight. Resist the urge to paste your entire style guide into it. And whenever you catch the agent making the same mistake twice, that is the signal to add one line to AGENTS.md, a mistake turned into a rule, which is the highest-value thing the file can hold.

#The reframe: AGENTS.md carries how you build, a spec defines what done means

Here is the distinction that untangles most of the confusion, and it is the same line that runs through everything we write about building with agents.

There are two completely different kinds of knowledge an agent needs, and people keep trying to cram both into one file. The first is how you build here, your conventions, commands, and constraints. That is ambient. It is true all the time, it belongs in context always, and AGENTS.md is exactly the right home for it. The second is what this specific thing should do and how you will know it is done. That is not ambient. It is the definition of a single unit of work, and it belongs with that work, not in a file every task drags along.

When you blur those two, both jobs get done badly. Your AGENTS.md swells with feature-specific detail that becomes stale the moment the feature ships, and your actual requirements live nowhere durable, so the agent builds against a vague prompt and you find out it built the wrong thing at review time. Keep them separate and both get sharp. AGENTS.md stays a lean, stable description of your project's rules. The requirement for each feature carries its own acceptance criteria, the specific, checkable statements of what this build has to do.

This is exactly the gap BrainGrid is built to close. AGENTS.md tells the agent how to work in your repo, and it should. But it was never designed to tell the agent what to build or to verify that the build is correct, and it cannot, because it is a static file with no notion of "done." In BrainGrid, you describe the feature and the Planning Agent turns it into a requirement with explicit acceptance criteria, the what and the definition of done, which the Builder Agent then builds against, whether that build runs in the BrainGrid Cloud sandbox or in your own GitHub repo through Claude Code, Cursor, or Codex over MCP. AGENTS.md sets the ground rules. The requirement sets the target. The two are complements, not competitors, and trying to make one file do both jobs is why so many AGENTS.md files end up bloated and so many builds end up subtly wrong.

#What this means if you are building right now

If you are shipping features with an agent and you do not have an AGENTS.md, write one today, and keep it short. Put your exact build and test commands at the top. Name your stack and versions. State the two or three conventions you actually care about and the two or three boundaries the agent must never cross. That alone will kill a whole category of "why did it do it that way" friction, because the agent will finally be working from your rules instead of its priors.

But do not ask that file to do the job it cannot. The moment you find yourself pasting the requirements for a specific feature into AGENTS.md, stop. That is a sign the what of your work has nowhere durable to live, and the fix is not a longer instruction file. It is a real requirement with acceptance criteria for that feature, kept with the feature and checked against the build. AGENTS.md is how your agent learns your project. It is not how your agent learns what you actually want it to ship this afternoon. Get the ambient rules into AGENTS.md, keep the per-feature definition of done somewhere the build gets verified against it, and you have covered both kinds of knowledge instead of half of each.

If you want to go deeper on the ambient side, we wrote about context engineering and why agents get less reliable the longer they run. For the target side, here is how to write acceptance criteria an AI agent can actually verify.

#FAQ

#What is an AGENTS.md file?

AGENTS.md is a standard Markdown file placed at the root of a project that gives AI coding agents the project-specific context they cannot infer on their own: how to build and test the project, what coding conventions to follow, where files live, and what the agent must not do. It works like a README written for machines instead of humans. Over 60,000 open-source projects use it, and major agents including Cursor, Claude Code, GitHub Copilot, Codex, and Windsurf all read it, so you can write your instructions once and have them apply across every tool.

#Do I need an AGENTS.md file?

If you build with an AI coding agent regularly, yes, it is one of the highest-value things you can add. Without it, the agent guesses at your build command, your import style, your file layout, and your conventions on every session, and it gets a meaningful fraction of those guesses wrong. A short, well-structured AGENTS.md means the agent's first draft already matches how your project works, which removes a whole category of correction cycles. For a one-off script or a repo you never touch with an agent, it is not necessary.

#Does AGENTS.md actually help?

It helps when it is lean and specific, and it can hurt when it is bloated. GitHub's study of over 2,500 repositories found that agent success is directly tied to the quality of the instructions, so a focused file with exact commands and clear boundaries measurably improves results. But because AGENTS.md is always loaded into the agent's context, a long, poorly structured file spends the context window on irrelevant instructions and can actually reduce success rates. The fix is to keep it short, lead with commands, and only add rules that apply across every task.

#Is AGENTS.md always loaded?

Yes, that is the core of how it works and also its main limitation. Instruction files like AGENTS.md are loaded once at the start of a session and stay in the agent's context for that session, so every rule in the file is carried through every task whether or not it is relevant. This is why the file is ideal for ambient, project-wide facts (your build command, your conventions) and a poor fit for feature-specific requirements, which change with every task and are better kept with the individual piece of work.

#What is the difference between AGENTS.md and a spec or acceptance criteria?

AGENTS.md carries the how: the durable, project-wide rules for working in your repo, true no matter what feature you build. A spec with acceptance criteria carries the what: the specific definition of one feature and how you will know it is done, which changes with every task. AGENTS.md is a static file with no concept of "done," so it can tell the agent how to work but cannot verify that a build is correct. The two are complements. You keep the ambient rules in AGENTS.md and the per-feature definition of done in a requirement the build is checked against.

BrainGrid is the AI Product Planner that turns your idea into a requirement with acceptance criteria, the definition of done your agent builds against, so AGENTS.md can stay lean and your builds still land correct. Try it at braingrid.ai.