CLAUDE.md vs AGENTS.md: What Changed When Claude Code Added AGENTS.md Support (2026)

Claude Code 2.1.277 reads AGENTS.md when a folder has no CLAUDE.md. Here is the exact precedence, the /config setting, what to do with old symlink and import workarounds, and how to verify it works.

Book a Free Strategy Call

Skip the read: talk to the ManasFlow team in 30 min.

Free strategy call. We map your AI engineering team, you keep the notes.

Claude Code now reads AGENTS.md. Anthropic added it in version 2.1.277, released September 18, 2026. If a folder has no CLAUDE.md, Claude Code falls back to AGENTS.md, and you can change that behavior under "Project instructions" in /config.

The one rule that matters: any CLAUDE.md in your working directory or above it (except your personal ~/.claude/CLAUDE.md) makes Claude read that file instead of AGENTS.md. Delete it, or set Project instructions to claude-md-and-agents-md, if you want AGENTS.md read too.

What CLAUDE.md and AGENTS.md each are

Both are Markdown files in your repo that tell a coding agent how to work. Build commands, test steps, conventions, things not to touch. The agent reads them at the start of a session so you do not repeat yourself.

CLAUDE.md is Claude Code's own format. The Register describes it as able to hold Claude-specific instructions. AGENTS.md is meant to be tool agnostic. OpenAI introduced it in August 2025, according to The New Stack, and later handed it to the Agentic AI Foundation under the Linux Foundation. Tools like Codex, Cursor, Gemini CLI and GitHub Copilot read it.

Until this release, Claude Code was the odd one out. A repo used by both Claude and another tool needed two files, or a workaround to keep them in sync. For background on writing either file, see our guide to AGENTS.md and CLAUDE.md examples.

Related Reads

What Claude Code does now

Anthropic engineer Thariq Shihipar said, per The Register, that without a CLAUDE.md in a folder, "Claude will check for and use AGENTS.md." The Claude Code memory docs spell out the details.

Files that count as "a CLAUDE.md." If any of these exists in your working directory or any directory above it, Claude reads it instead of AGENTS.md.

• CLAUDE.md
• .claude/CLAUDE.md
• CLAUDE.local.md

Files that do not count. These keep loading alongside AGENTS.md and never block it.

• Your personal ~/.claude/CLAUDE.md
• Your organization's managed CLAUDE.md
• Files in .claude/rules/

What gets read, and when. At session start, Claude reads every AGENTS.md and .claude/AGENTS.md in the working directory and the directories above it. When Claude later opens a file in a subdirectory with the Read tool, it also picks up that subdirectory's AGENTS.md, but only if that subdirectory has none of the three CLAUDE.md files. Inside an AGENTS.md, @path imports work, claudeMdExcludes patterns apply, and subagents that skip project instructions skip these files too.

What is not read. AGENTS.local.md, AGENTS.override.md, and anything under a .agents/ directory.

The setting. In /config, the "Project instructions" option controls which files load. The value claude-md-and-agents-md loads both. The docs' troubleshooting steps also list claude-md and managed-only as values to rule out when AGENTS.md isn't loading. In settings JSON the same option lives under pluginConfigs, agents-md@builtin, options, instructionFiles. A change applies from your next message.

Free weekly brief

Steal our production automations

The exact n8n flows, Claude Code setups, and prompts we ship for clients, broken down step by step. No spam, unsubscribe anytime.

What to do in your situation

One caution on the monorepo row. A stray CLAUDE.md in a parent directory blocks AGENTS.md below it, because the check looks in the working directory and above. Search for leftovers before you blame the feature.

How to check it is working

Start an interactive session in the repo. Per the docs, you should see a line like no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md.

Then run /context. Here is the catch. The "Memory files" list shows an AGENTS.md only when a CLAUDE.md imports it. An AGENTS.md that Claude reads directly does not appear there. So an empty list does not mean it failed.

If AGENTS.md is not loading, the docs give this order of checks.

• Look for a CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or above, other than ~/.claude/CLAUDE.md.
• Run claude --version and confirm 2.1.277 or later.
• Check whether your session is one that cannot load AGENTS.md (see below).
• Open /config and confirm Project instructions is not claude-md or managed-only. If the setting is missing, your session cannot load AGENTS.md.

When support is unavailable. The docs list four cases. A version before 2.1.277. A session that does not fetch feature flags from Anthropic, such as Amazon Bedrock or another third-party provider, or one with telemetry disabled. Your first session after installing or upgrading, since Claude reads AGENTS.md from the next session on. And setups where disableAllHooks or allowManagedHooksOnly is set, or the built-in agents-md plugin is disabled in /plugin. The 2.1.277 changelog entry also says the feature is not yet on Bedrock, Vertex or Foundry.

What to clean up

Old workarounds are mostly harmless now, with one exception. Per the docs:

• A CLAUDE.md containing @AGENTS.md. Leave it. It never causes a double read. Delete it if it holds nothing else, or keep it if some of your sessions cannot load AGENTS.md directly.
• A CLAUDE.md that says "read AGENTS.md" in words. Claude only sees AGENTS.md if it decides to open the file. Delete the CLAUDE.md, or swap the sentence for an @AGENTS.md import.
• A CLAUDE.md symlinked to AGENTS.md. Do nothing, or delete the link. Claude reads the content once either way.
• A SessionStart hook that prints AGENTS.md. Remove it. Once Claude reads the file directly, the hook adds a second copy to context.

