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

> Use one AGENTS.md for Claude Code and Codex: how each tool finds the file, the import and symlink options, size limits, and how to check what loaded.

19 October 2026 · Technical · How-to · 7 min read · https://bridge-terminal.com/atlas/blog/agents-md-claude-md-one-instruction-file/

## The short version

- Codex reads AGENTS.md; Claude Code (v2.1.277 or later) reads CLAUDE.md first and falls back to AGENTS.md only when no CLAUDE.md or CLAUDE.local.md exists in the working directory or above it.
- The safest shared setup is one AGENTS.md plus a CLAUDE.md that starts with @AGENTS.md and adds Claude-only notes below.
- Claude Code treats CLAUDE.md as context, not enforced configuration, so anything that must always happen belongs in a hook or permission rule.
- Keep files short: Claude Code recommends under 200 lines per CLAUDE.md, and Codex stops adding files at 32 KiB by default.
- Verify what loaded instead of guessing: /context or /memory in Claude Code, and a 'list the instruction sources' prompt or a log file in Codex.

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`.

| Repository has | Claude Code reads |
| :- | :- |
| `AGENTS.md` only | `AGENTS.md` |
| `AGENTS.md` and `CLAUDE.md` | `CLAUDE.md` only |
| `CLAUDE.md` that imports `AGENTS.md` | `CLAUDE.md`, with `AGENTS.md` through the import |

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`:

```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:

```markdown
@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:

```bash
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:

| Value | What Claude reads |
| :- | :- |
| `claude-md-or-agents-md` | Default: `CLAUDE.md`, or `AGENTS.md` if there is no `CLAUDE.md` or `CLAUDE.local.md` on the path |
| `claude-md-and-agents-md` | Both, with each directory's `CLAUDE.md` first |
| `claude-md` | `CLAUDE.md` only |
| `managed-only` | Only the organisation's managed `CLAUDE.md` and auto memory at launch |

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

```json
{
  "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:

```markdown
---
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:

```bash
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.

## Questions people ask

### Does Claude Code read AGENTS.md?

Yes, from v2.1.277. By default it reads 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. Otherwise it reads the CLAUDE.md files only.

### How do I make Claude Code and Codex share one instruction file?

Keep the rules in AGENTS.md and create a CLAUDE.md whose first line is @AGENTS.md, with any Claude-only notes below. A symlink from CLAUDE.md to AGENTS.md also works, but it is awkward on Windows and Claude's edit tools will not write through it.

### What is the size limit for AGENTS.md in Codex?

Codex's project_doc_max_bytes defaults to 32 KiB across the combined files. Once that is reached it stops adding files, so raise the limit in config.toml or split instructions into nested directories.

### How can I check which instruction files were loaded?

In Claude Code run /context or /memory. In Codex, run a prompt asking it to list the instruction sources it loaded, from the directory you are working in, or write a log with -c log_dir.

### Will Claude Code always follow what CLAUDE.md or AGENTS.md says?

No. Claude Code's docs say these files are context, not enforced configuration. For rules that must always apply, use hooks or permission rules.

## About Atlas: One set of rules for a team of agents

Instruction files only help if every agent actually loads them, and conflicting or oversized files quietly weaken them. Atlas runs each engineer as its own Claude Code session with a written role, but its published facts do not describe checking a project's AGENTS.md or CLAUDE.md files. — https://bridge-terminal.com/atlas/

## Sources

- [How Claude remembers your project (Claude Code docs)](https://code.claude.com/docs/en/memory)
- [Custom instructions with AGENTS.md (Codex docs)](https://learn.chatgpt.com/docs/agent-configuration/agents-md)
- [Claude Code v2.1.283 release summary](https://www.havoptic.com/r/claude-code-2.1.283)

_Researched and drafted with Claude, then checked against the sources above. Atlas is an independent product, not affiliated with Anthropic or OpenAI._