Most advice on CLAUDE.md vs AGENTS.md was written when Claude Code ignored AGENTS.md and you had to pick a side or maintain two files. That stopped being true this year, and the right setup for a team using both Claude Code and Codex is now simpler than most guides suggest.
- Same job, different readers. Both files are plain Markdown instructions loaded before the agent works. CLAUDE.md is Claude Code's; AGENTS.md is an open format read by Codex and many other tools.
- Claude Code now reads AGENTS.md when a repository has no CLAUDE.md. Codex still doesn't read CLAUDE.md unless you configure a fallback filename.
- For a mixed team, AGENTS.md is the source of truth. If you need Claude-only rules, add a CLAUDE.md whose first line is
@AGENTS.md. - The loading rules differ. Codex caps the combined file at 32 KiB. Claude Code recommends under 200 lines per file.
- Neither file enforces anything. Rules that must hold go in hooks, permissions or the sandbox.
- Procedures belong in skills, not in either file.
CLAUDE.md vs AGENTS.md: two files, one job
An AI coding agent starts every session knowing nothing about your project. An instruction file fixes that: the agent reads it first, so you don't re-explain the build command, the branch policy and the one directory nobody should touch.
CLAUDE.md and AGENTS.md are both that file. They're both plain Markdown, they both live in the repository, and neither has a schema. The differences are practical:
| CLAUDE.md | AGENTS.md | |
|---|---|---|
| Who defined it | Anthropic, for Claude Code | An open format, now under the Linux Foundation |
| Read natively by | Claude Code | Codex, Cursor, Gemini CLI (with a setting) and many others; Claude Code as a fallback |
| Personal global file | ~/.claude/CLAUDE.md |
~/.codex/AGENTS.md (for Codex) |
| Imports | @path/to/file |
None in the format; plain Markdown |
| Size guidance | Under 200 lines per file | Codex stops at 32 KiB combined by default |
| Enforced? | No | No |
We come at this with uneven experience, and it's worth saying which way it leans. Rough Works runs Claude Code daily. We maintain one global CLAUDE.md of 107 lines, about twenty project-level ones, and exactly one repository, a client site repo, that uses AGENTS.md with no CLAUDE.md at all. Codex is installed and lightly used. So the Claude side below is lived, and the Codex side is documentation checked against the installed CLI. Everything vendor-specific was read from the official docs on November 18, 2026.
If the whole category is new to you, AI agents explained is the place to start.
What an AGENTS.md file is, and who reads it
The agents.md site describes the format as "a simple, open format for guiding coding agents", a README for agents. A human README explains the project to people. AGENTS.md holds the build steps, test commands and conventions that would clutter that README but that an agent needs every time.
Is it a standard? It's an open convention with a steward. The site says it is now stewarded by the Agentic AI Foundation under the Linux Foundation. There's no specification to validate against: the FAQ says there are no required fields, just Markdown with whatever headings you like. The site claims more than 60,000 open-source projects use it; that's the site's own figure, which we haven't checked.
The site's list of supporting tools includes OpenAI Codex, Cursor, Gemini CLI, GitHub Copilot's coding agent, Zed, Aider, Devin, Windsurf and JetBrains Junie, among others. As of November 2026, Claude Code isn't on that list, even though Anthropic's own documentation now says Claude Code reads the file. We'll get to that.
The site suggests these sections:
- Project overview
- Build and test commands
- Code style guidelines
- Testing instructions
- Security considerations
And it documents two behaviours that most tools follow: in a monorepo you can nest an AGENTS.md in each package, and the file closest to the code being edited takes precedence. An explicit instruction in your prompt overrides all of them.
How AGENTS.md works in Codex
Codex is the reference implementation most people mean when they search "AGENTS.md Codex", and OpenAI's AGENTS.md guide is precise about discovery.
1. Global scope. In the Codex home directory (~/.codex unless CODEX_HOME is set), Codex reads AGENTS.override.md if it exists, otherwise AGENTS.md. It uses only the first non-empty file.
2. Project scope. Codex starts at the project root, typically the Git root, and walks down to your current working directory. In each directory it checks AGENTS.override.md, then AGENTS.md, then any fallback names you've configured. It includes at most one file per directory.
3. Merge order. Files are concatenated from the root down, joined by blank lines. In OpenAI's words, "files closer to your current directory override earlier guidance because they appear later in the combined prompt."
So for a session started in services/payments/, the chain looks like this:
~/.codex/AGENTS.md (global, first)
repo/AGENTS.md (project root)
repo/services/payments/AGENTS.md (closest, last, wins on conflict)
The size limit. Codex skips empty files and stops adding files once the combined size reaches project_doc_max_bytes, which defaults to 32 KiB. Past that, instructions are silently left out. The documented fix is to split guidance into nested directories or raise the limit:
# ~/.codex/config.toml
project_doc_max_bytes = 65536
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
Overrides. AGENTS.override.md replaces the AGENTS.md in the same directory. It's meant for temporary changes: drop one in, work, delete it. Because Codex stops searching at your current directory, an override only helps if it sits at or above where you launch.
Checking what loaded. The guide's own test is to ask:
codex --ask-for-approval never "Summarize the current instructions."
codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."
Codex rebuilds the chain on every run, so there's no cache to clear. If instructions look stale, restart it in the right directory.
One more use: Codex's GitHub code review reads a ## Code Review Rules section from the AGENTS.md nearest each changed file. The same file steers both the agent that writes and the one that reviews. The rest of the Codex setup is in our Codex CLI guide.
How CLAUDE.md works in Claude Code
Claude Code's memory documentation lists four scopes, loaded from broadest to most specific:
| Scope | Location | Shared with |
|---|---|---|
| Managed policy | A system path set by IT, such as /etc/claude-code/CLAUDE.md on Linux |
Everyone in the organisation |
| User | ~/.claude/CLAUDE.md |
Only you, in every project |
| Project | ./CLAUDE.md or ./.claude/CLAUDE.md |
The team, through version control |
| Local | ./CLAUDE.local.md (gitignored) |
Only you, in this project |
How they load:
- Upward at launch. Claude Code loads
CLAUDE.mdandCLAUDE.local.mdfrom the working directory and every directory above it, concatenated from the filesystem root down, so the closest file is read last. - Downward on demand. A
CLAUDE.mdin a subdirectory loads when Claude reads or edits a file in that subdirectory, not at launch. - Imports. A line containing
@path/to/filepulls that file in. Imports can nest four levels deep. A path inside backticks or a code block is not imported. - Comments are free. Block-level HTML comments are stripped before the file reaches the model, so you can leave notes for human maintainers at no context cost.
Two commands are worth knowing. /init generates a starting file from your codebase. /context all lists what actually loaded under Memory files, which is the Claude Code equivalent of asking Codex to list its sources.
The size guidance is different in kind from Codex's hard cap. Anthropic's docs say to "target under 200 lines per CLAUDE.md file", because longer files "consume more context and reduce adherence". Imports help you organise a long file, but they don't reduce its cost, since imported files load with the file that imports them.
Our own global file is 107 lines. It has thirteen short sections with titles like "Verify before you assert", "Delegation", "Finish the change" and "Memory hygiene". Several cite the mistake that prompted them. Here is the start of one, as written:
## Find the source of truth before editing
- When a value appears in more than one place, work out which copy the
running code actually reads, then update all of them. Config duplicated
into prose, comments, or prompt strings drifts silently.
- **A config string fed into an LLM prompt is behavior, not documentation.**
Project files are shorter and about the repository only: how merging deploys, which file is the real spending limit, where the tracking tags actually live. We go through what earns a place in CLAUDE.md best practices.
Does Claude Code read AGENTS.md? Yes, with rules
This is the part that changed, so here is exactly what Anthropic's docs say as of November 2026. Don't rely on older answers, including the absence of Claude Code from the agents.md supporter list.
Claude Code "can read AGENTS.md as your project instructions, so a repository already set up for other coding agents works without adding a CLAUDE.md, an import, or a setting." Reading it directly requires Claude Code v2.1.277 or later. The default behaviour:
| Your repository has | Claude reads |
|---|---|
AGENTS.md, and no CLAUDE.md or CLAUDE.local.md in the working directory or above |
AGENTS.md |
AGENTS.md and a CLAUDE.md or CLAUDE.local.md in the working directory or above |
The CLAUDE.md files only |
A CLAUDE.md that imports AGENTS.md |
CLAUDE.md, with AGENTS.md included through the import |
The details that will catch you out:
- Your personal global file doesn't count.
~/.claude/CLAUDE.md, a managed organisation file and.claude/rules/keep loading alongsideAGENTS.md. - A
CLAUDE.local.mddoes count. Add one for your private notes in anAGENTS.mdrepository and Claude stops readingAGENTS.mdfor you. - "Or above" means any parent directory. A stray
CLAUDE.mdin a folder above your repository switches the fallback off. - Codex-only files are ignored. Claude Code does not read
AGENTS.override.md,AGENTS.local.mdor anything under a.agents/directory. - You get told. In an interactive session a line appears such as
no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md.
To change the default, type /config in a session and set Project instructions. The documented values are claude-md-or-agents-md (the default), claude-md-and-agents-md (read both), claude-md (ignore AGENTS.md) and managed-only.
The docs also list the sessions where direct AGENTS.md support isn't available: versions before v2.1.277, sessions where the built-in plugin that reads it has been disabled, and in some cases the first session after upgrading. For those, the import below is the fallback.
Our one AGENTS.md repository has no CLAUDE.md, and the machine runs v2.1.327, so by these rules Claude Code reads its AGENTS.md directly, alongside our global file. That's the documented behaviour. We're stating the rule here, not the result of a separate test.
One source of truth when a team uses both tools
Two files that say the same thing will disagree within a month. Someone updates the test command in one and not the other, and the two agents start following different rules. Pick one file to own the content. Both vendors' documentation supports that; these are the three documented ways, in the order we'd choose them.
Option 1: AGENTS.md only. Keep a single AGENTS.md and no CLAUDE.md. Codex reads it natively. Claude Code reads it through the default fallback. This is the least to maintain, and it's what our client site repo does. It works as long as everyone is on a current Claude Code and nobody adds a CLAUDE.md or CLAUDE.local.md.
Option 2: AGENTS.md plus a thin CLAUDE.md that imports it. This is the most robust setup, and the one Anthropic's docs show for sharing a file with other tools:
@AGENTS.md
## Claude Code
Use plan mode for changes under `src/billing/`.
Claude reads the imported file first, then the Claude-specific section. Codex never sees CLAUDE.md, so nothing is duplicated. Use this when you have instructions that only make sense for Claude Code (a permission mode, a skill to invoke, a subagent to prefer), or when some sessions can't load AGENTS.md directly. The docs confirm that keeping the import never makes Claude read AGENTS.md twice.
Option 3: a symlink.
ln -s AGENTS.md CLAUDE.md
This works when you need no Claude-specific content, with two caveats from Anthropic's docs. Claude's edit tools refuse to write through a symlink and will be pointed at AGENTS.md instead. And on Windows, creating a symlink needs Administrator rights or Developer Mode, and Git checks a committed symlink out as a one-line text file unless core.symlinks is enabled. If anyone on the team uses Windows, use the import.
Going the other way. If your repository already has a good CLAUDE.md and you're adding Codex, you have two documented choices. Rename it to AGENTS.md and apply option 1 or 2. Or tell Codex to accept the existing name:
# ~/.codex/config.toml
project_doc_fallback_filenames = ["CLAUDE.md"]
The second is per-user configuration, so every Codex user on the team has to set it. Renaming is a one-off.
What not to do: a CLAUDE.md that says, in prose, "see AGENTS.md for instructions". Anthropic's docs are blunt about this: Claude then sees AGENTS.md "only if it decides to open the file". Use the @ import or delete the file.
Whichever you pick, verify it. Run /context all in Claude Code and the summarise-your-instructions command in Codex, in the same directory, and compare.
A real AGENTS.md example, and what makes it work
Here is the AGENTS.md from that client site repo, with the client's name removed, three paths generalised and one machine-specific line dropped. Otherwise this is the whole file.
# Project navigation
Read `docs/delivery-status.md` first for current authorization, tool
limits, validation evidence, and the next action. Older ticket and review
documents are historical where that record supersedes them.
For page work, follow `docs/build-contract.md` and the relevant ticket
in the issues folder. The approved scope is `docs/website-spec.md`.
Use `package.json` and the CI workflow file for check commands.
Three paragraphs. It works because of what it leaves out:
- It contains no status. What's approved and what's next changes weekly, so the file points at the document that holds it. The instruction file never goes stale.
- It contains no commands. The check commands live in
package.jsonand the CI workflow, where they're executed. Copying them into prose creates a second copy to drift. - It settles conflicts in advance. "Older documents are historical where that record supersedes them" tells the agent which source wins when two disagree. That's the most common way an agent goes wrong in a long-running project.
That won't suit every repository. A project with no docs folder needs the commands written out. If you're starting from nothing, this template follows the sections the agents.md site recommends. Replace every line with your own; a generic instruction is worse than none.
# AGENTS.md
## Setup and checks
- Install: `<your install command>`
- Test: `<your test command>` (run before every commit)
- Lint: `<your lint command>`
## Conventions
- <the two or three rules people actually break>
## Boundaries
- Do not edit `<generated or vendored paths>`.
- Ask before changing `<pricing, auth, migrations>`.
## Where the truth lives
- Deploy behaviour: `<path to the workflow file>`
- Current scope and status: `<path to the doc>`
A few AGENTS.md best practices that hold for CLAUDE.md too:
- Write instructions you could verify. Anthropic's docs give the contrast: "Run
npm testbefore committing" beats "Test your changes". - Add a rule when the agent gets something wrong twice, not in anticipation.
- Put directory-specific rules next to the code, in a nested file, so they load only when relevant.
- Remove contradictions. The docs warn that when two instructions conflict, the model "may pick one arbitrarily". Claude Code has an audit for this:
/doctor prompt-auditreviewsCLAUDE.mdandAGENTS.mdfiles for outdated or conflicting content and proposes edits. - Re-read the file when you change tools. A rule written for last year's model may be noise now.
What belongs in neither file
The fastest way to improve an instruction file is to take things out. These don't belong in CLAUDE.md or AGENTS.md.
Secrets. Both files are committed and both are sent to a model. No tokens, no passwords, no private URLs.
Rules that must never be broken. Anthropic's docs say Claude treats CLAUDE.md as "context, not enforced configuration", and their extension guide puts it more sharply: an instruction like "never edit .env" is "a request, not a guarantee". The same is true of AGENTS.md in any tool. If a rule has to hold every time, enforce it: a pre-tool hook, a permission deny rule, or the sandbox. We keep one hard rule about commits in a shared checkout in a hook for exactly this reason, and Claude Code hooks shows how.
Multi-step procedures. A deploy checklist or a release routine is a skill. This is the answer to "AGENTS.md vs SKILL.md": an instruction file is loaded in full, every session, whether or not it's relevant. A skill is a folder with a SKILL.md whose short description is all the agent sees until a task calls for it. Both tools use the same skill format; Codex looks in .agents/skills, Claude Code in .claude/skills. Our Claude skills guide covers writing one.
Personal preferences. Your editor habits and sandbox URLs go in your own file: ~/.claude/CLAUDE.md or CLAUDE.local.md for Claude Code, ~/.codex/AGENTS.md for Codex. Remember that a CLAUDE.local.md switches off Claude's AGENTS.md fallback unless you change the Project instructions setting.
Values that live somewhere else. A price ceiling, a version number, a campaign name. Our own rule, quoted above, exists because a duplicated value in an instruction is read by the model as the truth. If it's stale, the agent quietly follows the stale one. Point to the file that holds the value.
Anything the agent can read from the code. Directory layout, the framework in use, what a function does. Anthropic's advice for /init output is to refine it with "instructions Claude wouldn't discover on its own". That's the test for every line.
History. What was fixed last month is not an instruction. Our global file says it this way: write the rule, not the incident.
Our defaults
- One agent, Claude Code → a short
CLAUDE.md. No need forAGENTS.md. - One agent, Codex → a short
AGENTS.md. - Both tools, or contractors with their own tools →
AGENTS.mdas the source of truth. Add aCLAUDE.mdstarting with@AGENTS.mdonly when you have Claude-only instructions. - Anyone on Windows → import, not symlink.
- A rule that must hold → not in either file. Enforce it.
- A procedure → a skill.
- Every quarter → read both files aloud and delete what's no longer true.
The CLAUDE.md vs AGENTS.md question used to be about picking a vendor. It's now about where one set of rules lives and which tool imports it. Decide that once, write it down in the repository, and both agents will follow the same rules.
We set up instruction files, skills and guardrails for client teams as part of our AI integration work, and the way we work with these tools day to day is in Claude Code for web development. If you'd like a second pair of eyes on yours, send it over.
Common questions
AGENTS.md vs CLAUDE.md: which one should my repo have?
If more than one coding agent touches the repository, make AGENTS.md the source of truth, because the widest range of tools read it. As of November 2026, Claude Code reads AGENTS.md directly when the repository has no CLAUDE.md, and Codex reads it natively. Add a CLAUDE.md only when you need Claude-specific instructions, and start that file with an @AGENTS.md import so the shared rules are never copied. If your team only uses Claude Code, a CLAUDE.md alone is fine.
CLAUDE.md vs AGENTS.md: what is the difference?
They do the same job: plain Markdown instructions an agent reads before it works. The differences are in who reads them and how they load. CLAUDE.md is Claude Code's file, with user, project and local scopes, an @path import syntax and a recommended size under 200 lines. AGENTS.md is an open format read by Codex and many other tools; Codex merges files from the project root down and stops at 32 KiB by default. Neither file is enforced. Both are guidance the model weighs.
What is an AGENTS.md file?
An AGENTS.md file is a plain Markdown file, usually in the root of a repository, that tells coding agents how to work there: how to install and build, how to run tests, which conventions to follow and what to avoid. The agents.md site describes it as a simple, open format and a README for agents. There are no required fields or special syntax. Agents that support it read it automatically at the start of a task.
How does AGENTS.md work in Codex?
Codex builds an instruction chain at the start of each run. It reads a global file from ~/.codex first, using AGENTS.override.md if present and AGENTS.md otherwise. Then it walks from the project root down to your working directory and takes at most one file per directory. The files are concatenated root first, so the closest file comes last and wins. It stops adding files at project_doc_max_bytes, which defaults to 32 KiB.
Can you show an AGENTS.md example?
A good AGENTS.md is short and points at things. One of ours, in a client site repo, is three paragraphs: read the delivery-status document first, follow the build contract and the relevant ticket for page work, and take check commands from package.json and the CI workflow. The agents.md site suggests sections for project overview, build and test commands, code style, testing instructions and security considerations. Start with commands and the two or three rules people break most.
What are the AGENTS.md best practices?
Keep it short, specific and verifiable. Write commands exactly as they should be run. Point to the file that holds the truth instead of copying values that will drift. Put directory-specific rules in a nested AGENTS.md next to the code they govern. Leave out secrets, long procedures and anything that changes weekly. Move step-by-step workflows into skills and rules that must never be broken into hooks or sandbox settings, because an instruction file is guidance and not enforcement.
Is AGENTS.md a standard, and how is AGENTS.md different from SKILL.md?
AGENTS.md is an open format stewarded by the Agentic AI Foundation under the Linux Foundation, and the agents.md site lists more than twenty tools that read it. It is a convention with no schema. SKILL.md is a different thing: it defines one skill, a packaged procedure with a name and description that an agent loads only when a task needs it. AGENTS.md is always in context; a skill is loaded on demand. Use AGENTS.md for standing rules and skills for repeatable workflows.

