CLAUDE.md vs AGENTS.md: one rules file for Claude Code and Codex

Put the shared rules in AGENTS.md. By default, Claude Code reads that file directly from v2.1.277 when no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md sits in the working directory or any folder above it, and Codex reads it out of the box. If you keep a CLAUDE.md for lines only Claude Code needs, start it with an import of that file: @AGENTS.md in a CLAUDE.md next to it. Then check what loaded in both AI engines, because one stray file can split them without a word.

How each engine finds its rules

Claude Code starts at the working directory and looks up. Codex starts at the project root, typically the Git root, and walks down to the current directory. The Claude Code memory docs and the Codex AGENTS.md guide each cover one side. This table puts them next to each other, as checked on 30 Oct 2026.

	Claude Code	Codex
Files it reads	CLAUDE.md, .claude/CLAUDE.md and CLAUDE.local.md in the working directory and above. AGENTS.md from v2.1.277, by default only when none of those exist.	AGENTS.override.md or AGENTS.md in the Codex home (~/.codex by default). Then, from the project root down: AGENTS.override.md, AGENTS.md, then names in project_doc_fallback_filenames. At most one file per directory.
Files it ignores	AGENTS.local.md, AGENTS.override.md and anything under .agents/.	Empty files, plus CLAUDE.md and any other name missing from the fallback list.
Order and precedence	By default a CLAUDE.md takes the place of AGENTS.md. With claude-md-and-agents-md, each directory's CLAUDE.md files come first and its AGENTS.md after. An @AGENTS.md import comes before the lines below it.	Codex home first, then root down, joined with blank lines. Files closer to the current directory come later and override earlier guidance.
Size limits	Target under 200 lines per CLAUDE.md. A file over 4 MiB is skipped. Imports don't reduce context.	Stops adding files once the combined size reaches project_doc_max_bytes, 32 KiB by default.
How to check what loaded	/context (under Memory files), /memory, and the no CLAUDE.md found; AGENTS.md loaded line.	Ask with codex --ask-for-approval never "Summarize the current instructions.", or read the TUI log.
Where review rules go	CLAUDE.md for /code-review and the Code Review service. REVIEW.md for the service only.	A ## Code Review Rules section in the AGENTS.md closest to the code, for Codex code review in GitHub.

Set up one rules file in 6 steps

1. Write the rules in AGENTS.md

Put every rule both AI engines must follow in AGENTS.md at the repo root, in the file's own text. Keep it short. Codex stops adding files at 32 KiB by default, and the Claude Code docs target under 200 lines per CLAUDE.md. Splitting the file with imports won't buy you room in Claude Code, because imported files load with the file that imports them.

2. Decide if you need a CLAUDE.md at all

With only AGENTS.md, and no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md anywhere up the path, both AI engines read the same file. Start there. Your personal ~/.claude/CLAUDE.md, your organization's managed CLAUDE.md and .claude/rules/ files don't count for that check, and they keep loading alongside AGENTS.md.

Lines only Claude Code should see don't need one: put them in .claude/rules/, which keeps loading next to AGENTS.md. A project CLAUDE.md is still an option if you'd rather keep those lines in one file. It's also the fallback for a session that reads CLAUDE.md files only. Before v2.1.281 that included some Amazon Bedrock sessions and sessions with telemetry disabled.

3. If you keep one, import AGENTS.md at the top

@AGENTS.md

## Claude Code only

Use plan mode for changes under `src/billing/`.

Claude Code reads the imported file first, then the lines below it. Keeping the import never makes it read AGENTS.md twice.

Three details:

• The path resolves from the file holding the import, so this line means the AGENTS.md next to that CLAUDE.md. In .claude/CLAUDE.md, write @../AGENTS.md to reach the one at the repo root.
• An import that resolves outside the working directory triggers a one-time approval dialog per project. Decline it and the imports stay disabled.
• Write the line bare. Import parsing skips code spans and fenced code blocks, so an @ path in backticks stays literal.

A CLAUDE.md that only says "read AGENTS.md" in words is weak. Claude Code sees the file only if it decides to open it. Replace the sentence with the import, or delete that CLAUDE.md.

4. Symlink only if it fits

ln -s AGENTS.md CLAUDE.md

This works when you need no lines just for Claude Code and nobody on the repo uses Windows. Claude Code's Edit and Write tools refuse to write through the link and point it to the target, so edits land in AGENTS.md. With any Windows user on the repo, use the import.

5. Leave AGENTS.override.md alone unless you mean it

In each directory Codex checks AGENTS.override.md first and reads at most one file, so an override hides the AGENTS.md beside it from Codex. Claude Code doesn't read overrides at all. Create one only for a rule you want in Codex and nowhere else.

6. Verify both AI engines

In Claude Code, start a new session:

• With a CLAUDE.md (import or symlink), run /context and confirm CLAUDE.md appears under Memory files.
• With AGENTS.md alone, an interactive session shows a line like no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md. From v2.1.280 you can also run /memory and look for the file's path. Older versions leave an AGENTS.md read this way off that list, so rely on the startup line there.

In Codex, run these only in a repo you already trust. The first goes in the repo root and the second checks a nested folder:

codex --ask-for-approval never "Summarize the current instructions."
codex --cd subdir --ask-for-approval never "Show which instruction files are active."

For a record of what loaded, start Codex with codex -c log_dir=./.codex-log and read ./.codex-log/codex-tui.log. Codex builds its chain once per run, so restart it in the target directory after an edit. There's no cache to clear.

Traps that split the two AI engines

CLAUDE.local.md

