One Rule File for Codex and Claude Code

When a repository uses both Codex and Claude Code, the first configuration problem is usually not what the rules should say. It is where those rules should live.

Codex looks for AGENTS.md. Claude Code looks for CLAUDE.md. Copying the same instructions into both files feels convenient, but the two copies will eventually drift: one gets a new test command while the other keeps the old one; one adds a safety constraint while the other never sees it.

The cleaner setup is to keep one source of truth:

Codex ─────────→ AGENTS.md
Claude Code ───→ CLAUDE.md ──imports──→ AGENTS.md

AGENTS.md owns the project rules. CLAUDE.md is only the adapter that exposes those rules to Claude Code.

The minimal setup

Put the actual shared instructions in AGENTS.md:

# Project Guidelines

- Run tests before committing.
- Ask before adding dependencies.
- Keep changes scoped to the current task.

Then make CLAUDE.md a one-line bridge:

@AGENTS.md

Codex reads AGENTS.md directly. Claude Code loads CLAUDE.md and expands the imported file.

This raises an obvious question: if Claude Code can import AGENTS.md, can Codex do the reverse by placing @CLAUDE.md inside AGENTS.md?

Do not build your configuration around that assumption. The two products use different instruction-loading models.

Claude Code: imports inside `CLAUDE.md`

Claude Code officially supports @path/to/file references inside CLAUDE.md. Imported files are expanded and loaded into the session together with the file that referenced them.

For example:

@AGENTS.md
@docs/git-workflow.md

The important details are:

Relative paths resolve from the file containing the import, not from the shell’s working directory.
Both relative and absolute paths are supported.
Imported files may import other files, up to five recursive hops.
Claude Code asks for approval the first time a project imports files from outside the project.
Imports are eager, not lazy: their contents enter the context at startup.

That last point changes how you should think about modularization. Splitting a 300-line rule file into three imported files may make maintenance easier, but it does not reduce startup context. Claude Code still loads all three.

If the goal is organization, imports are useful. If the goal is lower context usage, move narrowly scoped guidance into path-specific rules or an on-demand Skill instead of importing everything at launch.

Codex: an instruction discovery chain

Codex documents a discovery chain rather than a Markdown-level include syntax. At startup, it walks from the project root toward the current working directory and checks each directory in this order:

AGENTS.override.md
AGENTS.md
Any names configured in project_doc_fallback_filenames

Codex includes at most one instruction file per directory. If AGENTS.override.md exists, the regular AGENTS.md at that level is not also loaded. If AGENTS.md exists, a fallback such as CLAUDE.md is not merged beside it.

Files discovered at different directory levels are concatenated from the root down. More specific guidance appears later in the combined instructions, which makes nested files useful for package- or directory-specific rules.

The discovery chain also has a size limit. project_doc_max_bytes defaults to 32,768 bytes. If the combined project guidance exceeds that limit, later content can be truncated. Keeping the always-on rules concise is usually better than raising the limit immediately.

A fallback filename is not an import

Codex can treat another filename as project guidance when the standard files are missing:

# ~/.codex/config.toml
project_doc_fallback_filenames = ["CLAUDE.md"]

The key word is fallback.

This setting means: “If this directory does not contain AGENTS.override.md or AGENTS.md, try CLAUDE.md.” It is not a merge or include directive, and it does not teach Codex how to expand Claude Code’s @AGENTS.md syntax.

In a directory that already contains AGENTS.md, adding CLAUDE.md to the fallback list does not make Codex load both files.

Three similar-looking features that do different jobs

1. Claude Code instruction imports

@AGENTS.md

Location: inside CLAUDE.md.

Purpose: expand durable project instructions when the session loads.

2. File mentions in a prompt

Mentioning or attaching a file in a Codex or Claude Code prompt gives the current task extra context. Codex CLI also provides /mention for attaching a file.

Purpose: tell the agent which file matters for this task. It does not create a persistent instruction relationship.

3. Codex fallback filenames

project_doc_fallback_filenames = ["CLAUDE.md"]

Location: Codex configuration.

Purpose: discover project guidance under an alternate filename when the standard files are absent.

Once these three mechanisms are separated, the configuration becomes much easier to reason about.

Why duplicate rule files are a poor default

Maintaining separate AGENTS.md and CLAUDE.md files is valid when the two agents genuinely need different instructions. It is a poor default when both files are meant to say the same thing.

Duplicated rules create three predictable problems:

Updates land in only one copy.
Conflicting instructions make agents behave differently in the same repository.
Reviewers cannot tell which file is authoritative.

A clearer boundary is:

Put cross-agent repository conventions in AGENTS.md.
Import AGENTS.md from CLAUDE.md.
Add a short Claude-specific section after the import only when a behavior is truly Claude-specific.

If strict single-source maintenance matters more than tool-specific customization, keep CLAUDE.md as a pure bridge.

Common mistakes

Putting `@CLAUDE.md` in `AGENTS.md`

Codex does not document this as an automatic expansion mechanism. The model might occasionally decide to open the referenced file, but that is agent behavior, not a reliable instruction loader.

Expecting fallback files to merge

Fallbacks are considered only after higher-priority names are absent. Codex selects at most one instruction file per directory level.

Treating imports as a context optimization

Regular Claude Code imports load at startup. They improve organization, not token usage.

Copying the same rules into both files

It is quick on day one and expensive later. Unless the tools need different behavior, keep one authoritative copy.

Verify what actually loaded

In Claude Code, run:

/memory

This shows the CLAUDE.md, rules, and memory files in the session. Then use:

/context

to inspect how much context is occupied by instructions, Skills, MCP tools, and conversation history. If the imported AGENTS.md is missing, check the relative path and any external-import approval.

For Codex CLI, ask it to report the active instruction sources from the repository root:

codex --ask-for-approval never "Summarize the current instructions and list their source files."

When nested rules are involved, launch from the relevant subdirectory and confirm the root-to-current-directory order.

The decision rule

Use this checklist:

Supporting both Codex and Claude Code? Keep shared rules in AGENTS.md.
Connecting Claude Code? Import AGENTS.md from CLAUDE.md.
Connecting Codex? Let Codex discover AGENTS.md; do not rely on @ imports in its body.
Supporting a repository with no AGENTS.md? Consider a configured fallback filename.

The resulting architecture stays simple:

Codex ─────────→ AGENTS.md
Claude Code ───→ CLAUDE.md ──imports──→ AGENTS.md

One source of truth, two officially supported loading paths, and far less room for configuration drift.