If you keep the symlink, know its limits. Claude reads CLAUDE.md through the link, but the Edit and Write tools refuse to write through a symlink and point Claude at AGENTS.md instead. On Windows, a committed symlink can arrive as a one-line text file in place of your instructions.

To find copies that have drifted, run /doctor prompt-audit. When we ran it on our own repo, it caught an AGENTS.md that was a find-and-replace copy of our CLAUDE.md, pointing agents at a .Codex/ folder that doesn't exist.

The docs' suggested shared setup is a CLAUDE.md whose first line is @AGENTS.md, followed by a ## Claude Code section with Claude-only notes, such as using plan mode for a specific folder.

Claude Code agency

Want this set up properly on your team?

We configure, extend and ship with Claude Code alongside your engineers: subagents, MCP servers, hooks and review loops that hold up in production.

Why this happened

Developers had asked Anthropic for AGENTS.md support for nearly a year, according to The New Stack. The pressure peaked when Shopify CEO Tobi Lütke posted that he was considering banning Claude Code at Shopify over it. He called the workaround automation a "complexity tax" and described monorepo directories missing one of the two files. The Register reported the change on September 18 and noted that OpenAI's Thibault Sottiaux welcomed it publicly.

Getting a team set up

Choosing between one shared file and a layered setup gets harder with several tools, nested directories and managed policies. ManasFlow does Claude Code setup work for teams. You can see what that covers on our Claude Code development page or in our roundup of Claude Code agencies.

FAQ

Does Claude Code read AGENTS.md now?

Yes, from version 2.1.277. It reads AGENTS.md when no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md exists in the working directory or above it. You can change this in /config under Project instructions.

Will Claude read both CLAUDE.md and AGENTS.md?

Not by default. If a CLAUDE.md exists, Claude reads it instead. To load both, set Project instructions to claude-md-and-agents-md. Alternatively, put @AGENTS.md at the top of your CLAUDE.md.

Do I need to delete my CLAUDE.md?

No. Delete it only if you want Claude to read AGENTS.md directly. A CLAUDE.md that only contains @AGENTS.md is safe to keep and does not cause a double read.

Why does /context not show my AGENTS.md?

An AGENTS.md that Claude reads directly does not appear under Memory files. It shows there only when a CLAUDE.md imports it. Check the session-start line instead.

Does ~/.claude/CLAUDE.md block AGENTS.md?

No. Your personal file, the managed organization CLAUDE.md and .claude/rules/ all keep loading alongside AGENTS.md.

Does AGENTS.md work in subdirectories?

Yes. When Claude opens a file in a subdirectory with the Read tool, it loads that folder's AGENTS.md if the folder has no CLAUDE.md of its own.

Should I use a symlink or an @AGENTS.md import?

Use the import if anyone on your team uses Windows, or if you want Claude-only notes. A symlink works otherwise, but Edit and Write refuse to write through it.

Does this work on Bedrock or Vertex?

Not yet, per the 2.1.277 changelog, and the docs say third-party provider sessions cannot load AGENTS.md. Keep an @AGENTS.md import in a CLAUDE.md for those sessions.

Continue Reading

6 Best AI Coding Assistants Compared (2026 Pricing and Features)

The best AI coding assistants in 2026 are Claude Code for terminal-first agentic work, GitHub Copilot for teams that live in GitHub, Cursor for an AI-first editor, OpenAI Codex CLI for teams already paying for ChatGPT, Devin Desktop (the former Windsurf) for running fleets of ...

AI automation agencies that ship to production: 9 compared (2026)

About 88% of enterprise AI proofs of concept never reach production, according to IDC research cited by bex.co. We graded 9 small and mid-size AI automation agencies, ManasFlow included, on whether their own sites show shipped production work and maintenance after launch.

Is Your AI Agent Production-Ready, or One Incident Away From a Headline?

AI agent incidents went from a survey statistic to a UN agenda item in 2026. What the OpenAI test agents did to Hugging Face, why static guardrails fail against agents that can plan around them, and the controls to have before an agent gets write access.

Book a Free Strategy Call

Building this in production?

the ManasFlow team runs a 30-min call to map your AI engineering team. Free, no slides.

Free weekly brief

Steal our production automations

The exact n8n flows, Claude Code setups, and prompts we ship for clients, broken down step by step. No spam, unsubscribe anytime.

Ex-IBM AI engineer and enterprise architect. the ManasFlow team owns the technical architecture behind every automation and AI agent system ManasFlow ships.

6 Best AI Coding Assistants Compared (2026 Pricing and Features)

The best AI coding assistants in 2026 are Claude Code for terminal-first agentic work, GitHub Copilot for teams that live in GitHub, Cursor for an AI-first editor, OpenAI Codex CLI for teams already paying for ChatGPT, Devin Desktop (the former Windsurf) for running fleets of ...

AI automation agencies that ship to production: 9 compared (2026)

About 88% of enterprise AI proofs of concept never reach production, according to IDC research cited by bex.co. We graded 9 small and mid-size AI automation agencies, ManasFlow included, on whether their own sites show shipped production work and maintenance after launch.

Is Your AI Agent Production-Ready, or One Incident Away From a Headline?

AI agent incidents went from a survey statistic to a UN agenda item in 2026. What the OpenAI test agents did to Hugging Face, why static guardrails fail against agents that can plan around them, and the controls to have before an agent gets write access.