AGENTS.md vs CLAUDE.md: Differences and How to Use Both

If you use more than one AI coding tool on a project, you'll run into two files that seem to do the same job: AGENTS.md and CLAUDE.md. They do — mostly. Here's how they relate and how to avoid maintaining both.

What each file is

Both are plain Markdown files in your project that tell an AI coding agent how your project works: how to build and test it, the conventions to follow, what not to touch.

AGENTS.md is a tool-neutral convention. OpenAI Codex, Cursor, GitHub Copilot's agent, Gemini-based tools and many others read it. The idea is one file every agent understands.
CLAUDE.md is Claude Code's own instruction file, with extra features: personal and organisation-level versions, @path imports, and path-scoped rules in .claude/rules/. (Claude Code memory explained)

Does Claude Code read AGENTS.md?

Yes — recent versions of Claude Code (v2.1.277 and later) read AGENTS.md directly. But there's a rule that surprises people:

Your repo has	Claude Code reads
AGENTS.md only	AGENTS.md
AGENTS.md and a CLAUDE.md (or CLAUDE.local.md) in this folder or above	CLAUDE.md only
A CLAUDE.md that imports AGENTS.md	Both, through the import

So the moment someone adds a CLAUDE.md, Claude stops reading your AGENTS.md. That includes a personal CLAUDE.local.md — which is a common way to break it without noticing.

Your global ~/.claude/CLAUDE.md doesn't count for this check; only files in the project path do.

You can change the behaviour in /config under Project instructions — for example claude-md-and-agents-md to always read both.

The setup that works everywhere

Keep AGENTS.md as the single source of truth, and make CLAUDE.md a one-line pointer to it plus anything Claude-specific:

@AGENTS.md

## Claude Code only
- Use plan mode for changes under src/billing/

The @AGENTS.md line imports the file's contents, so Claude reads it every session regardless of version or setting. Other tools ignore CLAUDE.md and read AGENTS.md directly. One file to maintain, every tool covered.

You could also symlink CLAUDE.md → AGENTS.md, but avoid it if anyone uses Windows: Git often checks symlinks out as tiny text files there, and the instructions silently vanish. The import works on every platform.

What to put in the shared file

What makes these files useful is the same regardless of the name:

Commands: install, dev, test, lint, build
Layout: only the non-obvious parts
Rules: "never edit generated files", "validate input with Zod"
Gotchas: "tests need Postgres on port 5433"

Keep it short — under 200 lines — and make each rule something you could check. Tool-specific tricks go below the import in CLAUDE.md, or in each tool's own config.

Checking which file loaded

In Claude Code, run /memory or /context. If your AGENTS.md is listed, Claude read it. If only a CLAUDE.md shows up, look for a stray CLAUDE.md or CLAUDE.local.md in the project path.

Moving from one to the other

Have only CLAUDE.md, want to support other tools? Rename it to AGENTS.md, move Claude-only parts into a new CLAUDE.md that starts with @AGENTS.md.
Have AGENTS.md from another tool, starting with Claude Code? Do nothing — Claude reads it. Add a CLAUDE.md with @AGENTS.md only if you need Claude-specific lines or a personal local file.
Coming from Cursor or Copilot rules? Run /init; it reads .cursor/rules/ and .github/copilot-instructions.md and folds them in. (Claude Code /init)

The summary

AGENTS.md = shared file for any agent. CLAUDE.md = Claude Code's file.
Claude Code reads AGENTS.md only if no CLAUDE.md is in the project path.
Best setup: AGENTS.md holds everything; CLAUDE.md is @AGENTS.md plus Claude-only extras.
Check with /memory or /context.

EasySpawn runs Claude Code on a persistent server where your instruction files, project and running app stay in one place between sessions. See how it works or join the waitlist.

AGENTS.md vs CLAUDE.md: Which One Do You Need?