AGENTS.md vs CLAUDE.md Explained

Problem: You open a repo that has both an AGENTS.md and a CLAUDE.md. They look similar. They say similar things. You're not sure which one Claude Code reads, which one the other tools read, or why two files exist at all.

Quick Win: Claude Code reads CLAUDE.md. Every other major AI tool reads AGENTS.md. If you only use Claude Code, you only need CLAUDE.md. If your team uses multiple tools, one symlink makes both tools read the same file:

ln -s CLAUDE.md AGENTS.md

One source of truth. No duplication.

What AGENTS.md Actually Is

AGENTS.md is a cross-tool standard published by the Linux Foundation and the Agent Interoperability Initiative Foundation (AAIF). The goal is a single context file that any AI coding tool can read when it opens your repo.

As of April 2026, 18+ tools support it. OpenAI Codex, Gemini CLI, Devin, Cursor, Windsurf, Continue, Amp, Warp, and Goose all read AGENTS.md. It's active in over 60,000 GitHub projects.

The AAIF spec defines a schema for the file: fields like allowed_tools, disallowed_tools, agent_instructions, output_format, and environment. Each tool reads the fields it understands and skips the ones it doesn't.

Claude Code ignores those schema fields entirely. It has its own permission system inside settings.json. When it picks up AGENTS.md content (via import), it reads the prose instructions and disregards the structured fields.

What CLAUDE.md Actually Is

CLAUDE.md is Claude Code's native context file. Every session starts by loading it before the first token of conversation.

The file isn't documentation for Claude to read. It's the operating parameters for how Claude runs. Put your workflows, routing logic, quality rules, and delegation patterns here. Project docs, stack notes, and technology specifics belong in skills that load on demand.

Target size: 200-500 lines for a solo setup. 50-100 lines for a shared team file where every contributor has to understand what's in it.

The 6-Level Priority Hierarchy

Claude Code doesn't load just one file. It loads a stack of files and resolves them in order. Inner wins over outer:

Level 1 sets global defaults. Level 2 sets repo rules. Level 3 holds machine-specific stuff that should never leave your laptop.

The CLAUDE.local.md gotcha: Claude Code does not add this file to .gitignore on your behalf. You have to do it yourself. If you forget, git tracks it and it goes up with your next commit. Good candidates for the file: local API endpoints, personal debugging preferences, sandbox URLs. None of those belong in the shared tree.

@imports and the Bridge to AGENTS.md

Inside any CLAUDE.md file, you can pull in another file with @path/to/file.md. The imported content gets injected where the @ line sits.

That's how Claude Code 2.1.59+ lets you bridge AGENTS.md:

# CLAUDE.md
@AGENTS.md
<!-- Claude reads AGENTS.md content here, but CLAUDE.md rules below take priority -->

## Claude-specific rules
- Use TodoWrite to track multi-step tasks
- Never use --dangerously-skip-permissions outside containers

The imported AGENTS.md content loads. But Level 6 (imports) is the weakest layer in the hierarchy. If a rule in AGENTS.md conflicts with a rule written directly in CLAUDE.md, the direct rule wins. Always.

This means AGENTS.md content is always advisory when brought in via import. It informs Claude's behavior. It does not override what you've written in the root file.

The Symlink Trick

The cleanest multi-tool setup avoids the import complexity altogether. Run this once at repo root:

ln -s CLAUDE.md AGENTS.md

Now AGENTS.md is a symlink pointing at CLAUDE.md. Claude Code reads CLAUDE.md. Cursor, Windsurf, Gemini CLI, and every other AGENTS.md-aware tool reads AGENTS.md. They all hit the same bytes.

No duplication. No sync problem. One file to maintain.

The only trade-off: Claude Code ignores AGENTS.md schema fields, and AGENTS.md-aware tools ignore Claude Code-specific instructions (like TodoWrite or --dangerously-skip-permissions flags). In practice that's fine. Prose instructions work for both. Schema fields are just skipped.

Auto-Memory and MEMORY.md

Claude Code 2.1.59+ can write to a MEMORY.md file at your project root on its own. This file sits at Level 5, the same priority as your repo-level CLAUDE.md.

The file has hard limits: 200 lines and 25KB. For on-demand topic files (like memory/auth.md or memory/payments.md), the cap is 120 lines each. MEMORY.md itself acts as an index pointing to those topic files.

What to watch for: memory entries that contradict each other cause silent ambiguity. Claude doesn't throw an error. It just has two conflicting instructions and resolves them quietly, which may not go the way you expect. Audit MEMORY.md periodically. Remove entries older than 30 days that haven't recurred.

The 7 Ways CLAUDE.md Goes Wrong

Most teams write a CLAUDE.md once and never revisit it. These are the failure modes that accumulate over time:

Priority saturation: Too many ALWAYS and NEVER and CRITICAL labels. When every rule screams, none of them land. Claude treats overloaded files by spreading attention across all rules equally. Keep hard constraints to 5-7 maximum.

