AGENTS.md: what it is, which tools read it and a template to copy

What is AGENTS.md?

The site agents.md describes the format as a README for agents: a dedicated, predictable place to put the context and instructions that help AI coding agents work on your project. A README is written for humans, with a quick start, a project description and contribution guidelines. AGENTS.md carries the extra detail an agent needs, such as build steps, test commands and conventions, which would clutter a README or mean nothing to a human contributor.

There is no schema. The site's FAQ says there are no required fields: AGENTS.md is standard Markdown, you use whatever headings you like, and the agent reads the text you provide. The site says the format emerged from collaboration across OpenAI Codex, Amp, Jules from Google, Cursor and Factory, and that it is now stewarded by the Agentic AI Foundation under the Linux Foundation. It also says the format is used by more than 60,000 open-source projects, which is the maintainers' own figure.

The practical value is that one file replaces several. Before the format existed, each tool wanted its own filename for the same advice. If your repository has an AGENTS.md, most agents pick it up without any extra setup, and a teammate who uses a different tool gets the same instructions.

Which tools read AGENTS.md?

The agents.md homepage lists the tools it says are compatible. As of October 2026 the list includes Codex from OpenAI, Jules from Google, Factory, Aider, goose, opencode, Zed, Warp, VS Code, Devin from Cognition, UiPath's Autopilot and Coded Agents, Junie from JetBrains, Amp, Cursor, RooCode, Gemini CLI, Kilo Code, Phoenix, Semgrep, the GitHub Copilot coding agent, Ona, Windsurf from Cognition and Augment Code. The list changes, so treat the site as the source for any single tool.

Anthropic's Claude Code is not on that logo list, but its memory documentation has its own AGENTS.md section. The details differ per tool, and they are where most confusion comes from.

Sources for the rows are the Codex AGENTS.md guide, the opencode rules page, Claude Code's memory page and the agents.md FAQ. Cursor, Copilot and the others in the list each document their own handling; check their pages before relying on a nested layout.

What is the difference between AGENTS.md and CLAUDE.md?

They do the same job for different audiences. CLAUDE.md is the file Claude Code has always read. AGENTS.md is the vendor-neutral name that many tools share. The content can be identical: build commands, conventions, project layout, rules. Claude Code's own docs say to keep what Claude should hold in every session in the file, and to move multi-step procedures into skills and rules that only apply to some folders into path-scoped rules.

Claude Code's behavior, per its memory page, comes down to three cases.

One trap: adding a CLAUDE.local.md for your own private notes counts as having a CLAUDE.md, so Claude stops reading your AGENTS.md. The docs say to set Project instructions to claude-md-and-agents-md in /config if you want both. To confirm what loaded, run /memory in a session and look for the file path.

For the full guide to writing the Claude side, see how to write a CLAUDE.md. The rest of this page is about the shared file.

How do you use one file for Claude Code, Codex and Cursor?

Keep AGENTS.md as the single source and make Claude Code read it. The Claude Code docs give two ways, plus a third for migration.

@AGENTS.md

## Claude Code

Use plan mode for changes under src/billing/.

The import makes Claude read AGENTS.md first, then the Claude-specific lines below it. Keeping the import never makes Claude read the file twice, according to the docs. If you have no Claude-specific instructions, a symlink also works.

# Claude Code reads CLAUDE.md, which points to AGENTS.md
ln -s AGENTS.md CLAUDE.md

# Migrating an older AGENT.md (singular) from the agents.md FAQ
mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md

The symlink has costs, again from the docs. Claude's Edit and Write tools refuse to write through a symlink and tell Claude to edit the target instead. On Windows, creating a symlink needs Administrator privileges or Developer Mode, and Git checks a committed symlink out as a plain text file unless core.symlinks is enabled, which leaves a clone with a one-line CLAUDE.md. If anyone on the team uses Windows, use the @AGENTS.md import. Either way, run /context in your next Claude Code session to confirm CLAUDE.md appears under Memory files.

Cursor users have a related file, covered in Cursor rules. The Claude Code docs also say /init reads Cursor rules and Copilot instructions when it generates a CLAUDE.md, so migrating the other way is partly automated.

