Amaresh Pelleti

Posted on Nov 12 Originally published at devtoolhub.com

CLAUDE.md vs AGENTS.md: Which Claude Code Reads

#claudecode #ai #productivity #devtools

Originally published on DevToolHub.

Claude Code reads CLAUDE.md first and falls back to AGENTS.md only when no CLAUDE.md exists. That one rule settles most claude.md vs agents.md questions. If you also use Codex, Cursor or Copilot, put the shared rules in AGENTS.md and add a CLAUDE.md that imports it with @AGENTS.md.

I tested this on Claude Code 2.1.322. I put a unique codeword in each file, ran claude -p in throwaway folders, and asked it to list every codeword in its loaded instructions. The results match the docs, with one catch that most guides skip: a CLAUDE.local.md quietly switches AGENTS.md off.

What Is the Difference Between CLAUDE.md vs AGENTS.md?

CLAUDE.md is Claude Code's own instruction file. AGENTS.md is an open, plain-Markdown format that many coding tools read, and it has no required fields. In practice, both hold the same kind of content: build commands, code style and project rules.

	`CLAUDE.md`	`AGENTS.md`
Read by	Claude Code	Codex, Cursor, Windsurf, Copilot's coding agent and others; Claude Code reads it from v2.1.277
Format	Markdown with `@path` imports	Plain Markdown, any headings
Personal, uncommitted file	`CLAUDE.local.md`	None
Path-scoped rules	`.claude/rules/`	Claude-only feature, not part of the format
`InstructionsLoaded` hooks	Fire	Don't fire when Claude reads it through the setting

The tool list comes from the AGENTS.md site, which also says Aider and Gemini CLI need a config setting to read it. The Claude Code columns come from the memory docs.

CLAUDE.md vs AGENTS.md: Which Does Claude Code Load When Both Exist?

It loads CLAUDE.md and ignores AGENTS.md. By default, Claude reads AGENTS.md only when no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md exists in your working directory or any directory above it.

Here is what I saw. Each folder held files with different codewords, so the right column shows what Claude reported.

Files in the folder	Codewords Claude reported
`AGENTS.md` only	The `AGENTS.md` codeword
`AGENTS.md` and `CLAUDE.md`	The `CLAUDE.md` codeword only
`CLAUDE.md` containing `@AGENTS.md`	Both codewords
`AGENTS.md` and `CLAUDE.local.md`	The `CLAUDE.local.md` codeword only
`CLAUDE.md` as a symlink to `AGENTS.md`	One codeword, loaded once

The fourth row is the catch. CLAUDE.local.md counts as a CLAUDE.md for this check, so adding one to keep personal notes stops Claude from reading your AGENTS.md. Your ~/.claude/CLAUDE.md, a managed CLAUDE.md and .claude/rules/ files don't count, so they keep loading next to AGENTS.md.

In an interactive session you can confirm it. When AGENTS.md is the file in use, Claude shows a line like no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md.

How Do You Share One CLAUDE.md vs AGENTS.md Setup Across Tools?

Pick one source of truth, then point the other file at it. You have four options, and the docs cover all of them.

1. Use AGENTS.md alone. On Claude Code v2.1.277 or later this works with no extra setup. Before that version, or if the built-in plugin is disabled, Claude reads CLAUDE.md files only.

2. Import it from CLAUDE.md. Create a CLAUDE.md that starts with the import, then add Claude-only notes below it:

@AGENTS.md

## Claude Code
- Use plan mode for changes that touch more than three files.

I tested this, and both codewords loaded. The docs say Claude never reads AGENTS.md twice when a CLAUDE.md imports it. It also works on older versions.

3. Symlink one to the other. This creates the link in the current folder only, and ln fails if CLAUDE.md already exists:

ln -s AGENTS.md CLAUDE.md

In my test the content loaded once. But you can't keep Claude-only notes, because both names are the same file.

4. Load both on purpose. Open /config, find Project instructions, and choose claude-md-and-agents-md. I did not test this setting.

I use option 2. It works on every version, other tools see a clean AGENTS.md, and the Claude-specific notes stay out of their way.

How Do Subdirectory CLAUDE.md Files Load?

Claude loads CLAUDE.md from your working directory and every directory above it at launch. A CLAUDE.md in a subdirectory waits until Claude reads a file in that folder.

I checked this with a root file and a sub/CLAUDE.md. At first, Claude reported only the root codeword. Then I told it to read sub/notes.txt, and it reported both.

This matters in a monorepo, because rules in a team's folder cost nothing until Claude works there. If an ancestor file from another team gets in your way, the claudeMdExcludes setting skips it by path or glob pattern.

