What is AGENTS.md?
AGENTS.md is an open format for giving AI coding agents the context they need to work in a codebase. It is an ordinary Markdown file, usually committed at the root of the repository. It holds the operational knowledge an agent cannot infer from the code alone: build and test commands, code style rules, review conventions, and the constraints nobody bothers to write down.
The format grew out of a shared problem. Every coding agent invented its own instruction file, so a team using more than one tool ended up maintaining the same rules three times. AGENTS.md consolidates that into a single file that many tools read. It emerged from work across OpenAI Codex, Amp, Jules, Cursor and Factory, and is now stewarded by the Agentic AI Foundation under the Linux Foundation. The format's own site lists 23 tools that read it, and counts more than 60,000 open-source repositories that ship one.
There is no schema and no required section list. Agents read the file as prose, so plain headings and short imperative sentences work better than clever structure.
In plain words
A contractor starts on Monday. You don't hand them the company brochure. You tell them how to start the app, which directory not to touch, and how the team words a commit message. AGENTS.md is that note. You write it once, keep it in the repo, and it briefs a colleague who arrives with no memory of yesterday and starts from zero every single session.
How it works
The mechanics are deliberately boring, which is the point.
- One file, plain Markdown. No schema, no frontmatter, no build step. Write the headings that suit your project.
- The nearest file wins. An agent editing a file looks for the closest AGENTS.md above it in the directory tree. Package-level rules therefore beat repo-level ones.
- Monorepos nest it. Put one file per package instead of a single sprawling file at the root. The OpenAI repository carries 88 of them.
- Your prompt still overrides everything. The file sets the defaults; an explicit instruction in chat wins over anything written in it.
- Migration is a rename. Teams moving from a tool-specific file rename it to AGENTS.md and leave a symlink behind for backward compatibility.
AGENTS.md vs CLAUDE.md
Both files answer the same question, and the difference is ownership rather than capability. CLAUDE.md is Claude Code's own convention. AGENTS.md is the cross-tool one, which is why the same content ends up duplicated in repos that use several agents side by side.
The fix is to pick one file as the source of truth and point the other at it, either with a symlink or with a one-line CLAUDE.md that imports it. Anthropic's memory documentation recommends exactly that. Two files with the same rules will drift apart, and a drifted instruction file is worse than no instruction file at all.
Why it matters
An agent starts each session with no memory of your project. Without a written brief it will guess, and it will guess plausibly rather than correctly.
- It stops the same correction repeating. "Use pnpm, not npm" belongs in a file, not in every second chat message.
- It survives a change of tool. One file serves Codex, Cursor, Copilot and the rest, so switching agents is not a migration project.
- It is reviewable. The rules live in git and go through pull requests like any other file.
- It scales down as well as up. A nested file lets one package enforce a rule that would be nonsense at the root.
What to watch out for
Most of what templates tell you to write into this file does not pay for itself.
That comes from a study that asked the question directly: Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? Gloaguen, Mündler, Müller, Raychev and Vechev (arXiv, February 2026) ran coding agents on SWE-bench tasks. The repositories were ones where developers had already committed a context file of their own. The finding was blunt: context files "[do] not generally improve task success rates, while increasing inference cost by over 20% on average", and the effect held across every model and agent they tried. Agents did reliably follow the explicit instructions they were given. What failed to earn its keep was the repository overview, the section every template puts first.
So write less of it, not none of it.
- Cut the overview, keep the commands. An agent can read your code. It cannot guess that integration tests need a running container, or that one directory is generated and must never be edited by hand.
- Every line costs tokens on every run. A 400-line file is charged to each session forever. Write the ten things that break, not the tour.
- Stale rules actively mislead. A command that stopped working in March will be followed in August. Treat the file as code and update it in the same pull request that changes the behaviour.
- Never put secrets in it. The file is committed, indexed, and read by third-party tools. Credentials belong in a secret manager.
- Nest instead of growing. When a root file starts hedging with "in the API package, however…", that rule wants its own file in the API package.
Related articles:
- Context engineering: the skill that decides how well you build with AI - Why what you put in the context window matters more than the prompt you write.
- What's an agent? - The short version: an AI that handles a task on its own once you give it the goal.
- What is spec-driven development? - The other half of the brief: telling the agent what to build, not just how to work.
- Claude Code vs Cursor vs Copilot - How the tools that read this file differ in practice.
Want to stay one step ahead?
Don't miss our best insights. No spam, just practical analyses, invitations to exclusive events, and podcast summaries delivered straight to your inbox.