Every coding agent starts a session knowing nothing about your project. It doesn't know your test command, your folder layout or the one directory it must never touch. You can repeat all of that in every chat, or you can write it down once in an AGENTS.md file.
AGENTS.md is a plain Markdown file at the root of your repository that tells AI coding agents how to work on your project. The official site calls it "a README for agents" and says it is used by over 60,000 open-source projects. This guide covers what AGENTS.md is, which tools read it, how to write one that agents actually follow, and how it relates to CLAUDE.md and Cursor rules.
What is AGENTS.md?
AGENTS.md is an open format, not a product feature. There are no required fields: it is standard Markdown, and you can use any headings you like (agents.md). The format grew out of work across the coding-agent ecosystem, including OpenAI Codex, Amp, Google's Jules, Cursor and Factory, and it is now stewarded by the Agentic AI Foundation under the Linux Foundation.
The idea is simple. Your README is written for humans. AGENTS.md holds the extra detail an agent needs to do useful work without asking: the exact commands, the conventions, and the rules that are easy to break.
Which tools read AGENTS.md
Support is broad, but each tool loads the file a little differently. These details come from each vendor's own docs:
| Tool | How it uses AGENTS.md |
|---|---|
| Codex | Reads AGENTS.md before doing any work. It also reads a global ~/.codex/AGENTS.md, and an AGENTS.override.md takes priority over AGENTS.md in the same folder (Codex docs). |
| Cursor | Treats AGENTS.md as a simple alternative to .cursor/rules. Nested AGENTS.md files in subfolders are combined with their parents, and the more specific one takes precedence (Cursor rules docs). |
| Claude Code | Reads AGENTS.md as project instructions when the project has no CLAUDE.md. If you also keep a CLAUDE.md, import AGENTS.md from it (Claude Code memory docs). |
| Others | The agents.md site lists many more agents that read the format, including GitHub Copilot's coding agent, Gemini CLI, Jules and Windsurf. |
How to write an AGENTS.md file
Start small and specific. The agents.md site suggests covering a project overview, build and test commands, code style, testing instructions, security considerations and pull request guidelines. Here is a starting point for a Next.js and Supabase app:
# AGENTS.md
## Project
Client portal built with Next.js (App Router) and Supabase.
Users sign in and manage their own records.
## Commands
- Install: `npm install`
- Dev server: `npm run dev`
- Build: `npm run build`
- Tests: `npm test`
- Lint: `npm run lint`
## Code style
- TypeScript strict mode. No `any` without a comment explaining why.
- Server code reads data with the server client in `lib/supabase/server.ts`.
## Security rules
- Never commit secrets. Only the Supabase publishable key may use a
`NEXT_PUBLIC_` prefix.
- Every new table gets Row Level Security and one policy per operation.
- Do not edit files in `supabase/migrations/` that are already applied.
Add a new migration instead.
## Definition of done
- Build, tests and lint pass, and you paste the output.
- New behavior has a test.
## Pull requests
- One feature or fix per branch.
- PR description lists every changed file and why.
A few habits make the difference between a file agents follow and one they skim:
- Be concrete enough to check. Claude Code's docs give the pattern: "Run
npm testbefore committing" works better than "Test your changes" (Claude Code memory docs). - List the real commands. Agents will run test commands they find in AGENTS.md and try to fix failures before finishing, according to the agents.md FAQ. Make sure the commands exist in
package.json. - Keep it short. Claude Code recommends under 200 lines per instruction file, because longer files use more context and reduce adherence. Codex stops adding instruction files once their combined size reaches 32 KiB by default (Codex docs).
- Write rules, not essays. Bullets under clear headings are easier to follow than paragraphs.
- Treat it as living documentation. When an agent makes the same mistake twice, add a line.
You don't have to start from a blank page. Codex's /init command creates an AGENTS.md for the project (Codex CLI), and our AGENTS.md starter template is a fuller version of the example above.
Nested AGENTS.md files for monorepos
In a repo with several packages, put one AGENTS.md at the root and another inside each package. According to agents.md, "the closest one takes precedence", so each subproject can ship its own commands and rules. If instructions conflict, the closest AGENTS.md to the edited file wins, and explicit instructions in your chat override everything.
Codex documents its exact order: it walks from the project root down to your working directory, includes at most one file per folder, and joins them so files closer to your current directory appear later and override earlier guidance (Codex docs).
AGENTS.md vs CLAUDE.md vs Cursor rules
These files overlap, so it helps to know when each one loads:
- AGENTS.md is the shared, tool-neutral file. Put anything every agent should know here.
- CLAUDE.md is Claude Code's own instruction file. By default, Claude Code reads AGENTS.md only when there is no CLAUDE.md or CLAUDE.local.md in your working directory or above it. If you need both, add a line with
@AGENTS.mdat the top of CLAUDE.md so Claude Code imports the shared file, then add Claude-specific notes below it (Claude Code memory docs). - Cursor project rules live in
.cursor/rules/as.mdcfiles withdescription,globsandalwaysApplyfront matter. A plain.mdfile in that folder is ignored. Use rules when an instruction should only load for certain files, and keep each rule under 500 lines (Cursor rules docs). If you only need one set of rules, AGENTS.md is enough: our universal AGENTS.md starter includes bridge files for Claude Code and Gemini CLI.
The simplest setup for most teams is one AGENTS.md as the source of truth, plus a one-line CLAUDE.md that imports it if anyone uses Claude Code alongside other tools.
What not to put in AGENTS.md
- Secrets. AGENTS.md is committed to Git and read by every agent. Name environment variables, never their values.
- Long procedures that only matter sometimes. A ten-step release process belongs in an agent skill, which loads only when the task calls for it.
- Things a hook should enforce. Instruction files are context, not enforcement. Claude Code's docs say that to block an action regardless of what the agent decides, you should use a hook or a permission rule instead (Claude Code memory docs). Our guide to running coding agents safely covers those controls.
Keep reading
- Cursor vs Claude Code vs Codex: how to pick an AI coding agent
- 10 copy-paste AI coding prompts to ship a web app
- AGENTS.md starter template for Next.js and Supabase
FAQ
What is AGENTS.md?
AGENTS.md is a plain Markdown file in your repository that gives AI coding agents the context and instructions they need, such as build commands, code style and security rules. It has no required fields.
Does Claude Code read AGENTS.md?
Yes. Claude Code reads AGENTS.md as project instructions when there is no CLAUDE.md or CLAUDE.local.md in the working directory or above it. Otherwise, import it from CLAUDE.md with a line containing @AGENTS.md.
Where should AGENTS.md go?
Put AGENTS.md at the root of your repository. In a monorepo, add another one inside each package; agents use the closest file to the code they are editing.
What is the difference between AGENTS.md and Cursor rules?
AGENTS.md is a tool-neutral Markdown file every agent can read. Cursor project rules are .mdc files in .cursor/rules with description, globs and alwaysApply front matter, which control when each rule loads in Cursor.