Add a CLAUDE.local.md for your personal, uncommitted notes in a project that relies on AGENTS.md, and Claude Code stops reading AGENTS.md. Codex keeps reading it. That's a lot of power for a file nobody commits. To keep both, run /config and set Project instructions to claude-md-and-agents-md.

A CLAUDE.md in a parent folder

The check covers the working directory and every folder above it. A CLAUDE.md above the repo silently turns off the direct AGENTS.md read under the default setting, and Codex carries on with AGENTS.md. ~/.claude/CLAUDE.md is exempt. If the no CLAUDE.md found line is missing from a new session, look up the path first.

AGENTS.override.md

Rules placed here reach Codex only. If Codex follows guidance you can't find, look for an override higher in the tree or in the Codex home.

The 32 KiB Codex cap

The cap applies to the combined size of the chain, and Codex stops adding files once it reaches project_doc_max_bytes. A file that's fine in Claude Code can still run past it. Raise the limit or split the rules across nested directories.

@ lines in AGENTS.md

Claude Code expands @path imports inside an AGENTS.md it reads. The Codex guide describes no import syntax, so don't count on an @ line in AGENTS.md reaching Codex. Put rules Codex must follow in the file's own text.

A SessionStart hook that prints AGENTS.md

This is an old workaround. Remove it once Claude Code reads AGENTS.md directly, because it adds a second copy to the context.

/import

/import appends a one-time copy of AGENTS.md into the matching CLAUDE.md. Later edits to AGENTS.md don't reach that copy. The @AGENTS.md line pulls in the live file instead.

Windows symlinks

Creating a symlink on Windows needs Administrator privileges or Developer Mode. Git checks a committed symlink out as a plain text file unless core.symlinks is enabled, which leaves a one-line CLAUDE.md in place of your instructions.

Where review rules go

Codex code review in GitHub reads a ## Code Review Rules section in the AGENTS.md closest to the code. Put repo-wide checks at the root and service checks in nested files.

Claude Code has two review tools, and they read different files. The local /code-review command reads CLAUDE.md files and not REVIEW.md. The managed Code Review service on GitHub pull requests reads CLAUDE.md and REVIEW.md, and it takes REVIEW.md from the base or default branch, never from the pull request's own changes. Guidance you want in both goes in CLAUDE.md.

None of this blocks anything. In Claude Code, CLAUDE.md and AGENTS.md are context, not enforced configuration. To block an action whatever Claude Code decides, use a PreToolUse hook.

Checklist

• AGENTS.md holds every rule both AI engines must follow, in its own text.
• Claude Code is on v2.1.277 or later.
• No CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md sits in the working directory or above it, unless you meant it.
• Any CLAUDE.md you keep is either a symlink to AGENTS.md or a regular file that starts with a bare import of it (@AGENTS.md next to it, @../AGENTS.md from .claude/CLAUDE.md), with lines only Claude Code needs below it.
• No CLAUDE.md tells Claude Code in words to read AGENTS.md.
• No CLAUDE.md symlink exists if anyone on the repo uses Windows.
• No AGENTS.override.md exists in the tree or the Codex home, unless you want Codex to differ.
• The combined Codex instructions fit under 32 KiB, or you raised project_doc_max_bytes.
• No SessionStart hook prints AGENTS.md.
• A new Claude Code session shows CLAUDE.md under Memory files in /context, or the AGENTS.md loaded line at startup.
• codex --ask-for-approval never "Summarize the current instructions." from the repo root gives back your rules.
• Codex review rules sit under ## Code Review Rules in AGENTS.md, and Claude Code review rules sit in CLAUDE.md.

How I keep one set of rules across repos

I use the same split for the rules that follow me across repos. In my Two Engines Kit for Claude Code and Codex, RULES.md holds the shared rules, and claude.md and codex.md hold the few lines that differ. Claude Code imports the live files and sync.sh builds the Codex copy. The installer points ~/.claude/CLAUDE.md at the shared rules, builds ~/.codex/AGENTS.md from them, previews each change and asks, and backs up what it replaces. uninstall.sh restores it.

FAQ

Does Claude Code read AGENTS.md?

It does, from v2.1.277. By default it reads AGENTS.md only when there's no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or any directory above it.

Should I symlink CLAUDE.md to AGENTS.md?

Only if you need no lines just for Claude Code and nobody on the repo uses Windows. In every other case, use the @AGENTS.md import.

Why is my AGENTS.md not loading in Claude Code?

Check these in order:

• Your version: reading AGENTS.md directly needs v2.1.277.
• A CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or above it.
• The Project instructions value in /config: the claude-md and managed-only values don't give you the direct read.
• The session type: before v2.1.281, some sessions read CLAUDE.md files only, so import AGENTS.md from a CLAUDE.md there.
• The list itself: before v2.1.280, /memory and /context didn't show an AGENTS.md read directly, so the file can load and stay off the list.

Does Codex read CLAUDE.md?

No, not by default. It reads AGENTS.override.md, AGENTS.md and any names in project_doc_fallback_filenames in ~/.codex/config.toml. Fallback names come last and Codex reads at most one file per directory, so a directory's AGENTS.md still wins over a fallback.

How big can AGENTS.md be?

Codex stops adding files once the combined size reaches 32 KiB by default. Raise project_doc_max_bytes or split the rules across nested directories. On the Claude Code side, the docs target under 200 lines per CLAUDE.md and Claude Code skips a file over 4 MiB.

Comments

[Robb Lejuwaan]

Good writeup. We went the same way: one short shared file, with tool-specific bits in their own small files. Two files that disagree are worse than one file that's missing a rule.