Claude Code now supports AGENTS.md Natively - Here's how it actually works

Quick answer: As of 4 days ago, September 18, Claude Code natively reads AGENTS.md , the open, cross-tool standard for AI coding agent instructions. By default it's a fallback, not a merge: Claude Code reads AGENTS.md only in a project that has no CLAUDE.md in the working directory or any parent directory. If a CLAUDE.md exists anywhere in that chain, Claude Code reads that instead and ignores AGENTS.md . You can change this under /config → "Project instructions." If you've been running more than one coding agent against the same repo, you've probably already got a CLAUDE.md , a .cursorrules , maybe a .github/copilot-instructions.md , and a handful of other files that all say roughly the same thing in slightly different dialects. Anthropic just closed one of those gaps. Below is what changed, exactly how the fallback logic works, and what to do if you're running a monorepo or already have a CLAUDE.md you want to keep. A reminder of what AGENTS.md is? AGENTS.md is an open, tool-agnostic Markdown file, a "README for agents" that tells any AI coding agent how to work in a given repository: build commands, test commands, style rules, off-limits directories, and deploy steps. It sits at the repo root (or nested in subdirectories, for monorepos) and is read by more than twenty coding tools, including Codex, Cursor, Gemini CLI, Copilot, and now Claude Code. The pitch behind the standard is simple: instead of every vendor inventing its own instruction file with its own name, its own parsing rules, and its own precedence quirks, agents converge on one plain-Markdown file that any tool can read. No proprietary schema, no lock-in, no special syntax, just Markdown a human can also open and understand. The workaround era Before native support landed in Claude Code, AGENTS.md and CLAUDE.md lived side by side, and keeping them in sync was entirely on you. The common patterns looked like this: - Symlinks. ln -s AGENTS.md CLAUDE.md so both filenames pointed at one file. Worked until someone's editor or git config mangled the symlink on checkout, or a Windows teammate's filesystem didn't preserve it. - Loader scripts. Small pre-commit hooks or Makefile targets that concatenated AGENTS.md intoCLAUDE.md on save, so Claude Code would pick up the content under the name it actually looked for. - Community plugins and skills. Wrapper skills whose entire job was "go find AGENTS.md , read it, and inject it into context" - a workaround built entirely because the CLI didn't do this itself yet. - Just maintaining both, by hand. The most common answer, and the one most likely to drift. Someone updates the build command in AGENTS.md for the Cursor and Aider users on the team, forgetsCLAUDE.md , and now Claude Code is running stale instructions until someone notices. None of these were catastrophic. All of them were friction that had nothing to do with the actual work, infrastructure tax paid just to keep one CLI aligned with a standard the rest of the ecosystem had already settled on. How does Claude Code's AGENTS.md support actually work? Claude Code added the feature with characteristically plain wording in the changelog: "Added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead; change it under 'Project instructions' in /config (not yet on Bedrock, Vertex or Foundry)" That sentence matters more than it looks, the default behavior is a fallback, not a merge. Claude Code checks the working directory and every parent above it; if a CLAUDE.md exists anywhere in that chain, AGENTS.md is ignored entirely. Only when there's no CLAUDE.md in scope does it read AGENTS.md instead. It's implemented as a built-in plugin under the hood, which is why it's configurable rather than hardcoded. The four "Project instructions" modes in /config | Mode | Behavior | When to use it | |---|---|---| claude-md-or-agents-md (default) | Reads CLAUDE.md if one exists anywhere above the working directory; otherwise falls back to AGENTS.md . | You have no CLAUDE.md yet, or you're fine with AGENTS.md only applying where CLAUDE.md is absent. | claude-md-and-agents-md | Loads both files together; CLAUDE.md takes precedence on overlapping instructions. | You want one shared AGENTS.md to serve every tool, with CLAUDE.md layered on top for Claude-specific extras. | claude-md | Ignores AGENTS.md entirely - pre-2.1.277 behavior. | You deliberately want Claude Code isolated from the shared file. | managed-only | Drops checked-in and private instruction files; keeps only organization-managed config. | Enterprise/compliance setups that centrally control agent instructions. | Practical consequences: Symlinks, monorepos, and known limitations - For a single root file, you can drop the symlink. If your only instruction file lived at the repo root and you were symlinking CLAUDE.md → AGENTS.md purely so Claude Code would notice it, that's no longer necessary under the default fallback mode. - For monorepos, symlinks aren't actually replaced - they're replaced by a different pattern. A nested AGENTS.md inapps/api/ is not picked up automatically if anyCLAUDE.md exists above it in the tree (including at the repo root), because the fallback check happens per-lookup and a closer or higherCLAUDE.md wins. If you want Claude Code to respect a nestedAGENTS.md while other tools keep reading it directly, the documented pattern is a smallCLAUDE.md next to it that imports i*@AGENTS.md rather than a symlink. SetinstructionFiles toclaude-md-and-agents-md if you want both loaded everywhere instead. - It's not available everywhere yet. Bedrock, Vertex, and Foundry deployments don't have it as of this writing. There are also a handful of sharper edges: nested AGENTS.md files attach on file reads but aren't restored after context compaction, they don't show up in/memory , and directories added via--add-dir don't contribute theirAGENTS.md at all. Worth checking/config and the changelog before you assume parity withCLAUDE.md in every edge case. - One less thing to explain to new hires or new agents. For the common case, one instruction file at the root, no CLAUDE.md in the way, point someone (or something) at the repo, and the instructions are just there, under the name every other tool already expects. Why this matters for teams standardizing agent workflows If your team runs a single agent, none of this changes much, update one file, move on. The value shows up the moment you're running more than one, which is increasingly the default rather than the exception: Claude Code for one class of task, a Cursor or Codex-based agent for another, a CI-triggered agent doing automated reviews, maybe a background agent doing dependency bumps. Every one of those previously needed its own copy of "here's how this repo works," or needed you to maintain the sync tooling described above. Native AGENTS.md support means that gap can close but only if you actually pick the mode that matches your setup. Ship a repo with just AGENTS.md and nothing else, and Claude Code, Cursor, Codex, and Copilot all read the identical file by default with zero configuration. Keep a CLAUDE.md around too which most existing Claude Code users will and you need to either explicitly switch /config to claude-md-and-agents-md , or accept that CLAUDE.md is what Claude reads while everyone else reads AGENTS.md , and keep the two in sync on purpose. For a technical lead, that's the actual decision to make, not just the actual win: treat AGENTS.md as the cross-tool baseline everyone gets by default, and reserve CLAUDE.md for Claude-specific extras (hook config, permission modes) layered on top via claude-md-and-agents-md or an explicit @AGENTS.md import. Do that once, deliberately, and "which instruction file does this tool actually read" stops being a recurring Slack question. A quick tip while you're at it If part of your AGENTS.md includes instructions for agents to look things up, current library versions, API docs, internal runbooks, it's worth pointing that lookup at something more precise than the model's default built-in web search. Use Valyu for that in our own agent configs: it's a search API built specifically for LLM consumption, so an agent grounding itself against your AGENTS.md instructions gets clean, structured, current results instead of noisy search-result HTML it then has to parse. Small swap, noticeably fewer hallucinated API calls from agents "helpfully" filling gaps with stale training data. Here's an example of an agents.md file. Where this leaves you If you've been maintaining a root-level symlink purely for Claude Code's benefit, retire it. If you've only had a CLAUDE.md and never bothered with AGENTS.md because it only mattered for other tools, check /config and decide on purpose: switch to claude-md-and-agents-md if you want one file to genuinely serve everyone, or keep them separate and intentional if CLAUDE.md carries Claude-specific settings you don't want other tools tripping over. And if you're standardizing agent workflows across a team for the first time, this is as good a moment as any to start: one AGENTS.md at the root, CLAUDE.md imports (@AGENTS.md ) rather than symlinks anywhere your monorepo needs nested instructions, and a root CLAUDE.md reserved for what's actually Claude-specific. The instruction-file wars aren't fully over, there's still fragmentation elsewhere in the ecosystem but this is one less front to fight on. FAQ: Claude Code and AGENTS.md Does Claude Code read AGENTS.md by default? Only as a fallback. If no CLAUDE.md exists in the working directory or any parent directory, Claude Code reads AGENTS.md instead. If a CLAUDE.md exists anywhere above it, AGENTS.md is ignored unless you change the mode in /config . Do I still need CLAUDE.md if I have AGENTS.md? No, for shared instructions one AGENTS.md is enough under the default fallback mode. Keep CLAUDE.md only if you need Claude-specific settings (like hook or permission config) that other agents wouldn't understa