What Should Go in a CLAUDE.md or AGENTS.md File?

Write instructions you can verify, and keep the file under 200 lines. Longer files use more context, so Claude follows them less well. Imports organise a long file but don't shrink it, because imported files load together with the file that imports them.

Compare these pairs from the docs. The concrete version is the one to write:

"Use 2-space indentation" instead of "Format code properly"
"Run npm test before committing" instead of "Test your changes"
"API handlers live in src/api/handlers/" instead of "Keep files organized"

A short starting point looks like this:

# Project notes

## Commands
- Install: `npm ci`
- Test one file: `npx vitest run path/to/file.test.ts`
- Lint before committing: `npm run lint`

## Conventions
- API handlers live in `src/api/handlers/`.
- Use 2-space indentation.

## Don't
- Don't edit files under `generated/`. Run `npm run codegen` instead.

To start, run /init and Claude writes a first draft from your codebase. Four more points are worth knowing:

It's context, not enforcement. Claude can still ignore a line. To block an action for certain, use a PreToolUse hook or a permissions.deny rule.

Comments are free. Block-level HTML comments are stripped before the file reaches Claude, so you can leave maintainer notes.

Long procedures belong elsewhere. Move a multi-step workflow into a Skill, as in our Agent Skills guide.

Audit the files. /doctor prompt-audit (v2.1.283 or later) flags outdated or conflicting instructions and proposes edits. I did not run it.

For installation and first-run steps, see the Claude Code setup guide and the quick-start guide. Claude Code also runs in the browser, which our Claude Code on the web guide covers.

CLAUDE.md vs AGENTS.md: Which Should You Use?

Use CLAUDE.md if Claude Code is your only agent. Use AGENTS.md plus a one-line CLAUDE.md import if your team mixes tools. Don't maintain two copies of the same rules.

Only Claude Code: CLAUDE.md. You also get CLAUDE.local.md and .claude/rules/.
Two or more agents: AGENTS.md for the shared rules, and a CLAUDE.md containing @AGENTS.md for Claude's extras.
You already have an AGENTS.md and Claude Code 2.1.277 or later: do nothing. Just don't add a CLAUDE.local.md unless you change the Project instructions setting.
An old workaround: a CLAUDE.md that only says "read AGENTS.md" in words is weaker than an import, because Claude has to decide to open the file. Replace the sentence with @AGENTS.md.

What I Did Not Test

I tested file loading on one version, Claude Code 2.1.322, with claude -p. Beyond that, I did not check how well Claude follows the instructions once they load. Other tools reading AGENTS.md are also untested, so that list comes from the AGENTS.md site. I skipped path-scoped rules, managed policy files, /init output, auto memory, the claude-md-and-agents-md setting and any version before 2.1.277.

Frequently Asked Questions

Q: Does Claude Code read AGENTS.md?
A: Yes, from v2.1.277, but only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or above it. If any of those exist, Claude reads them and skips AGENTS.md unless you import it or change the Project instructions setting.

Q: Can I symlink CLAUDE.md to AGENTS.md?
A: Yes. In my test, Claude loaded the content once. An @AGENTS.md import is usually better, because it lets you add Claude-only notes in the CLAUDE.md file.

Q: Where does a CLAUDE.md file go?
A: For a project, use ./CLAUDE.md or ./.claude/CLAUDE.md. For personal settings across all projects, use ~/.claude/CLAUDE.md. For personal notes in one project, use ./CLAUDE.local.md and add it to .gitignore.

Q: How long should it be?
A: Under 200 lines per file. Past that, Claude follows it less reliably, so move part-of-the-codebase rules into .claude/rules/ or a subdirectory CLAUDE.md.

Q: Will Claude always follow it?
A: No. The docs call these files context, not enforced configuration. Use a hook or a permission rule for anything that must never happen.

Quick Summary:

Claude Code loads CLAUDE.md and ignores AGENTS.md when both exist
With only AGENTS.md, Claude Code 2.1.277 or later reads it automatically
A CLAUDE.local.md counts as a CLAUDE.md and turns AGENTS.md off
@AGENTS.md inside CLAUDE.md loads both, and a symlink loads the content once
Subdirectory files load only after Claude reads a file in that folder
Keep the file under 200 lines and use hooks for rules that must hold

The claude.md vs agents.md answer for your repo takes a minute to check: if it has an AGENTS.md and a CLAUDE.local.md, Claude isn't reading the first one. For structured practice with these tools, see the free Anthropic Academy courses.

DEV Community