Does Claude Code Read AGENTS.md? Yes, Since 2.1.277. Do You Still Need CLAUDE.md?

For a year, the answer was no.

Claude Code read CLAUDE.md. Codex, Cursor and most other coding agents read AGENTS.md. If you used two agents, you kept two files, or a symlink, or a one-line import.

The request to support AGENTS.md had 5,173 thumbs-up and 401 comments by September 19, 2026.

On September 18, 2026, Claude Code 2.1.277 changed the answer.

“Added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead.”

So that’s it? Delete CLAUDE.md, keep one file, done?

For many projects, yes. But read the sentence again. In a project with no CLAUDE.md. The new behavior is a fallback, and it comes with conditions.

Here is the short version. Claude Code 2.1.277 or later reads AGENTS.md when there is no CLAUDE.md or CLAUDE.local.md in your working directory or above it. If one exists, Claude reads that file and skips AGENTS.md. You can change this under Project instructions in /config. None of it works yet on Amazon Bedrock, Google Vertex AI or Foundry, or with telemetry turned off.

Most search results for this question still say no. They were correct until September 18.

This page follows Anthropic’s documentation and changelog as of September 19, 2026. I haven’t run my own tests.

Does Claude Code read AGENTS.md now?

Yes, under three conditions.

(1) You need version 2.1.277 or later.

Run claude --version to check. Run claude update to upgrade.

You may be behind without knowing it. On September 19, npm’s latest tag pointed to 2.1.278. The stable tag still pointed to 2.1.267.

(2) The first session after the upgrade doesn’t count.

The docs say Claude reads AGENTS.md “from your next session on.”

So if you upgrade and test right away, it looks broken. Start a second session.

(3) Some sessions can’t load it at all.

The changelog says “not yet on Bedrock, Vertex or Foundry.” The docs add sessions with telemetry disabled.

The feature ships as a built-in plugin called agents-md. Two settings turn it off: disableAllHooks and allowManagedHooksOnly. Disabling the plugin in /plugin does the same.

How can you tell? In these sessions, Project instructions doesn’t appear in /config.

The fix is the old one. Put a CLAUDE.md next to your AGENTS.md that imports it. I show it below.

Do you still need CLAUDE.md?

Often not. It depends on what your CLAUDE.md does today.

(1) A one-line @AGENTS.md import: delete it or leave it.

This was the common setup. One commenter on Hacker News wrote: “This allows us to remove our one line Claude.md files that just say ‘AGENTS.MD’.”

Leaving it does no harm. The docs say the import never makes Claude read AGENTS.md twice.

Keep it if anyone on the project is on Bedrock, an older version, or a session with telemetry off. The import works everywhere.

(2) A symlink: same answer.

ln -s AGENTS.md CLAUDE.md still works. Claude reads the content once either way.

The symlink was always awkward on Windows. Creating one needs Administrator rights or Developer Mode. And Git checks a committed symlink out as a plain text file unless core.symlinks is on. That clone gets a one-line CLAUDE.md with a file name in it.

If the symlink was your only reason for a CLAUDE.md, you can delete it now.

(3) A sentence that tells Claude to read AGENTS.md: replace it.

Another commenter: “We have a CLAUDE.md file whose only content is ‘please read .agents/agents.md’.”

This one was never reliable. The docs say Claude sees AGENTS.md “only if it decides to open the file.”

And now it gets in the way. The sentence sits in a CLAUDE.md, so Claude never falls back to AGENTS.md.

Delete the file, or replace the sentence with an @AGENTS.md import.

(4) A SessionStart hook that prints AGENTS.md: remove it.

Once Claude reads AGENTS.md directly, the hook adds a second copy to the context.

(5) Rules only Claude needs: keep CLAUDE.md, and import the shared file.

Put the import first. Put the Claude-only rules under it.

@AGENTS.md

## Claude Code

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

Claude reads the imported file first, then the rest.

What happens when both files exist?

Claude reads CLAUDE.md and skips AGENTS.md. The two are not merged.

This is the table from the docs.

Your repository has	Claude reads
An `AGENTS.md`, and no `CLAUDE.md` or `CLAUDE.local.md` in your working directory or above it	Your `AGENTS.md`
An `AGENTS.md` and a `CLAUDE.md` or `CLAUDE.local.md` in your working directory or above it	Your `CLAUDE.md` files only
A `CLAUDE.md` that imports `AGENTS.md`	Your `CLAUDE.md`, with `AGENTS.md` included through the import

(1) CLAUDE.local.md counts as a CLAUDE.md.

Say the team’s rules are in AGENTS.md. You add a CLAUDE.local.md for your own notes and keep it out of Git.

Now Claude stops reading the team’s AGENTS.md. Only for you, and nothing tells you.

.claude/CLAUDE.md counts too. So does a CLAUDE.md in any directory above the one you work in.

(2) Your personal ~/.claude/CLAUDE.md doesn’t count.

It keeps loading beside AGENTS.md. So do your organization’s managed CLAUDE.md and the files in .claude/rules/.

(3) You can have Claude read both.

Type /config and set Project instructions.

