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

Both are Markdown instruction files that coding agents read at the start of a session. AGENTS.md is an open format read by many tools, including OpenAI Codex; CLAUDE.md is Claude Code's own file, with extra features such as imports and local and user-level variants.

How do I use one file for both Codex and Claude Code?

Keep AGENTS.md as the real file. Then either create CLAUDE.md as a symlink to it, or create a CLAUDE.md whose first line is @AGENTS.md, with any Claude-only notes below. Anthropic's docs describe both options.

Which AGENTS.md wins when there are several?

Codex concatenates files from the project root down to the current directory, so closer files come later and override earlier guidance. The agents.md site says the nearest file to the code being edited takes precedence, and chat instructions override all of them.

Is there a size limit for AGENTS.md in Codex?

Yes. OpenAI's Codex docs say it stops adding instruction files once their combined size reaches project_doc_max_bytes, which defaults to 32 KiB. You can raise it or split instructions into nested folders.

Developer blog

AGENTS.md vs CLAUDE.md: What They Are and How to Use Both

Published 3 November 2026 · 7 min read

By Cong Le · Pocket Grove

Original research brief: 3 November 2026. Sources reviewed: 3 November 2026.

Quick answer: AGENTS.md vs CLAUDE.md is mostly a question of who reads what. AGENTS.md is an open instruction file that OpenAI Codex and many other agents read. CLAUDE.md is Claude Code's own file. Recent Claude Code can read AGENTS.md too, but prefers CLAUDE.md when both exist. To serve both, keep one real AGENTS.md and point CLAUDE.md at it.

If you use more than one coding agent, you soon end up with two instruction files that say almost the same thing and slowly drift apart. This post explains, in plain English, what each file is, how the official docs say they load, and the simple setup we use so there is only ever one copy.

It is part of our series on the AI software development lifecycle (SDLC), simply explained. We are not covering what to put in the file here; for that, see Stop putting everything in CLAUDE.md, and for what the research does and does not show about these files, see what peer-reviewed evidence says about CLAUDE.md.

What is AGENTS.md?

The agents.md site describes it as an open, Markdown format for giving coding agents project context. Think of it as a README written for agents rather than people: build steps, test commands, code style and conventions. There are no required fields or headings.

You put it at the root of your repository. In a large monorepo (one repository holding many projects) you can add more AGENTS.md files inside sub-projects. The site lists many tools that support it, including OpenAI Codex, GitHub Copilot's coding agent, Cursor, Gemini CLI and others, and says the format is now stewarded by the Agentic AI Foundation under the Linux Foundation.

What is CLAUDE.md?

CLAUDE.md is the instruction file for Anthropic's Claude Code. Anthropic's memory docs describe it as plain-text instructions that Claude reads at the start of every session. It has more moving parts than AGENTS.md:

Several scopes: an organisation-wide managed file, a personal ~/.claude/CLAUDE.md, a project CLAUDE.md (or .claude/CLAUDE.md), and a personal, git-ignored CLAUDE.local.md.
Imports: a line such as @docs/testing.md pulls another file in, up to four levels deep.
Path rules: files in .claude/rules/ can carry a paths: filter so they only load when Claude works on matching files.

Anthropic also stresses that CLAUDE.md is context, not enforced configuration. To block something every time, use a hook instead.

AGENTS.md vs CLAUDE.md at a glance

	AGENTS.md	CLAUDE.md
Who defines it	Open format (agents.md)	Anthropic, for Claude Code
Main readers	Codex and many other agents	Claude Code
Personal/global file	Codex: `~/.codex/AGENTS.md`	`~/.claude/CLAUDE.md`
Local override	Codex: `AGENTS.override.md`	`CLAUDE.local.md` (personal, git-ignored)
Imports other files	Not part of the format	Yes, with `@path`
Nested files	Yes, nearest wins	Yes; subfolder files load when Claude works there
Size guidance	Codex default cap 32 KiB combined	Anthropic suggests under 200 lines per file

How does Codex load AGENTS.md?

OpenAI's Codex AGENTS.md guide (which currently redirects to learn.chatgpt.com) spells out the order. Codex builds an "instruction chain" once per run:

Global: it looks in your Codex home folder (by default ~/.codex) and uses AGENTS.override.md if present, otherwise AGENTS.md.
Project: it starts at the project root, usually the git root, and walks down to your current folder. In each folder it checks AGENTS.override.md, then AGENTS.md, then any extra names you configured, and takes at most one file per folder.
Merge: it joins the files together from root to current folder. Files closer to where you are come later, so they override earlier guidance.

Two practical limits from the same page. Codex stops adding files once the combined size reaches project_doc_max_bytes, 32 KiB by default. And it stops at your current folder, so files deeper down are not loaded. You can also tell Codex to treat other filenames as instruction files with project_doc_fallback_filenames in ~/.codex/config.toml.

The agents.md site puts precedence more simply: the closest AGENTS.md to the file being edited wins, and explicit instructions in chat override everything.

Does Claude Code read AGENTS.md?

