What is AGENTS.md — the file your AI agent reads before you ask

A familiar scene: you explain for the third time that this project uses pnpm, not npm. The agent suggested npm install again. You corrected it again. Tomorrow, a new session — and you start over.

One file fixes this. It's called AGENTS.md.

And here's the clever bit: the agent reads it on its own, before you ask for anything. You don't attach it to your request — it's already there. This isn't documentation somebody might open someday. It's part of every prompt you send.

AGENTS.md is a README, but for robots

A normal README.md is written for people: what the project is, how to install it, how to contribute.

AGENTS.md is the same kind of place, but for AI agents. It holds the boring technical details a human doesn't need in a README but an agent absolutely does: the build command, how to run tests, the code style, what not to touch.

The format is just Markdown. No schema, no required fields, nothing breaks if you add an extra heading. Plain lists, like any note.

Put the file in your repository root. The agent finds it from there.

Why one file and not five

A couple of years ago every tool invented its own format. Codex read AGENTS.md, Claude Code read CLAUDE.md, Gemini CLI read GEMINI.md, Cursor kept rules in its own folder.

The result was faintly ridiculous: three files in one repo with the same text in each. Or symlinks pointing at each other. Or a person giving up, keeping one — and letting the other agents work blind.

AGENTS.md won as the common denominator. It's an open format with no owner: stewarded by the Agentic AI Foundation under the Linux Foundation, read by more than twenty tools — Codex, Cursor, Copilot, Aider, Zed, Jules — and already sitting in over 60,000 open-source repositories.

Claude Code joined last: September 18, 2026, version 2.1.277. The rule is simple — if a folder has no CLAUDE.md, Claude Code reads AGENTS.md instead. Its own format still wins when present, but the shared file is no longer ignored.

What actually belongs inside

The classic beginner mistake is dumping all your documentation in there. Don't — and here's why: this file is mixed into every request and takes up room in the context window. The longer it is, the pricier the session and the more the important parts get diluted.

What works:

• Commands, literally. Not "run the tests" but pnpm test. Not "build the project" but pnpm build. A line like that gets executed, not paraphrased.
• Stack and versions. "Next.js 16, pnpm, TypeScript strict." Without it the agent guesses from habit — and guesses wrong, because the internet has far more npm examples.
• Boundaries. "Don't touch legacy/", "never push straight to main." Prohibitions pay off most: they're exactly what an agent can't learn from reading the code.
• Conventions. Commit style, comment language, where new files go.

What doesn't belong: product descriptions, team history, architecture essays. Those are for humans — those go in the README.

Keep it to a page or two. If it doesn't fit, the format nests: drop a separate AGENTS.md into a monorepo subfolder and the agent picks the one closest to the file it's working on.

How to check it's actually being read

A thirty-second test, no magic involved.

Open a fresh session and ask: "what command runs the tests here?" — without hinting at the answer. If the agent names exactly your command from the file, it read it. If it guesses npm test, the file didn't get picked up.

Then check three things: the name is exactly AGENTS.md (case matters), the file sits in the project root, and the agent was started from that same folder.

After that, just keep adding to it whenever you catch yourself explaining something twice. Corrected the agent on the same point twice? That line belongs in AGENTS.md. It's the same twenty minutes you already spend explaining — invested once instead of daily. For the wider approach, see our guide on how to give AI context about your code.

How is AGENTS.md different from a README?

The README is for people: what the project is and why it exists. AGENTS.md is for agents: how to build, how to test, what not to touch. They were deliberately split so the README doesn't turn into a dump of technical trivia.

I already have a CLAUDE.md — should I delete it?

No. Claude Code reads CLAUDE.md first and only falls back to AGENTS.md when its own file is missing. If you use several agents, keep shared rules in AGENTS.md and leave Claude-specific bits in CLAUDE.md.

Will the agent definitely obey it?

Not always. These are instructions, not settings — a model can ignore them, especially if the file is long and contradicts itself. So keep it short and concrete. Five clear rules beat three pages of wishes.