AGENTS.md vs CLAUDE.md: which file each tool reads

In AGENTS.md vs CLAUDE.md, Codex reads AGENTS.md and Claude Code reads CLAUDE.md, though Claude can also read a repository’s AGENTS.md files in place of CLAUDE.md. So one AGENTS.md at the repo root can serve both tools. The differences are in where each tool looks and how it merges files.

What each tool reads

Codex has one file name to remember. Codex reads AGENTS.md files before doing any work, and in each directory it checks AGENTS.override.md first. Claude Code has more locations, because it also keeps a personal file that stays out of version control.

The shared name came from outside either vendor. AGENTS.md is now stewarded by the Agentic AI Foundation under the Linux Foundation, and its stated purpose is to hold the build steps, tests and conventions that would clutter a README.

How the files merge

Both tools build one prompt from several files, so order matters. Codex starts at the project root, walks down to the working directory and takes at most one file per directory. Claude Code does the reverse walk: it loads files from the working directory and every directory above it.

In a monorepo this lines up well. The AGENTS.md spec says the closest AGENTS.md to the edited file wins; explicit user chat prompts override everything, and it points at the main OpenAI repo, which has 88 AGENTS.md files at time of writing.

repo/
  AGENTS.md          shared rules for every agent
  CLAUDE.md          one line that pulls in AGENTS.md
  packages/api/
    AGENTS.md        rules for this package only

Serving both tools from one repo

The simplest route is to write only AGENTS.md. Claude Code’s memory page has a dedicated AGENTS.md section on when ./AGENTS.md loads instead of or alongside CLAUDE.md, and that section is worth reading before relying on it, since the details depend on your setup.

The second route is a thin CLAUDE.md. The docs say CLAUDE.md files can import additional files using @path/to/import syntax, so a one-line import should point Claude Code at the shared file. That exact line is not shown in the docs excerpt used here, so test it with /context, which lists loaded files under Memory files.

@AGENTS.md

## Claude Code only
- Prefer the project skills over long ad hoc prompts.

Anything specific to one tool goes below the import, which keeps the shared file honest. The same idea applies to skills, covered in sharing one skills repo between Claude Code and Codex.

If an older AGENT.md already exists, the AGENTS.md site gives a migration line:

mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md

What to put in the shared file

AGENTS.md is plain Markdown: No. AGENTS.md is just standard Markdown when asked about required fields, so headings are your choice. Commands that run, such as test and lint lines, tend to be the most useful content, and brevity helps both tools given their size guidance.

## Build and test
- Run `pnpm test` before committing.
- Run `pnpm lint` after moving files.
## Conventions
- API handlers live in src/api/handlers/.

One caveat applies to Claude Code in particular. It treats them as context, not enforced configuration, so a rule that must never be broken belongs in a hook instead. The Claude Code hooks guide covers the setup, and context size ties into the usage limits post.

Verdict

Use one AGENTS.md as the source of truth, since Codex reads it directly and Claude Code can read it in place of CLAUDE.md. Add a thin CLAUDE.md only if the in-place route does not load it in your setup, and verify with /context.

Try it on your own plan: read the Claude Code memory docs