An open convention, documented at agents.md, for a single file that coding agents read before they touch your code. There is no schema, no front matter and no required headings — it is ordinary Markdown, and the agent reads it the way a new contributor would read a README.

The reason it exists is separation. A README is written for humans: what the project does, how to get started, how to contribute. An AGENTS.md is written for an automated contributor: the exact commands, the conventions that are not obvious from the code, and the boundaries. Keeping them apart means the README stays readable and the agent instructions can be as blunt and specific as they need to be.

A growing set of tools read it, among them OpenAI Codex, Cursor, GitHub Copilot's coding agent, Google's Jules and Gemini CLI, and several others. Because it is just Markdown, a tool that does not know the convention loses nothing.

The main file lives at the repository root, next to the README, and is committed like any other file so the whole team — and CI — gets the same instructions.

Larger repositories can add more. An AGENTS.md in a subdirectory covers that subtree, and the convention is that the closest file to the code being edited wins: a file in packages/api/ takes precedence over the root one for work inside packages/api/. That makes monorepos manageable — the root file carries what is true everywhere, and each package documents only its own build, test and conventions. Nested files do not need to repeat the root; write them as deltas.

One rule ranks above all of it: an explicit instruction from the person in the chat overrides anything written in the file.

Aim for the things an agent cannot infer from reading the code, and that a new hire would have to be told.

• Setup. The exact install command, the required runtime version, any environment file to copy.
• Commands. Build, dev, test, lint, typecheck, and how to run a single test — the last one matters more than it sounds, because it decides whether the agent iterates in seconds or minutes.
• Project layout. A few lines on where things live, especially anything surprising.
• Conventions. Formatting that is not enforced by a tool, naming, error handling, which libraries to prefer over which.
• Verification. What must pass before the work is considered done.
• Boundaries. Generated files not to edit, directories not to touch, migrations not to write by hand, things never to commit.
• Pull requests. Title format, what the description should contain, whether to update a changelog.

Every line competes for attention with every other line, so the file gets worse as it gets longer. Leave out marketing copy, project history, and anything already in the README.

Leave out what the tools already enforce. If Prettier formats the code and CI runs it, you do not need a paragraph on brace style — say "run npm run format" instead. The same goes for rules a linter or the type checker will catch.

Leave out anything you will not maintain. A stale command is worse than a missing one, because the agent will try it, fail, and then improvise. And leave out secrets entirely: the file is committed, and it is read in full by a model on every session.

This is the shape a good file takes for a typical Next.js application: short, all commands, no prose that could have gone in the README. Roughly thirty lines is a reasonable target. Adapt the sections rather than copying the content, and delete anything that is not true of your repository.

They solve the same problem for different audiences. CLAUDE.md is Claude Code's own instruction file, read automatically at the start of a session. AGENTS.md is the vendor-neutral convention that a range of tools read.

If you use more than one tool, the tidy arrangement is one source of truth. Put the substance in AGENTS.md and make CLAUDE.md a one-line file that imports it with @AGENTS.md, then add anything genuinely Claude-specific underneath. That avoids the familiar failure where two instruction files drift apart and contradict each other.

Other tools have their own equivalents — Cursor's rules files, Copilot's instructions file, and so on. Most of them will also read AGENTS.md, and where they will, having one file is worth more than having a perfectly tailored one per tool.

Every command must actually work. Copy them from your terminal, do not type them from memory. Then run each one from a clean clone. A command that fails costs the agent several turns of guessing.

Keep it short. A file that fits on one screen is read properly. Somewhere past a couple of hundred lines the instructions start competing with each other, and specific rules get lost behind general ones.

Be concrete. "Write clean code" changes nothing. "Validate request bodies with Zod in lib/validation.ts" changes the output.

Update it when you change the build. Treat it like a config file, not documentation: if a PR renames a script, it should change AGENTS.md in the same commit.

Write the boundaries explicitly. Agents are cautious about what they are told to avoid and confident about everything else, so an unstated rule is an unenforced one.

Turning it into a second README. Architecture essays and project history push the commands off the screen.

Copying a template wholesale. A file listing scripts your repository does not have is actively harmful.

Contradicting the code. If the file says Jest and the repo runs Vitest, the agent will believe the file first.

Nesting too deeply. One root file plus a file per package is usually enough; a file in every folder is a maintenance burden nobody will keep up with.

Forgetting it is Markdown. It is rendered and read like any other document, so headings and lists help. If you want to check how it reads, paste it into the viewer — and the Markdown guide covers the syntax if you are writing one from scratch.