---
title: AGENTS.md vs CLAUDE.md: what it is, who reads it, and how to use both
description: 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.
date: 2026-11-18
updated: 2026-11-18
author: The Esment Team
category: Agents & context
tags: agents-md, claude-md, claude-code, context-engineering
canonical: https://esment.notas.ai/blog/agents-md
---

# AGENTS.md vs CLAUDE.md: what it is, who reads it, and how to use both

*The Esment Team · 2026-11-18 · [HTML version](https://esment.notas.ai/blog/agents-md)*

## 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](https://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](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-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](https://code.claude.com/docs/en/memory), [Codex](https://learn.chatgpt.com/docs/agent-configuration/agents-md), [Cursor](https://cursor.com/docs/context/rules), [GitHub Copilot](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions) and [Gemini CLI](https://geminicli.com/docs/cli/gemini-md/).

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](https://code.claude.com/docs/en/memory) 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.

> [!WARNING]
> In a monorepo, a CLAUDE.md at the root switches off every AGENTS.md below it. A gitignored CLAUDE.local.md does the same, but only on that developer's machine, which makes for a confusing "works for Priya, not for Sam" afternoon.

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.

> [!NOTE]
> As of November 2026, this is what the docs say. The docs also list cases where native reading is unavailable: a version older than v2.1.277, or the built-in plugin turned off in `/plugin`. Before v2.1.281, some sessions, such as those on Amazon Bedrock, read CLAUDE.md only. We could not confirm release dates for these versions.

## 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.

**Figure.** The shared rules live in AGENTS.md. A short CLAUDE.md imports them and adds Claude-only notes.

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:

```md
@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.

> [!STEPS]
> 1. If you have an old CLAUDE.md, rename it to AGENTS.md. Keep the shared parts and move Claude-only parts aside.
> 2. Create a new CLAUDE.md whose first line is `@AGENTS.md`, followed by a `## Claude Code` section for the Claude-only notes.
> 3. Start Claude Code in the repository and run `/context all`. CLAUDE.md should appear under **Memory files**.
> 4. 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](https://esment.notas.ai/blog/claude-memory-not-working) 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.** `@path` imports work in both files.
- **Hooks.** `InstructionsLoaded` hooks 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](https://esment.notas.ai/learn/claude-code-context). If you want a hook that loads notes at the start of each session, see [Claude Code hooks for memory](https://esment.notas.ai/blog/claude-code-hooks-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](https://esment.notas.ai/learn/the-context-window). Our [context engineering checklist](https://esment.notas.ai/blog/context-engineering) 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.

```md
# 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.

**Figure: Two different jobs.** AGENTS.md holds the rules the team agreed on. Memory holds what you worked out along the way.

| Instructions file | Memory |
|---|---|
| You write it | Learned while working |
| Reviewed in a PR | You can review and edit |
| One repository | Spans tools, projects |
| Rules for everyone | 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](https://esment.notas.ai/learn/claude-md-vs-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](https://esment.notas.ai/blog/why-ai-assistants-need-memory).

## 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](https://esment.notas.ai/learn/share-memory-claude-code-cursor) covers the options.

> [!ESMENT]
> Esment is a local-first memory that Claude Code, Cursor and ChatGPT can all read and add to, so a decision you made in one is there in the others. It does not replace AGENTS.md. Keep the repo's rules in the file and use memory for what follows you. See [how Esment works](https://esment.notas.ai/learn/how-esment-works) and [connecting your assistants](https://esment.notas.ai/docs/assistants).

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.