Yes, in recent versions. Anthropic's memory docs say Claude Code can read AGENTS.md as your project instructions without any setup (v2.1.277 or later). But there is a catch worth knowing:

AGENTS.md only, no CLAUDE.md: Claude reads your AGENTS.md files.
Both AGENTS.md and a CLAUDE.md (or CLAUDE.local.md) in your folder or above it: by default Claude reads only the CLAUDE.md files.
A CLAUDE.md that imports AGENTS.md: Claude reads CLAUDE.md, with AGENTS.md included through the import.

Your personal ~/.claude/CLAUDE.md and organisation-managed file do not count for that check, so they still load alongside AGENTS.md. A project CLAUDE.local.md does count, which can quietly switch off AGENTS.md for you. You can change the behaviour with the "Project instructions" setting in /config, for example to read both files together.

Anthropic also lists what Claude Code does not read: AGENTS.local.md, AGENTS.override.md and anything under a .agents/ folder. So Codex's override file is a Codex-only feature.

How do CLAUDE.md files load and which one wins?

According to Anthropic, Claude Code loads CLAUDE.md and CLAUDE.local.md from your current folder and every folder above it. They are all joined together rather than replacing each other, ordered from the top of the file system down to where you started. So the most specific instructions are read last. Files in subfolders load later, when Claude reads or edits something in that subfolder.

Note the difference in wording. Codex describes closer files as overriding; Anthropic says the files are concatenated and that, if two instructions contradict each other, Claude may pick either one. In both tools, the practical fix is the same: do not let your files disagree.

How do you keep one file for both tools?

This is the bit that saves real time. Anthropic's docs describe two ways to keep AGENTS.md as the single shared file:

Option 1, symlink. If you have no Claude-specific instructions, make CLAUDE.md a symbolic link (a pointer to another file) to AGENTS.md:

ln -s AGENTS.md CLAUDE.md

Anthropic says Claude reads the content once either way.

Option 2, import. If you do want a few Claude-only lines, create a real CLAUDE.md that starts with an import:

@AGENTS.md

## Claude Code
Use plan mode for changes under src/billing/.

Claude reads the imported AGENTS.md first, then the rest. Anthropic adds that keeping the import never makes Claude read AGENTS.md twice.

Two things to avoid, both from Anthropic's list of old workarounds. A CLAUDE.md that only says "please read AGENTS.md" in words is unreliable, because Claude sees the file only if it decides to open it. And a startup hook that prints AGENTS.md now adds a second copy to the context.

The agents.md site uses the same symlink trick for renaming: move an old file to AGENTS.md and leave a symlink under the old name.

What we do at Pocket Grove

In our studio, every project folder has one real AGENTS.md and a CLAUDE.md symlink next to it. Our rule is simply that the two can never be separate copies. The same goes for our personal global file: the Codex global AGENTS.md is a symlink to the Claude one, so both tools get the same personal instructions.

We keep the shared file short and put longer procedures in skills and per-app TASKS.md files, which is what both vendors' docs nudge you towards. Cong Le uses this across about 53 iOS and Android apps with Claude Code and Codex. The main benefit is boring and real: we fix an instruction once and both agents see it.

One caution from the docs that we would pass on: if you add a CLAUDE.local.md to a project that relies on AGENTS.md alone, Claude Code will stop reading AGENTS.md unless you change the setting. Check with /context that the file you expect has loaded.

For the wider picture of how these files fit next to tests and reviews, see Claude Code best practices, in plain English.

Sources

AGENTS.md — agents.md (Agentic AI Foundation) — https://agents.md
Custom instructions with AGENTS.md — OpenAI — https://developers.openai.com/codex/guides/agents-md
How Claude remembers your project — Anthropic — https://code.claude.com/docs/en/memory
Best practices for Claude Code — Anthropic — https://code.claude.com/docs/en/best-practices

Frequently asked questions

What is the difference between AGENTS.md and CLAUDE.md?: Both are Markdown instruction files that coding agents read at the start of a session. AGENTS.md is an open format read by many tools, including OpenAI Codex; CLAUDE.md is Claude Code's own file, with extra features such as imports and local and user-level variants.
Does Claude Code read AGENTS.md?: Yes, in recent versions. Anthropic's docs say Claude Code reads AGENTS.md by default only when there is no CLAUDE.md or CLAUDE.local.md in the working directory or above it; a setting lets it read both.
How do I use one file for both Codex and Claude Code?: Keep AGENTS.md as the real file. Then either create CLAUDE.md as a symlink to it, or create a CLAUDE.md whose first line is @AGENTS.md, with any Claude-only notes below. Anthropic's docs describe both options.
Which AGENTS.md wins when there are several?: Codex concatenates files from the project root down to the current directory, so closer files come later and override earlier guidance. The agents.md site says the nearest file to the code being edited takes precedence, and chat instructions override all of them.
Is there a size limit for AGENTS.md in Codex?: Yes. OpenAI's Codex docs say it stops adding instruction files once their combined size reaches project_doc_max_bytes, which defaults to 32 KiB. You can raise it or split instructions into nested folders.