Value	What Claude reads
`claude-md-or-agents-md`	`CLAUDE.md` files, or `AGENTS.md` when there are none. The default
`claude-md-and-agents-md`	Both. In each directory, `CLAUDE.md` first and `AGENTS.md` after it
`claude-md`	`CLAUDE.md` files only, as before 2.1.277
`managed-only`	Only your organization’s managed instructions and auto memory

You can also set it in ~/.claude/settings.json.

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

(4) You can’t set it for the whole team from the repository.

Claude Code ignores this option in project and local settings files. It reads it from your user settings, a --settings file, or managed settings.

So each person sets it on their own machine. If the team needs both files read everywhere, the @AGENTS.md import is still the way to put that in the repository.

Why isn’t my AGENTS.md loading?

The usual cause is a CLAUDE.md somewhere on the path. Check in this order.

(1) Look for a CLAUDE.md you forgot about.

Look in your working directory and every directory above it. Look for CLAUDE.md, .claude/CLAUDE.md and CLAUDE.local.md.

A stray CLAUDE.md in a parent folder is enough.

(2) Check the version, then start a second session.

You need 2.1.277 or later. The first session after the upgrade doesn’t read AGENTS.md.

(3) Open /config and look for Project instructions.

If the setting isn’t there, your session can’t load AGENTS.md. The likely reasons are Bedrock, Vertex, Foundry, telemetry off, or one of the hook settings.

If it is there, check that it isn’t set to claude-md or managed-only.

(4) Don’t look in /memory.

An AGENTS.md that Claude reads directly isn’t listed in /memory. It isn’t under Memory files in /context either.

Look for this line when the session starts.

no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md

Or ask Claude what its project instructions say.

(5) Check whether the folder was added with --add-dir.

A CLAUDE.md in an added directory loads when CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD is set. An AGENTS.md there doesn’t.

Do Claude Code and Codex read AGENTS.md the same way?

No. The file name is shared. The loading rules aren’t.

Codex’s rules differ from Claude Code’s in four ways.

(1) Codex reads AGENTS.override.md. Claude Code doesn’t.

In Codex, an AGENTS.override.md wins over the AGENTS.md at the same level.

Claude Code doesn’t read AGENTS.override.md, AGENTS.local.md, or anything under a .agents/ directory.

Commenters in the Hacker News thread pointed out that skills in .agents/skills still aren’t picked up either.

(2) Codex stops at 32 KiB.

Codex joins the files it finds. It stops adding files when the total reaches project_doc_max_bytes, which is 32 KiB by default.

Claude Code’s docs give a different kind of limit. Aim for under 200 lines per file, because longer files “reduce adherence.”

Short is safer for both.

(3) They walk the folders differently.

Codex starts at the Git root and walks down to your current directory. It takes one file per level. Later files sit lower in the prompt, so they win.

Claude Code reads the AGENTS.md in your working directory and in each directory above it. It picks up a subdirectory’s AGENTS.md later, when it reads a file there.

(4) Claude Code expands @path imports inside AGENTS.md.

Codex’s guide doesn’t mention imports. Don’t count on them there. To Codex, @docs/style.md may be plain text.

So what belongs in the shared file? Plain rules, written out in full. No imports, no override files, and nothing long.

One more caution from the same thread. swyx argued that prompts should be tuned for each model, and that “blindly applying agents.md is probably an antipattern.”

You don’t have to agree. But it is a good reason to keep Claude-only rules in a CLAUDE.md that imports the shared file, when you have such rules.

Does this matter outside a code repository?

Yes. The thread is about code, but a folder of notes or drafts has the same problem.

Many people run Claude Code on a notes folder one day and Codex the next. Until now that meant two instruction files with the same rules for tone, sources and which files to leave alone.

Now one AGENTS.md can serve both. Here is a small one for a writing folder.

# AGENTS.md

- Drafts are in drafts/. Sources are in sources/. Never edit a file in sources/.
- Before you state a fact, find it in sources/ and name the file.
- Match the voice of the pieces in published/. Don't add praise or summaries.
- Ask before you create, move or delete a file.

We have two guides that use an instruction file this way. One is for Claude Code and one is for Codex. With 2.1.277, the Codex version’s AGENTS.md can serve both agents, as long as the folder has no CLAUDE.md.

Is a longer file better? Probably not. A study from ETH Zurich tested context files such as AGENTS.md on real coding tasks. The files didn’t generally improve success rates, and they raised inference cost by over 20%. Agents did follow the specific instructions in them.

So keep the file to rules you have decided on, and check that each one helps. I cover the study in How to Write with an LLM.

We make StashBase, a local writing app that runs Claude Code or Codex beside your documents. So read this part as coming from its developers.

In StashBase you switch between Claude Code and Codex from the agent picker, on the same folder. Agent Instructions in the Chat toolbar holds the rules for that folder. StashBase stores them and sends them to whichever agent you pick. It doesn’t create or rewrite AGENTS.md or CLAUDE.md in your folder. See the agent setup guide.

If you also work on that folder from a terminal, keep an AGENTS.md in it. As of 2.1.277, both agents read it.