AGENTS.md: the instructions file for coding agents

AGENTS.md is a plain Markdown file at the root of a repository that tells coding agents how to work on the project: how to build it, how to run the tests, which conventions to follow and what to avoid. Its official site calls it a README for agents, kept separate from the README written for people. On October 23, 2026, Codex, Cursor, GitHub Copilot and many other tools read it, and Claude Code reads it when the project has no CLAUDE.md of its own. This guide explains what to put in the file, how each tool finds it and how to keep it short and safe, based on the documentation of each tool read on October 23, 2026.

What AGENTS.md is for

A coding agent starts every session knowing nothing about your project. Without instructions it guesses the package manager, runs the wrong test command or reformats files against your style. AGENTS.md gives it a predictable place to look. The format has no required fields: it is ordinary Markdown with whatever headings make sense. The agents.md site says agents will try to run the testing commands you list there, so the file is not just documentation but a set of instructions the agent acts on.

The format is now stewarded by a foundation under the Linux Foundation, and the site says it is used by over 60,000 open-source projects. Supported tools listed there include Codex, Jules, Aider, goose, opencode, Zed, Warp, VS Code, Devin, Junie, Amp, Cursor, RooCode, Gemini CLI, Kilo Code, the GitHub Copilot coding agent, Windsurf and Augment Code.

What to put in it

The agents.md site suggests a project overview, build and test commands, code style guidelines, testing instructions and security considerations. Headings help in long files, but a minimal file can be four lines:

Setup: pnpm install, then pnpm dev for the dev server.
Tests: run pnpm test before every commit; all tests must pass.
Code style: TypeScript strict mode, single quotes, no semicolons.
Security: never commit .env files or print secrets in logs.

Write commands exactly as they should be typed, and prefer concrete rules ("run pnpm lint") over vague ones ("keep the code clean"). If you are new to agents in the terminal, our guide on how to use Claude Code shows the same kind of file in practice.

How each tool reads it

Table: how coding tools load AGENTS.md (official documentation, checked October 23, 2026)

Claude Code has a setting called Project instructions that decides which file wins: by default it reads CLAUDE.md or, failing that, AGENTS.md, and it can also read both, CLAUDE.md only or managed files only. If you want one source of truth for every tool, Anthropic's suggestion is to keep the rules in AGENTS.md and import it from CLAUDE.md with a line containing @AGENTS.md. Claude Code does not read AGENTS.local.md, AGENTS.override.md or a .agents/ folder. Our comparison of Claude Code and Cursor covers the other differences between the two.

Nested files in a monorepo

Large repositories can have one AGENTS.md per package. The agents.md site's rule is simple: the file closest to the code being edited takes precedence, and an explicit instruction from the user in the chat overrides everything. Codex makes the mechanics explicit: it reads one file per folder from the root down to where you started it, in the order AGENTS.override.md, then AGENTS.md, then any fallback names, and concatenates them so the closer files come last. GitHub Copilot also accepts a single CLAUDE.md or GEMINI.md at the root instead of AGENTS.md, and when personal, repository and organization instructions all exist, it uses all of them, with personal ones taking precedence.

Keep it short

Every line costs context on every request, and the tools set limits. Codex stops reading project instructions at 32 KiB by default (project_doc_max_bytes). Anthropic recommends keeping each CLAUDE.md under 200 lines, and Cursor suggests keeping rules under 500 lines. Move long reference material into separate documents, and for Claude Code use path-scoped files in .claude/rules/ so a rule only loads when the agent touches matching files. To check what Codex actually loaded, ask it to summarize its current instructions.

Security: an instructions file is code

Agents follow AGENTS.md, so treat changes to it like changes to a build script: review them in pull requests. Never put API keys, passwords or tokens in it, because the file is committed and sent to the model on every task. Be careful with files from repositories you do not trust: a malicious AGENTS.md is a ready-made prompt injection, and an agent with shell access may run the commands it lists. The same caution applies to tools connected through MCP. For a broader view of which agents to trust with your code, see our guide to the best coding assistants.