CLAUDE.md vs AGENTS.md: What Claude Code Actually Reads

Published October 2, 2026 · 11 min read · by the CSS DNA team

Quick answer: CLAUDE.md is Claude Code’s instruction file. AGENTS.md is the shared file that Codex, Cursor and GitHub Copilot’s agents read. Since v2.1.277 (September 18, 2026), Claude Code also reads AGENTS.md, but by default only when there is no CLAUDE.md or CLAUDE.local.md in your working directory or any directory above it. To keep one source of truth, write AGENTS.md and put a one-line @AGENTS.md import in CLAUDE.md.

Most repositories that use more than one coding agent end up with two or three instruction files saying nearly the same thing, slowly drifting apart. The fix is to know exactly which file each tool loads, in what order, and which one wins. All of that changed for Claude Code two weeks ago, so a lot of what you will read elsewhere is now stale.

The correction: Claude Code reads AGENTS.md now, with a catch

Plenty of guides still say Claude Code ignores AGENTS.md and that you need a symlink or a SessionStart hook to make it pay attention. That stopped being true with v2.1.277, which the Claude Code changelog dates to September 18, 2026: “in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead.” Version 2.1.281 (September 23) extended that to Amazon Bedrock, Google Vertex AI, Microsoft Foundry, LLM gateways and sessions with telemetry disabled.

The catch is in the word instead. According to the official memory docs, three files count as “you already have a CLAUDE.md”: CLAUDE.md, .claude/CLAUDE.md and CLAUDE.local.md, in your working directory or any directory above it. If any of them exists, Claude reads your CLAUDE.md files and skips AGENTS.md entirely.

The behavior is controlled by a setting called Project instructions in /config, with four values. The default is claude-md-or-agents-md, which is the “one or the other” rule above. We cover all four further down.

Which file does each agent read?

Each row below comes from that tool’s own documentation, not from a compatibility chart. Where the docs are silent, the table says so rather than guessing.

Two details in that table are easy to miss. Codex never reads CLAUDE.md unless you add it to project_doc_fallback_filenames in ~/.codex/config.toml, and it stops adding files once their combined size reaches project_doc_max_bytes, 32 KiB by default. Claude Code, for its part, does not read AGENTS.override.md, AGENTS.local.md, or anything under an .agents/ directory, so Codex overrides stay Codex-only.

How Claude Code orders its instruction files

Claude Code loads instruction files from four scopes, broadest first. Nothing overrides anything: every file found is concatenated into context, and later text simply reads as more specific.

Within the directory tree, Claude Code walks from your working directory up to the filesystem root and loads every CLAUDE.md and CLAUDE.local.md it finds, ordered root first. Start a session in foo/bar/ and foo/CLAUDE.md lands in context before foo/bar/CLAUDE.md. In each directory, CLAUDE.local.md comes after CLAUDE.md, so your personal notes are the last thing Claude reads at that level.

Files below your working directory behave differently. A packages/web/CLAUDE.md doesn’t load at launch; it’s pulled in the first time Claude reads a file in packages/web/. That’s why a monorepo with per-package instructions can look like it’s ignoring them in the first few turns.

Because everything is concatenated, contradictions are your problem. The docs are blunt about it: if two instructions conflict, “Claude may pick one arbitrarily.” They also suggest keeping each file under 200 lines, and Claude Code skips any single file over 4 MiB.

For instructions that only matter to some files, use .claude/rules/. A rule file with paths frontmatter loads only when Claude reads a matching file:

---
paths:
  - "src/components/**/*.tsx"
  - "src/styles/**/*.css"
---

# UI rules
- Colors come from tokens in src/styles/tokens.css. No raw hex.

The Project instructions setting

Open /config in a session and look for Project instructions. If it isn’t there, your session can’t load AGENTS.md at all: you’re on a version before 2.1.277, you disabled the built-in agents-md plugin, or it’s your first session right after upgrading.

You can also set it in a settings file, under the built-in plugin’s ID. Claude Code honors this in ~/.claude/settings.json, a --settings file or managed settings, and ignores it in project and local settings, so you can’t force it on teammates from the repo:

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

@imports: how one file pulls in another

Both CLAUDE.md and an AGENTS.md that Claude reads directly can import other files with @path. Imported files are expanded into context at launch, next to the file that references them.

See @README.md for the project overview and @package.json for scripts.

# Design system
@docs/DESIGN.md

# Personal, shared across worktrees
@~/.claude/my-project-instructions.md

The rules, from the docs:

