Do I need an AGENTS.md? (and how it differs from CLAUDE.md)

What it actually is

AGENTS.md is a plain markdown file you drop at the root of your project, addressed to the AI agent working in your codebase rather than the human reading a README. It holds the same kind of thing you’d tell a new teammate on their first day: the exact command to start the dev server, the command to run tests, folders the agent should never touch, conventions specific to this repo. There’s no required schema. You write it in whatever headings make sense, the same way you’d write any markdown file.

Think of it like USB-C replacing a drawer full of proprietary phone chargers. Before a shared standard, each coding agent expected its own file in its own format, so a team briefing five tools wrote the same instructions five times over. AGENTS.md is the one plug shape enough tools agreed to support: write the instructions once, and every agent that reads the format picks them up. It’s one small, concrete piece of context engineering: deciding upfront what an agent needs to know, and where.

Why your AI just did this

Your agent creates or reads an AGENTS.md when it’s one of the tools built to look for it: OpenAI’s Codex, Cursor, GitHub Copilot’s coding agent, Google’s Gemini CLI and Jules, Aider, Windsurf, and VS Code among them, per the list agents.md itself maintains as of July 2026. Cursor reads it as a plain alternative to its own Project Rules: drop an AGENTS.md at the root, or in a subdirectory, and Cursor applies it with none of the .mdc frontmatter Project Rules require.

Claude Code is the exception readers hit constantly: Anthropic’s own documentation says plainly that it reads CLAUDE.md, not AGENTS.md. That’s different from a system prompt, which the tool bakes in before you ever open a repo. AGENTS.md and CLAUDE.md are both files you write and commit, and only one of them Claude Code opens on its own. If your repo already carries an AGENTS.md for other tools, Anthropic’s docs recommend a CLAUDE.md that imports it with @AGENTS.md, so both tools follow the same instructions without you keeping two files in sync by hand.

When you’ll run into it

You inherit a repo with an AGENTS.md, open it in Claude Code, and none of it seems to apply. Nothing is broken. Claude Code genuinely doesn’t look for that filename; check for a CLAUDE.md before assuming your setup is wrong.

You clone a project scaffolded with Codex or another AGENTS.md-native tool and find the file already sitting next to package.json, with sections for build commands, testing, and style. In a monorepo you might find several, one at the root and others inside individual packages; per the standard, “the closest one takes precedence.”

Running /init in Claude Code with the CLAUDE_CODE_NEW_INIT=1 environment variable set will read an existing AGENTS.md, alongside Cursor and Windsurf rule files, and fold what it finds into the CLAUDE.md it generates. Without that variable set, /init still reads Cursor and Copilot rule files but skips AGENTS.md.

What to check

• If your repo has both a CLAUDE.md and an AGENTS.md giving different instructions, pick one as the source of truth and have the other import it. Don’t maintain the same rule twice by hand
• Write commands you can paste and run, not descriptions: npm test beats “run the tests”, since an agent that can execute a command doesn’t need to guess what the words mean
• Keep entries to facts that stay true for months: build steps, folder layout, real gotchas you’ve hit before. Skip anything an agent can discover by reading the code itself
• If you use Claude Code alongside a tool that reads AGENTS.md natively, add @AGENTS.md near the top of your CLAUDE.md instead of retyping the same rules
• In a monorepo, put shared rules at the root AGENTS.md and only override what differs in a package’s own copy; the nearest file wins, so a duplicated rule just gives the two copies room to drift apart

Say it like a dev

Instead of: “why is Claude ignoring the instructions file that’s already sitting in this repo” Say: “this repo has an AGENTS.md written for other tools. Check whether a CLAUDE.md exists, and if not, create one that imports it with @AGENTS.md”

Instead of: “write down how the project works somewhere the AI can read it” Say: “add an AGENTS.md at the root with the exact build and test commands, plus anything you’d tell a new teammate on day one”

Instead of: “make a rules file that works in every tool” Say: “put the shared instructions in AGENTS.md, then add a CLAUDE.md that imports it, so Claude Code and Cursor read the same thing”