CLAUDE.md, AGENTS.md and Cursor rules: which file does what

Three conventions, one job, and they are not interchangeable. What each tool actually reads, where the file goes, and how to keep one set of instructions without maintaining three copies.

Checked against the tools’ own documentation on 17 August 2026.

Three files, one job, and they are not interchangeable. Put your project’s conventions in the wrong one and the tool you use every day will read nothing at all — silently, with no warning, while you wonder why it keeps ignoring instructions you can see on screen.

Here is what actually reads what.

CLAUDE.md is Claude Code’s, and only Claude Code’s

This is the one that surprises people. Claude Code reads CLAUDE.md. It does not read AGENTS.md. If your repository has an AGENTS.md and no CLAUDE.md, Claude Code starts every session knowing nothing you wrote.

What it does read, it reads thoroughly:

• It walks up the directory tree from where you launched it, picking up everyCLAUDE.md and CLAUDE.local.md on the way. They are concatenated, not overridden, ordered from the filesystem root down — so the file closest to where you are is read last.
• Files in subdirectories below you are not loaded at launch. They load when Claude reads a file in that directory.
• .claude/rules/ holds topic files. Give one a paths: list in its frontmatter and it only enters the context window when Claude touches a file matching the glob.

Aim for under 200 lines. The file is loaded into the context window at the start of every session and competes with your actual conversation for room — and, past a certain length, adherence drops. A long file is not a thorough one; it is a file the model skims.

AGENTS.md is the one everyone else agreed on

AGENTS.md is a plain markdown file at the repository root — a README written for a machine rather than a newcomer. It has no schema and no frontmatter. Its whole value is the list of tools that read it, which is now long enough that it is the sensible default for a repository whose contributors use different editors.

In a monorepo, put one in each package. Agents read the nearest file up the tree from whatever they are editing, so a package’s own conventions live with the package.

Cursor rules need frontmatter, or they are ignored

Cursor’s project rules live in .cursor/rules/ as .mdc files — markdown with a YAML block on top. The block is not decoration; it is what tells Cursor when the rule applies:

---
description: Project context and conventions
alwaysApply: true
---

# Project context
…

alwaysApply: true puts the rule in every session. Leave it false and Cursor decides from the description whether the rule is relevant, or attaches it automatically when you edit a file matching globs.

A plain .md file dropped into .cursor/rules/ without frontmatter is ignored. It sits there looking like configuration and does nothing, which is the most expensive kind of file to have in a repository.

Cursor also reads AGENTS.md from the repository root, including nested ones, as a simpler alternative to a rules directory. If you do not need per-glob scoping, that is one fewer convention to maintain.

The practical answer: write one, import it from the other

Do not maintain three copies. They drift, and a stale instruction is worse than a missing one because it gets followed.

Write AGENTS.md, since it is the file with the most readers. Then give Claude Code aCLAUDE.md that imports it:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

The import is expanded at session start, so Claude reads everything in AGENTS.md and then whatever you added below it. A symlink works too, if you have nothing Claude-specific to add:

ln -s AGENTS.md CLAUDE.md

On Windows, creating a symlink needs Administrator rights or Developer Mode. Use the@AGENTS.md import instead — it costs nothing and works everywhere.

What goes in it

Whatever you would otherwise re-explain. Build and test commands. Where things live. The convention that is not the framework default. The mistake the agent made twice.

What does not go in it is your product’s scope — what you are building, what you are deliberatelynot building, and how anyone can tell when a piece of it is done. That is a different document with a different job, and the context file is the wrong shape for it: it is loaded into every session forever, while scope changes with the project. Keep the conventions in the context file and the scope in a spec, and let the context file point at it.

How to write a spec a coding agent can build from covers the other half.