AGENTS.md and CLAUDE.md: One Instruction File for Both

If your team uses both Claude Code and Codex, you can keep one set of project instructions and have both tools read it. Put the shared rules in AGENTS.md, which Codex reads natively, and add a short CLAUDE.md that imports it. This article shows how each tool finds its files, where they disagree, and how to check what actually loaded.

Which file does each tool read?

Codex reads AGENTS.md. Claude Code reads CLAUDE.md, and since v2.1.277 it can also read AGENTS.md directly. The catch is a precedence rule that surprises people.

By default, Claude Code reads your AGENTS.md only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or any directory above it. If one exists, Claude reads the CLAUDE.md files only. Your ~/.claude/CLAUDE.md, your organisation's managed CLAUDE.md and .claude/rules/ files do not count for that check, and keep loading alongside AGENTS.md.

A side effect: adding a personal CLAUDE.local.md to a project that relies on AGENTS.md makes Claude stop reading AGENTS.md for you, unless you change the setting described below.

Direct reading is also unavailable in some sessions: on versions before v2.1.277, if you disabled the built-in plugin that reads AGENTS.md, and in some cases in the first session after an upgrade from v2.1.276 or earlier. Before v2.1.281, some sessions (for example on Amazon Bedrock, or with telemetry disabled) read CLAUDE.md files only. In all of these, import AGENTS.md from a CLAUDE.md instead.

How does Codex find AGENTS.md?

Codex builds its instruction chain from two scopes:

• Global: in ~/.codex (or CODEX_HOME), it uses AGENTS.override.md if present, otherwise AGENTS.md. Only the first non-empty file counts.
• Project: from the project root (usually the Git root) down to the current directory, it checks each directory for AGENTS.override.md, then AGENTS.md, then any names in project_doc_fallback_filenames. At most one file per directory is included.

Files are concatenated from root to current directory, so the file closest to your work appears last and overrides earlier guidance. AGENTS.override.md replaces AGENTS.md in the same folder, which is handy for a temporary change you intend to delete.

Codex stops adding files once the combined size reaches project_doc_max_bytes, which defaults to 32 KiB. You can raise it, or add fallback names, in ~/.codex/config.toml:

project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

Claude Code does not read AGENTS.local.md, AGENTS.override.md or anything under a .agents/ directory. If you rely on override files for Codex, Claude will not see them.

Setup 1: AGENTS.md as the single source, CLAUDE.md as an import

This is the safest default. It does not depend on the precedence rule above, and it still works in sessions that cannot read AGENTS.md directly. Create AGENTS.md with the shared rules, then add this CLAUDE.md beside it:

@AGENTS.md

## Claude Code

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

Claude reads the imported file first, then your Claude-specific notes. Relative imports resolve from the file containing them, and imports can nest up to four hops. Claude Code skips an AGENTS.md it has already loaded, so keeping the import never makes it read the file twice.

Setup 2: a symlink

If you have nothing Claude-specific to add, a symlink is enough:

ln -s AGENTS.md CLAUDE.md

Two constraints from the Claude Code docs. First, Claude's Edit and Write tools refuse to write through a symlink and will redirect to editing AGENTS.md instead. Second, on Windows a symlink needs Administrator rights or Developer Mode, and Git checks a committed symlink out as a plain one-line text file unless core.symlinks is enabled. If anyone on the team uses Windows, prefer the @AGENTS.md import.

Setup 3: let Claude read both files

If you want Claude to always load both, change the Project instructions setting. Type /config in a session and choose a value:

You can also set it in ~/.claude/settings.json, a --settings file or managed settings (project and local settings files are ignored for this):

{
  "pluginConfigs": {
    "cc-plugin-agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}

Before v2.1.285 the plugin ID was agents-md@builtin; use that ID if older versions also read your settings file. Because this is a personal or managed setting, it does not travel with the repository. Teammates who did not set it get the default. That is why the import in Setup 1 is more reliable for a shared repo.

What should go in the shared file?

Claude Code treats these files as context, not enforced configuration. Its docs say instructions work better when they are specific:

• "Use 2-space indentation" rather than "format code nicely"
• "Run npm test before committing" rather than "Test your changes"
• "API handlers live in src/api/handlers/" rather than "Keep files organized"

Good candidates for the shared file: build, test and lint commands, directory layout that is not obvious, naming conventions, and pitfalls that differ from the tool defaults. Leave out what the agent can read from the code itself, such as dependency lists.

Keep the length down. Claude Code warns that files over 200 lines consume more context and may reduce adherence. Codex has the 32 KiB cap noted above. Splitting into @ imports helps organisation but does not save context, since imported files load at launch.

Scope rules to parts of the repo

Both tools support layering by directory. In Codex, a nested AGENTS.md in services/payments/ is added after the root file when you work there. In Claude Code, a CLAUDE.md in a subdirectory loads on demand, when Claude opens a file in that subdirectory.

Claude Code also has .claude/rules/ with path scoping:

---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules

- All API endpoints must include input validation
- Use the standard error response format

Rules without paths load at launch. Rules with paths load when Claude reads, writes or edits a matching file. Codex does not read this folder (its documented discovery covers only the AGENTS.md names above), so keep anything that both tools need in AGENTS.md.

How do I check what actually loaded?

Do not assume. Check in each tool.

In Claude Code:

• Run /context and read the Memory files list, or /memory to see the paths. Both list an AGENTS.md that Claude read directly from v2.1.280; on older versions, ask Claude what its project instructions say.
• With no CLAUDE.md, an interactive session shows a line like no CLAUDE.md found; AGENTS.md loaded: <path>.
• Run claude --version to confirm v2.1.277 or later for direct AGENTS.md reading.
• Run /doctor prompt-audit (added in v2.1.283) to audit your CLAUDE.md files, skills, agents and commands for outdated prompting patterns. It proposes diffs and changes nothing until you ask.

In Codex, run from the directory you care about:

codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."

Codex should report the global file, the root AGENTS.md and any nested override in that directory. For a plain-text log, start it with codex -c log_dir=./.codex-log and read codex-tui.log in that folder. There is no cache to clear: restarting Codex in the target directory picks up changes.

Do not rely on instructions for hard rules

The Claude Code docs are explicit that CLAUDE.md content is context, and there is no guarantee of strict compliance. If something must happen every time, such as running a formatter after each edit, use a hook. To block an action regardless of what Claude decides, the docs point to a PreToolUse hook; settings such as permissions.deny are enforced by the client.

Migrating an existing setup

If you already have a workaround, the Claude Code docs say:

• A CLAUDE.md containing @AGENTS.md can stay.
• A CLAUDE.md that only says in words to go read AGENTS.md is unreliable, since Claude sees AGENTS.md only if it decides to open it. Delete it or replace that sentence with an import.
• A CLAUDE.md symlinked to AGENTS.md needs no change.
• A SessionStart hook that prints AGENTS.md should go, because it adds a second copy once Claude reads the file directly.

Running /init in Claude Code reads Cursor and Copilot rules, and with CLAUDE_CODE_NEW_INIT=1 set it also reads AGENTS.md. /import (v2.1.213 or later) appends a one-time copy of another agent's instruction files, such as AGENTS.md, to the matching CLAUDE.md.

Conclusion

Write your project rules once in AGENTS.md, add a CLAUDE.md that starts with @AGENTS.md, and keep both short and specific. Then verify with /context in Claude Code and a "list the instruction sources" prompt in Codex. When a rule must never be broken, move it out of prose and into a hook or permission setting.