• Relative paths resolve from the file containing the import, not from your working directory.
• Imports can nest, up to four hops deep.
• An @path inside backticks or a fenced code block is left alone, which is how you mention a path without importing it.
• Paths with spaces need a backslash before each space. A quoted path isn’t imported at all.
• The first time a project file imports something outside the working directory, Claude Code asks you to approve it. Decline, and those imports stay off.

One thing imports don’t do is save context. An imported file loads at launch just like the file that imports it, so splitting a 600-line CLAUDE.md into six imports helps you, not the model.

Keeping one source of truth

If your team uses Claude Code alongside Codex, Cursor or Copilot, make AGENTS.md the canonical file, because it’s the one all of them read. Then pick one of three ways to hand it to Claude Code.

Option 1: AGENTS.md alone

On v2.1.277 or later with the default setting, this just works, as long as nobody adds a CLAUDE.md or CLAUDE.local.md. It’s the most fragile option for exactly that reason.

Option 2: CLAUDE.md that imports AGENTS.md (recommended)

@AGENTS.md

## Claude Code only

Use plan mode for changes under src/billing/.

Claude reads the imported file first, then the Claude-specific lines below it. This works in every session, including ones that can’t load AGENTS.md directly, and the docs confirm the import never causes a second copy under any Project instructions value. Personal CLAUDE.local.md files are safe here, since you aren’t relying on the fallback.

Option 3: a symlink

ln -s AGENTS.md CLAUDE.md

Fine if you have nothing Claude-specific to add, with two caveats from the docs. Claude’s Edit and Write tools refuse to write through a symlink, so it gets redirected to edit AGENTS.md. And on Windows, Git checks out a committed symlink as a plain text file unless core.symlinks is enabled, leaving that teammate with a one-line CLAUDE.md that says AGENTS.md. If anyone on the team uses Windows, use the import.

If you set up a workaround before September, the docs say what to do with it. Keep an @AGENTS.md import. Replace a sentence like “read AGENTS.md first” with a real import, because a sentence only works if Claude decides to open the file. Delete a SessionStart hook that prints AGENTS.md, or you’ll load it twice.

What to put in it for UI work

The general advice in the docs applies: facts Claude should hold in every session, like build commands, conventions, project layout and “always do X” rules. Multi-step procedures belong in a skill; folder-specific rules belong in .claude/rules/.

For front-end work, the instruction file’s most useful job is to stop the agent from inventing a design system. Without one in context, a model falls back to the median of its training data, which is how you get the same indigo three-card page from every tool. A short UI section that points at real values does more than a page of adjectives:

# AGENTS.md

## Commands
- pnpm dev / pnpm test / pnpm lint

## UI
- Design tokens live in DESIGN.md and src/styles/tokens.css. Read DESIGN.md before
  writing or restyling any component.
- Never use a raw hex, px font size or spacing value that isn't a token.
- Type scale: use the --step-* custom properties only.
- Body text must meet 4.5:1 contrast against its background.
- Reuse components from src/components/ui before creating new ones.

Note that this example asks the agent to read DESIGN.md rather than importing it. A full token file can run to hundreds of lines, and an @DESIGN.md import would load all of it into every session, including the ones where you’re fixing a database migration. Our guide to writing a DESIGN.md for AI coding agents covers what goes in that file and how to keep it compact enough to import if you’d rather. In Claude Code, a design-system skill with paths set to your UI files is the tidier middle ground.

Getting the actual values is the tedious part. Typing a palette, a type scale and a spacing scale into Markdown by hand, from DevTools, one computed style at a time, is where most teams give up and leave the agent to guess.

How to check what actually loaded

Don’t trust the file tree; ask each tool.

• In Claude Code, run /context and look under Memory files, or /memory to list and open every file. When AGENTS.md loads through the fallback, an interactive session prints a line like no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md.
• For Codex, its docs suggest codex --ask-for-approval never "Summarize the current instructions." from the repo root; it should echo global and project guidance in precedence order.
• In Gemini CLI, /memory show prints the full concatenated context; the footer shows how many context files loaded.

If Claude Code isn’t picking up your AGENTS.md, the docs give this checklist, in order:

1. Look for a CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or any parent, other than ~/.claude/CLAUDE.md. One of those wins under the default setting.
2. Run claude --version and confirm 2.1.277 or later (2.1.281 or later on Bedrock, Vertex AI, Foundry or with telemetry off).
3. Open /config and check Project instructions isn’t claude-md or managed-only.

One debugging gotcha: the InstructionsLoaded hook, handy for logging which files load and why, doesn’t fire for an AGENTS.md read through the setting. It does fire for one that a CLAUDE.md imports or symlinks to.