# CLAUDE.md vs AGENTS.md: one rules file for Claude Code and Codex *Originally published at [https://rayastats.com/en/blog/claude-md-vs-agents-md](https://rayastats.com/en/blog/claude-md-vs-agents-md)* 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](https://code.claude.com/docs/en/memory) and the [Codex AGENTS.md guide](https://learn.chatgpt.com/docs/agent-configuration/agents-md) 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](https://rayastats.com/en/two-engines-kit), `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.