The "may or may not be relevant" wrapper: When Claude Code injects session context, it sometimes wraps it in this hedge. That wrapper signals the content was loaded but is being treated as background, not as instructions. Files with this wrapper are not being followed closely.

Import depth dilution: Instructions in an imported file are weaker than instructions written directly. A chain like CLAUDE.md → @a.md → @b.md is very diluted by the time you reach b.md. Keep important rules in the root file.

Trauma replay: MEMORY.md accumulates every correction you've ever made. After 50 sessions, Claude is trying to avoid 50 different past mistakes at once. Performance degrades. Periodic audits fix this.

Bias accumulation: Positive confirmations that get written to memory ("user prefers X") can calcify into rules that no longer match your current preferences. What you preferred six months ago may not be what you prefer today.

Instruction-following vs. enforcement: CLAUDE.md is loaded as context, not enforced like a linter. A rule that says "never use em-dashes" can still be violated. If a rule matters, pair it with actual tooling (a lint rule, a hook, a formatter) rather than relying on context alone.

Post-/compact loss: Running /compact summarizes the conversation. Instructions that were in the chat but not in CLAUDE.md don't survive compaction. Write durable rules to the file. Don't keep them only in the session.

What Goes in Each File

Anthropic's Boris Cherny frames the target directly: CLAUDE.md should hold behaviors that need to persist across every session.

Put in CLAUDE.md: operational workflows, routing logic, quality standards, coordination protocols, hard constraints (5-7 max), delegation patterns.

Put in skills (loaded on demand): technology patterns, framework conventions, project-specific context, architecture docs, team conventions.

Do not put in CLAUDE.md: architecture documentation (read from code), recent git history (use git log), current PR status, boilerplate instructions every model already follows by default.

The line count advice you'll find elsewhere says to stay under 60 lines. That's wrong. Sixty lines of project trivia you only need half the time wastes more effective context than 300 lines of universal operational rules that apply to every request. Relevance is the metric, not length.

Choosing Your Setup

Three patterns cover most use cases:

If you only use Claude Code, write a single CLAUDE.md and ignore AGENTS.md entirely. It doesn't exist for you.

If your team uses multiple tools but Claude Code is primary, use the symlink. One file, both filenames, no maintenance overhead. Write in the style that works for Claude Code; other tools get what they can from the prose.

If you need Claude Code to stay in sync with a repo-wide AGENTS.md that other tools maintain, use the @AGENTS.md import bridge inside your CLAUDE.md. Remember that the imported content is advisory. Put your Claude-specific overrides below the import line.

Two files, one clear rule: Claude reads CLAUDE.md, everyone else reads AGENTS.md, and a symlink is the fastest way to make them the same.

Common Questions

What is AGENTS.md?

AGENTS.md is an open standard published by the Linux Foundation and the Agent Interoperability Initiative Foundation. It defines a single context file any AI coding tool can read when it opens your repo. Over 18 tools support it, including Cursor, Windsurf, Gemini CLI, Devin, and OpenAI Codex. It is used in more than 60,000 open-source projects.

Does Claude Code read AGENTS.md?

Claude Code does not read AGENTS.md natively. It reads CLAUDE.md instead. You can pull AGENTS.md content into Claude Code using an @AGENTS.md import line inside your CLAUDE.md file, or point both filenames at the same file using a symlink. Neither approach changes which file Claude Code treats as authoritative.

What is the difference between AGENTS.md and CLAUDE.md?

AGENTS.md is a cross-tool standard that any AI coding assistant can read. CLAUDE.md is Claude Code's native file, loaded automatically at the start of every session. AGENTS.md uses a structured schema with fields like allowed_tools and output_format. CLAUDE.md uses plain prose instructions and supports Claude Code-specific features like @imports, CLAUDE.local.md, and auto-memory.

What should I put in CLAUDE.md?

Put operational rules that apply to every session: workflows, routing logic, quality standards, hard constraints, and delegation patterns. Keep hard constraints to 5-7 maximum. Do not put architecture documentation, recent git history, or boilerplate instructions that any model follows by default. Technology specifics and project context belong in skills that load on demand, not in the root file.

What is CLAUDE.local.md used for?

CLAUDE.local.md holds machine-specific settings that should not be committed to version control. Good candidates include local API endpoints, personal debugging preferences, and sandbox URLs. Claude Code does not add it to .gitignore automatically, so you have to do that yourself. If you forget, the file goes up with your next commit and exposes local configuration to every contributor.

How do I use CLAUDE.md and AGENTS.md together?

The cleanest approach is a symlink at your repo root: ln -s CLAUDE.md AGENTS.md. Claude Code reads CLAUDE.md, and every other tool reads AGENTS.md. Both hit the same bytes with no duplication. If you need Claude Code to stay downstream of a shared AGENTS.md file maintained by the team, use the @AGENTS.md import inside your CLAUDE.md and write any Claude-specific overrides below the import line.