Dev.to AI ๐Ÿค– Ai ๐Ÿ‘ 0 ๐Ÿ“– 6 min read

Does Claude Code read AGENTS.md?

Yes, since Claude Code v2.1.277, but only when there's no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your folder or above it. Here's which files switch it off, how to make Claude read both, and what it costs. Or

Yes, since Claude Code v2.1.277, but only when there's no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your folder or above it. Here's which files switch it off, how to make Claude read both, and what it costs.

Originally published on clogmeter.vercel.app.

Yes, from Claude Code v2.1.277, but by default only when your project has no CLAUDE.md. If a CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md sits in the folder you start Claude in or any folder above it, Claude reads those files and skips AGENTS.md completely. To get both, either start CLAUDE.md with @AGENTS.md, or set Project instructions to claude-md-and-agents-md in /config.

People have been asking this for months. In an r/ClaudeAI thread, "Do we still need to maintain CLAUDE.md and AGENTS.md?", the poster asks: "Has claude and claude code adopted AGENTS.md? I'm symlinking them but wondering if I can just drop CLAUDE.md all together." When native support was announced in September, the top question was the same one: "Should we delete just CLAUDE.md, and just use AGENTS.md instead?" This post answers both. For who reads which file in general, see CLAUDE.md vs AGENTS.md vs Cursor rules.

Behaviour is taken from Anthropic's Claude Code docs, How Claude remembers your project, and the v2.1.277 changelog (checked 22 Nov 2026). Claude Code changes often, so confirm on your version with the checks at the end.

What Claude reads, by repo layout

Your repo has Claude Code reads (default setting)
AGENTS.md only AGENTS.md. You see no CLAUDE.md found; AGENTS.md loaded: รขโ‚ฌยฆ at the start of the session
AGENTS.md and a CLAUDE.md (or CLAUDE.local.md) in your folder or above CLAUDE.md files only. AGENTS.md is ignored
A CLAUDE.md that starts with @AGENTS.md Both, through the import. AGENTS.md loads once
CLAUDE.md symlinked to AGENTS.md The content once

When AGENTS.md is the one being read, Claude treats it the way it treats CLAUDE.md. Every AGENTS.md and .claude/AGENTS.md from your launch folder upward loads at startup. A subfolder's AGENTS.md loads when Claude first reads a file in that folder, as long as that folder has no CLAUDE.md of its own. @path imports inside it are expanded.

The files that switch AGENTS.md off

The check only looks at three project files. Some files that look like they should count don't.

  • Count (Claude reads these instead of AGENTS.md): CLAUDE.md, .claude/CLAUDE.md and CLAUDE.local.md, in your working folder or any folder above it.
  • Don't count (they load alongside AGENTS.md): your personal ~/.claude/CLAUDE.md, your organisation's managed CLAUDE.md, and .claude/rules/ files.
  • Never read: AGENTS.local.md, AGENTS.override.md (a Codex file) and anything under a .agents/ folder.

The trap is CLAUDE.local.md. If you add one for your own uncommitted notes in a team repo that relies on AGENTS.md, Claude stops reading the team's AGENTS.md for you, with no error. A CLAUDE.md in a parent folder, for example in a monorepo root or your home folder above the repo, does the same.

How to make Claude read both

Type /config in a session and change Project instructions:

Value What loads
claude-md-or-agents-md (default) CLAUDE.md files, or AGENTS.md when there is no CLAUDE.md/CLAUDE.local.md
claude-md-and-agents-md Both. In each folder CLAUDE.md loads first, then AGENTS.md. A file already pulled in by an import or symlink isn't read twice
claude-md CLAUDE.md only (the old behaviour)
managed-only Only your organisation's managed CLAUDE.md and auto memory at launch

To set it in a file, add it to your user settings (~/.claude/settings.json) or managed settings. Claude Code ignores this entry in project and local settings files, so you can't commit it for the team:

{
  "pluginConfigs": {
    "cc-plugin-agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}

Before v2.1.285 the plugin ID was agents-md@builtin. Later versions accept either ID.

For a team, the setting doesn't help, because each person has to change it themselves. A committed CLAUDE.md whose first line is @AGENTS.md works for everyone on any version.

Can I delete CLAUDE.md and keep only AGENTS.md?

Yes, if all of these are true:

  1. Everyone is on v2.1.277 or later. Sessions on Amazon Bedrock or with telemetry turned off needed v2.1.281. Run claude --version.
  2. Nobody keeps a CLAUDE.local.md or a parent-folder CLAUDE.md, or they've switched to claude-md-and-agents-md.
  3. You don't rely on InstructionsLoaded hooks. They don't fire for an AGENTS.md that Claude reads directly. They do fire for an imported one.
  4. You don't need extra folders' instructions through --add-dir with CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD. Their CLAUDE.md loads, but their AGENTS.md doesn't.

If any of these fails, keep a one-line CLAUDE.md:

@AGENTS.md

## Claude Code only
- Hooks live in .claude/settings.json; don't duplicate their rules here.

Anthropic's docs say keeping the import never makes Claude read AGENTS.md twice, whichever setting you use.

Clean up old workarounds

  • A CLAUDE.md that only says @AGENTS.md: you can leave it, or delete it if every session can read AGENTS.md directly.
  • A CLAUDE.md that says "read AGENTS.md" in words: fix this one. Claude only sees AGENTS.md if it decides to open it, and because the CLAUDE.md exists, the native read is switched off. Replace the sentence with @AGENTS.md, or delete the file.
  • A CLAUDE.md symlink to AGENTS.md: it still works and loads once. Claude's Edit and Write tools won't write through the link and edit AGENTS.md instead. On Windows clones without core.symlinks, the link becomes a one-line text file, so use the import there. (Cursor is a separate case: see when symlinks double your tokens.)
  • A SessionStart hook that prints AGENTS.md: remove it. Now that Claude reads the file itself, the hook adds a second copy every session.

What it costs

Whatever Claude reads at startup is paid for in every session, before your first prompt. Switching to native AGENTS.md doesn't make the file cheaper. It only changes which file you pay for. The setting that can raise your bill is claude-md-and-agents-md: if your CLAUDE.md and AGENTS.md were maintained as separate copies of the same rules, both now load. Claude Code dedupes files (by import, symlink, or the same file loaded twice), not repeated paragraphs, so overlapping text in two files is paid for twice. It also gives you two places for an "always" and a "never" to contradict each other.

For size limits, see How long should CLAUDE.md / AGENTS.md be?

How to check what Claude read

  1. Start a fresh session and look for the line no CLAUDE.md found; AGENTS.md loaded: /path/to/AGENTS.md.
  2. Run /memory and look for the AGENTS.md path in the list. Before v2.1.280, /memory and /context didn't list a directly read AGENTS.md, so ask Claude what its project instructions say instead.
  3. Not loading? Look for a CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your folder or above (other than ~/.claude/CLAUDE.md). Then check claude --version. Finally, check that /config รขโ€ โ€™ Project instructions isn't set to claude-md or managed-only. If the setting isn't there at all, your session can't load AGENTS.md, so use the import. On your first session after upgrading from v2.1.276 or earlier, it can take one more session to start working.

If you want to see what your own AGENTS.md and CLAUDE.md cost in tokens, and where they repeat or contradict each other before you turn on both, we built a free browser-only checker: Clogmeter. For a single file there's the AGENTS.md / CLAUDE.md token counter, and for Cursor rules the Cursor rules token counter.

๐Ÿ“ฐ Read the original article on Dev.to AI

Originally published by Dev.to AI. Aggregated on AIWithGhost for educational purposes โ€” full credit and traffic to the original publisher.