Claude Code now reads AGENTS.md files natively: since the v2.1.277 and v2.1.278 releases of 18 and 19 September 2026, per Anthropic's official changelog, claude code agents.md support means a repository already set up for other coding agents works without adding a CLAUDE.md, an import, or a setting — Claude Code simply loads your AGENTS.md as project instructions whenever no CLAUDE.md exists in your working directory or above it. If you have been maintaining a CLAUDE.md that only says "read AGENTS.md", or keeping duplicate instruction files in sync across tools, you can stop doing that on current versions.
📺 Watch: Claude Just Dropped Game Changer Updates! 🤯
🔥 Get the Agent OS as a free bonus: AI Profit Boardroom members get the full Agent OS zip, prompt libraries, daily tutorials and weekly live coaching calls. → Get inside · Want AI SEO help 1-on-1? Book a free SEO strategy session →
What Claude Code AGENTS.md Support Actually Does
AGENTS.md is the vendor-neutral instructions file that a growing number of coding agents read for project context — architecture notes, coding standards, build commands, the rules you want an agent to follow in that repository. Until mid-September 2026, Claude Code ignored it unless you imported it from a CLAUDE.md. That changed in the releases Anthropic shipped on 18 and 19 September 2026: the changelog entry for v2.1.278 (19 September 2026) states that Claude Code reads AGENTS.md in projects without CLAUDE.md, and Anthropic's memory documentation confirms that reading AGENTS.md directly requires Claude Code v2.1.277 or later.
The behaviour is deliberately conservative by default. Anthropic's documentation describes the default mode, called claude-md-or-agents-md: Claude Code reads your AGENTS.md only when you have no CLAUDE.md in your working directory or any directory above it. If both files exist, your CLAUDE.md files win and AGENTS.md is ignored unless you change a setting or import it. And if your CLAUDE.md already imports AGENTS.md, nothing breaks — the import continues to work and the file is never read twice. Existing setups keep behaving exactly as they did, which is the point: AGENTS.md support removes boilerplate for repositories that never adopted CLAUDE.md, without reshuffling instructions for teams that did.
Claude Code AGENTS.md Support: The Exact Loading Rules
Anthropic's memory page spells out precisely which files count when Claude Code decides whether to load AGENTS.md. These are the combinations, as documented:
| Your repository has | Claude Code reads |
|---|---|
| An AGENTS.md, and no CLAUDE.md or CLAUDE.local.md in the working directory or above | Your AGENTS.md |
| An AGENTS.md and a CLAUDE.md or CLAUDE.local.md in the working directory or above | Your CLAUDE.md files only |
| A CLAUDE.md that already imports AGENTS.md | Your CLAUDE.md, with AGENTS.md included through the import |
Three details in the AGENTS.md rules are easy to miss. First, only a CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or above it blocks AGENTS.md from loading — your personal user-level CLAUDE.md in your home .claude folder, an organisation's managed CLAUDE.md, and .claude/rules/ files do not count, and keep loading alongside AGENTS.md. Second, at session start Claude Code loads every AGENTS.md and .claude/AGENTS.md in your working directory and the directories above it, and in an interactive session you see a confirmation line telling you no CLAUDE.md was found and which AGENTS.md loaded. Third, as Claude works in subdirectories, a subdirectory's own AGENTS.md loads when Claude opens a file there — provided that subdirectory has no CLAUDE.md variants of its own.
The documentation is equally clear about what is never read: AGENTS.local.md, AGENTS.override.md, and anything under a .agents/ directory. Inside each AGENTS.md that does load, path imports are expanded and exclusion patterns apply, the same as a CLAUDE.md. One gotcha worth flagging: because CLAUDE.local.md counts as a blocking file, adding one for your own uncommitted notes in a repository that relies on AGENTS.md silently stops AGENTS.md loading for you — the fix is the setting covered next.
If you want your Claude Code setup producing income instead of just tidy config files — the workflows, prompt libraries and weekly coaching calls that AI Profit Boardroom members use to ship automation projects that pay — check out the AI Profit Boardroom → get the full stack here. Want AI SEO help 1-on-1 first? Book a free SEO strategy session and get a plan for your own site.
How to Choose Which Instruction Files Load
Anthropic exposes the AGENTS.md behaviour through a Project instructions setting with three documented values:
- claude-md-or-agents-md — the default. CLAUDE.md files load, or AGENTS.md files load when no CLAUDE.md or CLAUDE.local.md exists in or above the working directory.
- claude-md-and-agents-md — both load together, each directory's CLAUDE.md files first and its AGENTS.md after them. Claude Code skips an AGENTS.md it has already loaded, so a file your CLAUDE.md imports or symlinks to is never read twice. This is also the documented fix for the CLAUDE.local.md gotcha above.
- managed-only — only your organisation's managed CLAUDE.md and auto memory load at launch; project, local and user CLAUDE.md files, .claude/rules/ files and every AGENTS.md are left out.
You can change the value in the config command, or set it in a settings file under the built-in agents-md plugin's entry in pluginConfigs — Anthropic notes it belongs in your user settings.json, a settings flag file, or managed settings, and that Claude Code ignores it in project and local settings files. Also documented: AGENTS.md support can be unavailable in specific cases — if you disabled the built-in agents-md plugin, sometimes in your first session after upgrading from v2.1.276 or earlier, and, before v2.1.281 (released 23 September 2026), in some session types such as Amazon Bedrock or sessions with telemetry disabled. On affected versions the guidance is to update Claude Code, or fall back to importing AGENTS.md from a CLAUDE.md.
Differences From CLAUDE.md and Old Workarounds to Remove
An AGENTS.md read through the setting is not a perfect drop-in for CLAUDE.md, and Anthropic documents the differences. InstructionsLoaded hooks do not fire for an AGENTS.md read through the setting — though they fire as usual for one that a CLAUDE.md imports or symlinks to. And directories added with the add-dir option under the additional-directories environment variable load their CLAUDE.md but not their AGENTS.md. If your automation depends on either behaviour, keep the import approach.
If you set up an AGENTS.md workaround before native support existed, the official advice is straightforward. A CLAUDE.md containing an AGENTS.md import can stay — keeping the import never causes a double read, whichever setting you use — and you can delete the CLAUDE.md entirely if it holds nothing else. The one setup you should actively replace is a CLAUDE.md that tells Claude in words to go and read AGENTS.md: Claude only sees the file if it decides to open it, so replace the sentence with a proper import or delete the wrapper file and let native AGENTS.md loading take over.
Why AGENTS.md Support Matters for Your Automation Stack
If you run several coding agents against the same repositories, AGENTS.md becoming a first-class citizen in Claude Code removes a genuine maintenance tax: one instructions file now serves every tool that reads the format, with no duplicate CLAUDE.md to keep in sync. That matters most when your repository is the home of an agent system rather than just application code — the Agent OS approach of giving agents a structured operating system of instructions and workflows is exactly the kind of setup where a single canonical instructions file pays off. Pair it with the Goldie Bench write-up if you are deciding which model brain should sit behind those instructions — it covers how the current options compare in hands-on tests.
For wider context on the tool itself, the guide to learning Claude Code covers the fundamentals, and there are dedicated walkthroughs on running Claude Code free, building a Claude Code SEO agent, enabling no-flicker mode, and the broader agentic OS setup for Claude Code — with the best Claude course roundup if you want a structured path through all of it. The same 18-23 September 2026 release window also shipped quality-of-life changes worth knowing about — the v2.1.278 changelog entry adds a server-side auto mode classifier default for Claude API and Enterprise users, and v2.1.281 adds an attribution setting for hiding commit and PR attribution — small changes, but they all point the same direction: less manual configuration between you and a working agent.
📺 Watch: Claude Just Got NEW Crazy Updates! 🤯
Claude Code AGENTS.md Support FAQ
Which Claude Code version do I need for AGENTS.md support?
Anthropic's documentation states that reading AGENTS.md directly requires Claude Code v2.1.277 or later, released 18 September 2026. Before v2.1.281 some session types — such as Amazon Bedrock sessions or sessions with telemetry disabled — still read CLAUDE.md files only, so update to v2.1.281 or later for full coverage.
Does AGENTS.md override my CLAUDE.md?
No. Under the default setting, any CLAUDE.md or CLAUDE.local.md in your working directory or above it takes priority and AGENTS.md is not read. To load both, set the Project instructions value to claude-md-and-agents-md — CLAUDE.md loads first in each directory, AGENTS.md after it.
Will my existing AGENTS.md import be read twice now?
No. Anthropic documents that Claude Code skips an AGENTS.md it has already loaded, so keeping an import in your CLAUDE.md never causes a duplicate read on any setting.
Does a subdirectory AGENTS.md load too?
Yes — when Claude reads a file in a subdirectory that has an AGENTS.md and none of the three CLAUDE.md file types of its own, that subdirectory's AGENTS.md loads, mirroring how nested CLAUDE.md files behave.
Verdict on Claude Code AGENTS.md Support
This is the right kind of update: no new syntax to learn, no migration, just one less duplicate file between your repository and a properly instructed agent. If your projects already carry an AGENTS.md for other tools, current Claude Code versions pick it up automatically; if you rely on CLAUDE.md, nothing changes until you say so. Check your version, delete any wrapper files that only exist to point at AGENTS.md, and put the reclaimed maintenance time into automation that actually earns.
If you want to turn Claude Code and agent workflows into a real income stream — with the Agent OS, 1,000+ done-for-you workflows and five live coaching calls a week — check out the AI Profit Boardroom → join here and get building. And if you want a personalised AI SEO roadmap first, book a free SEO strategy session.