What should you put in an AGENTS.md?

The agents.md site suggests project overview, build and test commands, code style, testing instructions and security considerations, plus anything you would tell a new teammate: commit and pull request rules, deployment steps, gotchas. Add the things an agent cannot work out by reading the code. Leave out what it can.

• Exact commands. pnpm test, not run the tests. The site's FAQ says that if you list test commands, the agent will try to run relevant checks and fix failures before it finishes.
• Rules with a reason. Never edit files under migrations/ because they are applied in production. A reason lets the agent judge edge cases.
• Where things live. Two lines on the folder layout beat a tree dump.
• What not to touch. Generated files, vendored code, secrets files.
• Definition of done. Which commands must pass before a change counts.

Keep it short. Claude Code's docs say files over 200 lines consume more context and may reduce adherence, and Codex stops adding instruction files once the combined size reaches 32 KiB by default. Do not paste API keys, tokens or customer data into it; the file is committed and read by every tool that opens the repository.

# AGENTS.md

## Project overview
One or two sentences: what this project does and who uses it.

## Setup commands
- Install dependencies: `pnpm install`
- Start the dev server: `pnpm dev`
- Run all tests: `pnpm test`
- Run one test file: `pnpm vitest run path/to/file.test.ts`
- Type-check: `pnpm tsc --noEmit`
- Lint: `pnpm lint`

## Project layout
- `app/` routes and pages
- `lib/` shared logic, no UI
- `tests/` unit and end-to-end tests

## Code style
- TypeScript strict mode; no `any`.
- Prefer small functions and plain names over clever ones.
- Match the formatting of the file you are editing.

## Testing instructions
- Add or update tests for every behavior you change.
- Run `pnpm test` and `pnpm lint` before you say a task is done. Fix failures, do not skip them.

## Boundaries
- Do not edit `migrations/`; ask first.
- Do not commit `.env` files or secrets.
- Do not add a new dependency without asking.

## Commits and pull requests
- Commit message: a short imperative summary, then a blank line and the reason.
- One logical change per commit.

Replace the commands with your own and delete any section you cannot fill with something specific. An empty template section teaches the agent nothing.

How do nested AGENTS.md files and conflicts work?

For a monorepo, put another AGENTS.md inside each package. The site says agents read the nearest file in the directory tree, so the closest one takes precedence and each subproject can ship tailored instructions. When instructions conflict, the closest AGENTS.md to the edited file wins, and an explicit instruction you type in chat overrides everything. The site notes that the main OpenAI repository had 88 AGENTS.md files at the time it wrote that.

Codex adds two refinements, from its guide. A file named AGENTS.override.md in a folder replaces that folder's AGENTS.md, which is how you give one service different test commands. And Codex concatenates files from the repository root down, joined by blank lines, so deeper files appear later in the combined prompt and take priority. To see what Codex loaded, run it with a prompt asking it to list the instruction sources.

Claude Code reads subdirectory files as it works. Per its docs, a subdirectory's AGENTS.md loads when Claude opens a file there with the Read tool, and only if that subdirectory has none of the three CLAUDE.md file types of its own. It does not read AGENTS.local.md, AGENTS.override.md or anything under a .agents folder.

Can an agent write your AGENTS.md for you?

Yes, and it is usually the fastest start. The agents.md site says most coding agents can scaffold one if you ask. opencode's /init command scans the repository and creates or improves an AGENTS.md. Claude Code's /init generates a CLAUDE.md. A generated file is a draft: it knows your scripts and folders, not your rules. Edit it so every line is true and useful.

Read this repository and write an AGENTS.md at the root.

Include only things you can verify from the files: install, dev, test, lint and build commands (check package.json scripts or the Makefile), the folder layout in one line each, and the code style you can see in the existing code.

Do not invent rules. If a section would be a guess, leave it out and list the question for me at the end instead.

Keep it under 80 lines. Do not include secrets or example keys.

A good AGENTS.md also helps when you build someone else's idea. If you are looking for something to build, the developer tools category on the board has ideas with generated build prompts, and pairing a prompt with a solid AGENTS.md keeps the agent on your conventions from the first commit.