Book a Free Strategy Call
Skip the read: talk to Walid 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.mdCLAUDE.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.
claude-md-and-agents-md. Then it reads both.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
| Your repo situation | What to do | Why |
|---|---|---|
| Claude-only repo | Keep CLAUDE.md. Nothing to change. | Any CLAUDE.md wins, so AGENTS.md is ignored by default. |
| Multi-tool repo (Codex, Cursor, others) | Maintain one AGENTS.md and delete the CLAUDE.md. Or keep a short CLAUDE.md that starts with @AGENTS.md and adds Claude-only notes. | Without a CLAUDE.md, Claude reads AGENTS.md directly. The import version helps when some sessions cannot load AGENTS.md. |
Old @AGENTS.md import or symlink | Leave it, or delete it if it holds nothing else. | The docs say the import never makes Claude read AGENTS.md twice. A symlinked CLAUDE.md is read once. |
| Monorepo with nested AGENTS.md | Put an AGENTS.md in each directory that needs one. Do not add a CLAUDE.md there. | A subdirectory AGENTS.md loads only if that subdirectory has none of the three CLAUDE.md files. |
| Windows contributors | If you must keep a CLAUDE.md, use an @AGENTS.md import, not a symlink. | Symlinks need Administrator or Developer Mode, and a committed symlink checks out as plain text without core.symlinks. |
| Org-managed CLAUDE.md | No change. It keeps loading next to AGENTS.md. | The managed file is not counted as a project CLAUDE.md. |
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.mdorCLAUDE.local.mdin the working directory or above, other than~/.claude/CLAUDE.md. - Run
claude --versionand confirm 2.1.277 or later. - Check whether your session is one that cannot load AGENTS.md (see below).
- Open
/configand confirm Project instructions is notclaude-mdormanaged-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.mdimport. - 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.
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.
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. AY Automate 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
What Is GraphRAG? How It Works and When to Use It Over Vector RAG (2026)
GraphRAG retrieves from a knowledge graph instead of just ranking text chunks by similarity, which makes it better at multi-hop and relationship questions and worse at cost and maintenance. Here's what it actually is, how the extraction-to-traversal pipeline works, and when the graph is worth the overhead.
What Are Multi-Agent Systems? A Practical Guide for Business Teams (2026)
A multi-agent system is more than one AI agent coordinating to finish a task, not one agent with a longer tool list. Here's the honest version: the real coordination patterns, when splitting into multiple agents actually helps, and when it's just complexity for its own sake.
Jev Is Live: What TypeSafe's "System One" AI Model Actually Does
TypeSafe AI came out of stealth Sept 15, 2026 with $40M in funding and Jev, a model that returns typed decisions instead of generated text. Three days later it's listed on OpenRouter, and developers report wiring it into Claude Code, browser automation, and ad analysis.
Book a Free Strategy Call
Building this in production?
Walid 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. Adel owns the technical architecture behind every automation and AI agent system AY Automate ships.
