AGENTS.md vs CLAUDE.md: what it is, who reads it, and how to use both
AGENTS.md explained: what it is, which coding agents read it, how it differs from CLAUDE.md, how to keep one file, a copyable template, and why it isn't memory.
In short
- AGENTS.md is an open, plain-Markdown "README for agents" that many coding tools read. It has no required fields, and the Agentic AI Foundation now stewards it.
- Claude Code reads AGENTS.md natively since v2.1.277, but by default only when no CLAUDE.md or CLAUDE.local.md exists in your working directory or above.
- To keep one source of truth, put the shared rules in AGENTS.md and make CLAUDE.md a short file that starts with @AGENTS.md. A symlink works but has more traps.
- An instructions file is static and hand-written. It is not memory, which is learned over time and can follow you across tools and projects.
AGENTS.md is a plain Markdown file, usually at the root of a repository, that tells coding agents how your project works: how to build it, how to test it, what style to follow. Think of it as a README written for a tool instead of a person. Our opinion, after checking each tool's own docs: write the shared rules once in AGENTS.md, keep Claude-only notes in a thin CLAUDE.md, and never confuse either file with memory.
This post covers what the format is, who reads it, what Claude Code actually does with it as of November 2026, a template you can copy, and where an instructions file stops being the right tool.
What AGENTS.md is, and who maintains it§
AGENTS.md is an open format with no required fields. It is plain Markdown, and the site calls it a "README for agents." OpenAI released it in August 2025. On December 9, 2025, the Linux Foundation announced the Agentic AI Foundation, with AGENTS.md as one of three founding contributions, and the format is now stewarded there.
The announcement says more than 60,000 open source projects and agent frameworks have adopted it. That is a figure reported by the people who released it, so treat it as a sense of scale, not a measurement.
The reason it exists is mundane. Before it, each tool wanted its own file with its own name, and a team using two agents kept two copies of the same advice, which drifted apart. One agreed name is a small thing that removes a real chore.
Which tools read AGENTS.md§
The agents.md site lists dozens of tools, and the list changes. These are the ones whose own documentation we could check:
| Tool | Reads AGENTS.md | How it behaves |
|---|---|---|
| Claude Code | Yes, since v2.1.277 | Only if no CLAUDE.md or CLAUDE.local.md exists in your working directory or above. Otherwise import it. |
| Codex | Yes | Reads from the project root down to your directory, concatenated, with a 32 KiB default cap. Supports an AGENTS.override.md. |
| Cursor | Yes | Root and nested files, with more specific instructions taking precedence. |
| GitHub Copilot | Yes | Files anywhere in the repo, and the nearest one takes precedence. |
| Gemini CLI | With one setting | Its default is GEMINI.md. Add AGENTS.md to context.fileName in settings.json. |
Sources, all read in November 2026: the docs for Claude Code, Codex, Cursor, GitHub Copilot and Gemini CLI.
Jules, Zed, Warp, Aider, goose, Windsurf and others appear on the agents.md list. We did not confirm how each of them behaves, so we are not describing them. Check a tool's own docs before you rely on it. Copilot's page also does not say which of its surfaces read the file.
Does Claude Code read AGENTS.md?§
Yes. Many older guides still say it does not, and they are out of date. Since v2.1.277, the Claude Code docs say a repository already set up for other coding agents works without adding a CLAUDE.md, an import or a setting.
There is one rule to learn, and it is the one most guides miss. By default, Claude Code decides what to read by what exists:
| What your repo has | What Claude Code reads |
|---|---|
| AGENTS.md only | AGENTS.md |
| AGENTS.md and any CLAUDE.md or CLAUDE.local.md in the working directory or above | CLAUDE.md files only |
| CLAUDE.md that imports AGENTS.md | CLAUDE.md, with AGENTS.md included |
"Any CLAUDE.md" includes .claude/CLAUDE.md and CLAUDE.local.md, in your working directory or any parent. Your personal ~/.claude/CLAUDE.md, managed policy files and .claude/rules/ do not count, and still load alongside.
You can change the rule in /config under Project instructions. The default is claude-md-or-agents-md. claude-md-and-agents-md loads both, with CLAUDE.md first in each directory, and claude-md ignores AGENTS.md. That setting is per developer, though. It does not travel with the repository, so an import is the better fix for a team.
Keep one source of truth§
You want the rules in one place, so they cannot disagree. There are two ways to do it, and the docs recommend the first.
AGENTS.md → CLAUDE.md → Claude Code
Option one: an import. Make CLAUDE.md a few lines long. The first line imports AGENTS.md, and the rest holds anything only Claude Code needs:
@AGENTS.md
## Claude Code
Use plan mode for changes under `src/billing/`.
Other tools keep reading AGENTS.md and ignore the rest. Claude Code gets both, in order. Imports travel with the repository, so every teammate gets the same result. Imports can go four hops deep.
Option two: a symlink. ln -s AGENTS.md CLAUDE.md also works. The costs are real, though. Claude's Edit and Write tools refuse to write through a symlink, so you have to edit the target. On Windows, symlinks need Administrator rights or Developer Mode, and Git may check them out as a one-line text file.
- If you have an old CLAUDE.md, rename it to AGENTS.md. Keep the shared parts and move Claude-only parts aside.
- Create a new CLAUDE.md whose first line is
@AGENTS.md, followed by a## Claude Codesection for the Claude-only notes. - Start Claude Code in the repository and run
/context all. CLAUDE.md should appear under Memory files. - In a monorepo, check a subfolder too. A subfolder's AGENTS.md loads on demand when Claude opens a file there, if that subfolder has no CLAUDE.md of its own.
Run that check once and it saves a lot of guessing later. If a rule seems ignored, the first thing to rule out is that the file never loaded. Our post on why Claude seems to forget covers the other usual causes.
What actually differs between the two files§
For the shared rules, nothing. Both are static Markdown that you write and review. The differences are in what Claude Code adds around CLAUDE.md.
- Scopes. CLAUDE.md can live in managed policy, user, project and local scopes. AGENTS.md is a project file.
- Rules by path.
.claude/rules/can scope instructions to certain paths so they load only when relevant. - Imports.
@pathimports work in both files. - Hooks.
InstructionsLoadedhooks do not fire for an AGENTS.md read through the setting. They do fire when a CLAUDE.md imports or symlinks it.
One caution applies to both. Anthropic describes these files as context, not enforced configuration. If something must never happen, use a hook or a permission rule, not a sentence in a Markdown file. For a fuller look at what fills the session, see what fills Claude Code's context. If you want a hook that loads notes at the start of each session, see Claude Code hooks for memory.
Nested files and precedence, tool by tool§
In a monorepo you may want different advice for packages/api and packages/web. Tools handle this differently, and the difference matters when two files disagree.
- The agents.md convention: agents read the nearest file in the directory tree. The closest AGENTS.md to the edited file wins, and an explicit chat prompt overrides everything.
- Cursor and GitHub Copilot: both describe the nearest or more specific file as taking precedence.
- Codex: it builds a chain from the project root down to your directory and concatenates it, root first. Closer files come later, and a 32 KiB combined cap stops further files from being added.
- Claude Code: it concatenates CLAUDE.md files from the working directory and every parent, root first. Closer files are read last, but they do not override. A subdirectory file loads on demand.
If you rely on precedence, test it in each tool you use. If you can, avoid contradictions instead: put only the differences in the nested file.
What to put in AGENTS.md, and what to leave out§
The agents.md site suggests a handful of sections: a project overview, build and test commands, code style, testing instructions and security considerations. To these we would add commit and PR rules, and a short list of gotchas.
Put in
- Exact commands, copy-pasteable, including the flags you actually use.
- Conventions a linter cannot catch: naming, error handling, where new files go.
- Boundaries: what to ask about before changing it (migrations, generated files, public APIs).
- Anything a new teammate would need on day one.
Leave out
- Secrets, tokens and internal URLs. The file is committed.
- Facts that change often, such as the current sprint or yesterday's decision.
- Anything obvious from reading the code.
- Long background essays. Link to your docs instead.
- Rules you need enforced. Use hooks and CI for those.
Keep it short. Anthropic suggests under 200 lines per CLAUDE.md file, because longer files use more context and are followed less reliably. Codex stops adding files at 32 KiB combined by default. A file that fits on one screen gets followed. This is the unglamorous part of context engineering: each line you add competes with the task for room in the context window. Our context engineering checklist covers the other parts of a context.
An AGENTS.md template you can copy§
Replace the placeholders with your project's real commands. Delete any section you cannot fill with something specific.
# AGENTS.md
## Project overview
<One or two sentences: what this repo does and who uses it.>
Layout: `<dir>/` holds <what>, `<dir>/` holds <what>.
## Setup and build
- Install: `<command>`
- Build: `<command>`
- Run locally: `<command>`
## Tests
- All tests: `<command>`
- One file: `<command> <path>`
- Run tests before you say a change is done.
## Code style
- <Language and formatter, with the command that applies it.>
- <Naming rule a linter cannot enforce.>
- <Where new modules and tests go.>
## Commits and pull requests
- <Commit message format.>
- <What a PR needs: tests, changelog entry, screenshots.>
## Security
- Never commit secrets or `.env` files.
- <Anything sensitive about this codebase.>
## Boundaries
Ask before you:
- change database migrations or generated files,
- add a dependency,
- change a public API.
Check it into the repository and review changes to it like code. That review path is the point. A team can argue about a line in a pull request, and nobody can do that with an assistant's private notes.
An instructions file is not memory§
It is easy to treat AGENTS.md as the place to put everything the assistant should know. It is the wrong place for most of it, because an instructions file and a memory do different jobs.
An instructions file is static and hand-written. You decide what goes in, you review it, and it describes one repository. Memory is learned over time: a preference you mentioned in passing, a decision and its reason, a correction. It can follow you into another tool or project.
Two different jobs
Instructions file: You write it; Reviewed in a PR; One repository; Rules for everyone. Memory: Learned while working; You can review and edit; Spans tools, projects; What you decided.
The test we use: if a new teammate should read it on day one, it belongs in the file. If you found it out last Tuesday, it is memory. And when a memory keeps proving true, promote it into the file. Our guide on CLAUDE.md vs a memory MCP compares the two in detail, including Claude Code's own auto memory, so we will not repeat it here. For the broader argument, see why AI assistants need a memory they can't lose.
Where a shared memory fits§
Instructions files stop at the repository edge. A chat assistant does not read your repo, and your preference for short answers is not a project rule. If you use Claude Code, Cursor and ChatGPT, each keeps its own picture of you, and none of them knows what the others learned. Our guide to sharing memory between Claude Code and Cursor covers the options.
If you would rather stay file-only, that is a reasonable choice for one person on one tool. The rule of thumb holds either way: files for what the team agreed, memory for what you learned.
Questions, answered§
What is AGENTS.md?
An open, plain-Markdown file at the root of a repository, or in subfolders, that tells coding agents how to build, test and style the project. It has no required fields and is described as a "README for agents." The Agentic AI Foundation, under the Linux Foundation, stewards the format.
Does Claude Code read AGENTS.md?
Yes, natively since v2.1.277, but only when no CLAUDE.md or CLAUDE.local.md exists in your working directory or above it. If one does, Claude reads the CLAUDE.md files alone unless one imports AGENTS.md or you change Project instructions in /config.
Should I symlink CLAUDE.md to AGENTS.md?
Prefer a CLAUDE.md that contains @AGENTS.md plus Claude-specific notes. A symlink works, but Claude's edit tools refuse to write through it, and on Windows symlinks can need elevated rights or turn into one-line text files when Git checks them out.
Which AGENTS.md wins in a monorepo?
On agents.md, Cursor and GitHub Copilot, the file nearest to the code being edited takes precedence, and explicit prompts override everything. Codex works differently. It concatenates files from the project root down to your directory, so closer files come later.
What should I put in AGENTS.md?
Exact build and test commands, code style, project layout, security notes and PR conventions. Leave out anything that changes weekly, anything obvious from the code, and secrets. Keep it short. Anthropic suggests under 200 lines per CLAUDE.md file, and Codex stops reading at 32 KiB by default.
Is AGENTS.md the same as AI memory?
No. It is a file you write and review, tied to one repository. Memory is learned while you work and can be recalled in other tools and projects. A good setup uses the file for rules the whole team shares and memory for what you decide along the way.
Pass it on →