You hand a coding agent a one-line ticket — "add pagination to the users endpoint" — and it writes the code, then runs npm test in a repo that builds with pnpm turbo run test, reformats three unrelated files with the wrong linter settings, and opens a pull request titled Fixed stuff. The change itself might be correct. Everything around it is wrong, because the agent had no idea how your project actually runs. So it guessed, and it guessed the way an average GitHub repo works.
That guessing is exactly what AGENTS.md is built to stop.
A README for the machine reading your code
AGENTS.md is a plain Markdown file you drop at the root of a repository. The tagline from the people who standardized it is precise: it's "a README for agents." Your README.md is written for a human deciding whether to use or contribute to the project. AGENTS.md is written for the agent that has already been told to change it — the build commands, the test runner, the lint rules, the commit conventions, the sharp edges. All the operational detail that would clutter a human-facing README, or that you'd normally explain out loud to a new teammate on their first day.
There is no schema to learn. No required fields, no YAML frontmatter, no special syntax — just Markdown headings and bullet points. An agent reads it as context before it starts work. That's the entire mechanism, and the lack of ceremony is the point: you can write a useful one in fifteen minutes.
Here's a realistic file for a TypeScript monorepo:
# AGENTS.md
## Dev environment
- Install with `pnpm install` (not npm — the lockfile is pnpm's).
- Run a single package's dev server: `pnpm --filter @acme/web dev`.
## Testing
- Full suite: `pnpm turbo run test`.
- Focus one file: `pnpm vitest run src/auth/token.test.ts`.
- Do not commit if `pnpm lint` reports errors — CI blocks on it.
## Conventions
- Prefer `Result<T, E>` returns over throwing in `packages/core`.
- Public API changes require a changeset: `pnpm changeset`.
## Pull requests
- Title format: `[<package>] <summary>`.
- Run `pnpm lint && pnpm turbo run test` before opening a PR.
Nothing there is clever. It's clear, and every command in it is real — that's what makes it work.
The mechanic that makes it scale: nearest file wins
The detail people miss is that AGENTS.md isn't one file per repo — it's one file per context. In a monorepo you place an AGENTS.md at the root and inside individual packages. When an agent edits a file, it reads the nearest AGENTS.md in the directory tree, the same way .gitignore or an ESLint config resolves. The closest file takes precedence, so a package that needs different testing rules just ships its own. OpenAI's own repository reportedly carries 88 of them.
Tools that lean into this define an explicit merge order. OpenAI's Codex, for instance, walks from the Git root down to the file being edited, concatenates the AGENTS.md files it finds, and lets closer files override earlier guidance — stopping once the combined instructions hit a size budget (32 KiB by default). It also supports an AGENTS.override.md for temporary local changes you don't want to commit.
This hierarchy is also the answer to the most common objection — "won't this file become a 2,000-line dumping ground?" It shouldn't. Treat it like documentation, not a config blob. Keep the root file short and general, push package-specific rules down into package-level files, and link out to deeper docs instead of pasting them. Give the agent what it needs here, and a pointer to the rest.
The best AGENTS.md files read like onboarding notes, not policy manuals. If a line doesn't change what the agent does, it's noise — and noise costs you context budget the agent could spend reading your code.
One more thing worth stating plainly: your direct prompt always wins. AGENTS.md sets the defaults; when you tell the agent "skip the tests this time," it does. The file removes the need to repeat yourself, not your ability to override.
Why it stopped being just a convention
None of this is new in spirit. Tool-specific instruction files came first — Claude Code reads CLAUDE.md, Cursor had .cursorrules, and everyone rolled their own. The problem was fragmentation: maintain five files saying the same thing, or accept that four of your five agents fly blind.
AGENTS.md is the de-duplication of that mess. OpenAI released it in August 2025, built with input from Google's Jules, Cursor, Factory, Amp, and others, deliberately as a single file any agent could read. Adoption followed fast — more than 60,000 open-source projects now ship one, and the tool list reads like a roll call: Codex, GitHub Copilot, Cursor, Gemini CLI, Jules, Factory, Aider, Zed, VS Code, Devin, and Claude Code by import.
Then it graduated. On December 9, 2025, the Linux Foundation launched the Agentic AI Foundation, and AGENTS.md was one of its three founding project contributions — alongside Anthropic's Model Context Protocol and Block's goose. A neutral-governance home matters here: it's the difference between a popular file one vendor happens to read and a standard the ecosystem has committed to keeping interoperable.
The takeaway
Open the repo you're already pointing agents at and add an AGENTS.md today. Fill it with the four things you'd tell a competent new hire before they touched anything: how to install, how to run the tests, how to lint, and how you want a PR to look. Copy the exact commands from your terminal history — not idealized ones — because the agent will run them verbatim. Then, the next time an agent invents npm test in a pnpm repo, you'll have a one-line fix instead of a re-review: put it in the file, once, and every agent you use reads it from then on.
Sources: AGENTS.md (official site), Custom instructions with AGENTS.md — OpenAI/Codex docs, Linux Foundation Announces the Formation of the Agentic AI Foundation, OpenAI co-founds the Agentic AI Foundation