Does Claude Code read AGENTS.md? CLAUDE.md vs AGENTS.md and .cursorrules

Yes. Claude Code v2.1.277 and later reads AGENTS.md as project instructions, but by default only when no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md exists in your working directory or above it. It doesn't list .cursorrules among the files it loads at session start; /init reads that file once when it generates a CLAUDE.md.

What Claude Code reads by default

Your repository hasClaude reads
AGENTS.md, no CLAUDE.md or CLAUDE.local.mdAGENTS.md
AGENTS.md and a CLAUDE.md or CLAUDE.local.mdThe CLAUDE.md files only
A CLAUDE.md containing @AGENTS.mdCLAUDE.md, with AGENTS.md included through the import

One file catches people out. Adding a CLAUDE.local.md for your own notes in a repo that relies on AGENTS.md stops Claude reading AGENTS.md for you, because the local file counts as a CLAUDE.md for this check.

When AGENTS.md is in use, Claude reads every AGENTS.md and .claude/AGENTS.md from your working directory and the folders above it at launch. A subfolder's AGENTS.md loads when Claude opens a file there and that subfolder has no CLAUDE.md of its own. AGENTS.local.md, AGENTS.override.md and anything under .agents/ are not read.

Change which files load

Type /config in a session and set Project instructions to one of these:

ValueWhat Claude reads
claude-md-or-agents-mdCLAUDE.md files, or AGENTS.md when there are none. The default.
claude-md-and-agents-mdBoth, with each folder's CLAUDE.md files first.
claude-mdCLAUDE.md files only.
managed-onlyYour organization's managed CLAUDE.md and auto memory at launch.

You can set the same value in ~/.claude/settings.json. Claude Code ignores this entry in project and local settings files:

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

Keep one file for every coding tool

If your project needs both files, make AGENTS.md the shared one and import it from a CLAUDE.md next to it. Claude reads the imported file first, then the lines below:

@AGENTS.md

## Claude Code

Use plan mode for changes under src/billing/.

With no Claude-specific lines, a symlink works too: ln -s AGENTS.md CLAUDE.md. Two limits apply. Claude's Edit and Write tools won't write through the link, so edits go to AGENTS.md. And on Windows, Git can check the link out as a plain text file, so use the import if anyone on the team works there.

More on the syntax in how to import files into CLAUDE.md.

Where AGENTS.md behaves differently

An AGENTS.md read through the setting differs from a CLAUDE.md in three ways:

  • InstructionsLoaded hooks don't fire for it.
  • Folders added with --add-dir don't load their AGENTS.md, even with CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD set.
  • An @path import outside your working directory loads only if you already approved external imports for the project. You get no prompt.

Bring in .cursorrules and other tools' files

Run /init. It reads these files and folds the relevant parts into the CLAUDE.md it generates:

  • Cursor: .cursor/rules/ or .cursorrules
  • Copilot: .github/copilot-instructions.md
  • With CLAUDE_CODE_NEW_INIT=1 set: AGENTS.md, .devin/rules/, .windsurf/rules/ or .windsurfrules, and .clinerules

/import codex, /import gemini and /import cursor carry over more: instruction files, MCP servers, commands, subagents and skills. Instruction files arrive as a one-time copy appended to the matching CLAUDE.md, so later changes to the original don't follow. Add --dry-run to preview. Importing from Cursor needs v2.1.265 or later.

Check which file loaded

  1. Run claude --version and confirm v2.1.277 or later.
  2. Start a session. If Claude picked up AGENTS.md you see a line like no CLAUDE.md found; AGENTS.md loaded: /path/to/AGENTS.md.
  3. Run /memory and look for the path in the list.

Rulebook, the Mac app we are building, works with CLAUDE.md files and doesn't read AGENTS.md. If you settle on CLAUDE.md, it shows each level side by side.

Questions

What is the difference between CLAUDE.md and AGENTS.md?
CLAUDE.md is the instruction file Claude Code looks for first. AGENTS.md is the file a repository sets up for other coding agents. Claude Code reads AGENTS.md as project instructions when no CLAUDE.md or CLAUDE.local.md exists in your working directory or above it.
Can Claude Code read CLAUDE.md and AGENTS.md together?
Yes. Type /config and set Project instructions to claude-md-and-agents-md. Claude reads each folder's CLAUDE.md files first and its AGENTS.md after them, and skips an AGENTS.md it has already loaded. Or put @AGENTS.md at the top of your CLAUDE.md.
Does Claude Code read .cursorrules?
The Claude Code docs don't list .cursorrules among the files it loads at session start. They list it as a source that /init reads when it generates a CLAUDE.md. /import cursor also copies Cursor configuration from your machine into Claude Code.
Why isn't Claude Code reading my AGENTS.md?
The usual cause is a CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or a folder above it. Claude reads that instead. Also check that you run v2.1.277 or later and that Project instructions isn't set to claude-md or managed-only.
Does ~/.claude/CLAUDE.md stop AGENTS.md from loading?
No. Your ~/.claude/CLAUDE.md, a managed CLAUDE.md and .claude/rules/ files don't count for that check. They keep loading alongside AGENTS.md.

Rulebook for Mac

Rulebook is a native Mac app we are building for these files. It shows every CLAUDE.md and settings.json level side by side, lets you drag a rule from one file to another, and edits permissions without hand-written JSON. See the features.

Rulebook is in development and not available yet.

Email us about the launch

Related guides