AGENTS.md vs CLAUDE.md: who reads which file

What is AGENTS.md used for?

It is an open format with no required fields and no frontmatter. The one rule that matters: the AGENTS.md closest to the file being edited wins, so a monorepo can keep one per package. An explicit request in chat overrides the file.

The format is stewarded by the Agentic AI Foundation under the Linux Foundation. agents.md lists 23 products, including Codex, Cursor, Gemini CLI, the GitHub Copilot coding agent, Windsurf, Zed, Aider, Devin and Junie. The site says AGENTS.md is “used by over 60k open-source projects” without saying how it counted. A GitHub code search by filename on 24 October 2026 returns 1,153,024 AGENTS.md files; those are files, not repos.

Which agents read AGENTS.md and which read CLAUDE.md?

AgentReadsDetailClaude CodeCLAUDE.md; AGENTS.md since v2.1.277AGENTS.md only if there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.mdCodexAGENTS.override.md, AGENTS.mdconcatenated from the git root down to the current folder, 32 KiB cap; CLAUDE.md only via project_doc_fallback_filenamesCursorAGENTS.md at root and in subfoldersnested files combine with parentsGitHub CopilotAGENTS.md; at the root also CLAUDE.md and GEMINI.mdcloud agent and CLI read all three, VS Code Chat only AGENTS.mdGemini CLIGEMINI.mdAGENTS.md only if you add it to context.fileNameOpenCodeAGENTS.mdfalls back to CLAUDE.mdZedfirst file from a list.rules, .cursorrules, …, AGENTS.md, CLAUDE.md, GEMINI.md: only the first match countsKiro, Windsurf (Devin Desktop), Cline, JunieAGENTS.mdeach also has its own rules format

The full matrix with paths is in the formats guide.

How Claude Code handles CLAUDE.md and AGENTS.md

CLAUDE.md exists at four levels: the managed organization file, personal ~/.claude/CLAUDE.md, project ./CLAUDE.md or ./.claude/CLAUDE.md, and local ./CLAUDE.local.md, which stays out of git. They do not override each other; they are concatenated from the filesystem root down to the working directory. CLAUDE.md files in subfolders load when Claude opens files there.

Since v2.1.277 Claude Code has a built-in AGENTS.md plugin. In the default mode it reads AGENTS.md only if neither CLAUDE.md, .claude/CLAUDE.md nor CLAUDE.local.md exists in the working directory or above. The catch is the last one: a personal CLAUDE.local.md also switches AGENTS.md off. The claude-md-and-agents-md mode loads both; change it under /config → Project instructions.

The older, still documented route is a bridge. One line in CLAUDE.md:

@AGENTS.md

The import expands the whole file. Nested imports go up to four levels deep.

How long should CLAUDE.md be?

Anthropic docs say to target under 200 lines per CLAUDE.md file. Imports do not save context: an imported file loads along with its parent.

You will often see “models reliably follow 150–200 instructions.” That is an estimate from the HumanLayer blog post “Writing a good CLAUDE.md” (25 November 2025), not a research finding. The post cites the IFScale paper (arXiv 2507.11538), but the number is not in its abstract: the paper tested up to 500 instructions, where the best models reached 68 % accuracy. HumanLayer keeps its own root CLAUDE.md under 60 lines.

Also worth knowing: CLAUDE.md is context, not enforced configuration. The docs recommend a PreToolUse hook for hard bans. A line saying “never touch prod” works until the first time the model decides otherwise.

What to put in AGENTS.md

Build, test and lint commands, exactly as they should be run.
Repo layout: where code and tests live, what is generated and must not be edited by hand.
Conventions the agent cannot infer from code: branch names, where migrations go.
Bans, backed by a hook when breaking them is expensive.

Skip what the agent can already see in the code, and skip wishes like “write clean code.” Every line goes into the context of every request.

No CLAUDE.md yet? /init in Claude Code drafts one from your codebase. It is almost always worth cutting in half.

AGENTS.md or CLAUDE.md: which should you use?

Solo and only on Claude Code: CLAUDE.md is enough. With two or more agents on the team (Claude Code and Cursor, Claude Code and Codex), keep a shared AGENTS.md as the source of truth and a CLAUDE.md that holds one line, @AGENTS.md, plus anything Claude-specific. That way the rules do not drift apart.

For five agents at once, generators such as rulesync, ruler and block/ai-rules write one source into each native format. They are covered in the formats guide. Real rules files to learn from are in the rules section.

FAQ

What is agents.md used for?

It gives many AI coding agents one shared file of project instructions: Codex, Cursor, Copilot, OpenCode, Zed and others read it. It usually holds build and test commands, repo layout and conventions.

Does Claude Code read AGENTS.md?

Since version 2.1.277, yes, but by default only when the project has no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md. Otherwise add the line @AGENTS.md to CLAUDE.md or switch to the claude-md-and-agents-md mode.

Where does the CLAUDE.md file go?

At the project root (./CLAUDE.md or ./.claude/CLAUDE.md); personal instructions go in ~/.claude/CLAUDE.md. Local notes you do not commit go in CLAUDE.local.md.

How do I create a CLAUDE.md file?

Run /init in Claude Code to draft one from your codebase, then trim it to what the agent cannot learn from the code. Anthropic suggests staying under 200 lines.

What is CLAUDE.md used for?

It is project memory for Claude Code: commands, conventions and context loaded at the start of every session. It guides the model but does not enforce anything; use hooks for hard rules.

AGENTS.md vs CLAUDE.md: what they are and which one to use