Update to Claude Code version 2.1.277 or later and any project that has no CLAUDE.md file now reads AGENTS.md as its project instructions instead — that is the core of the new Claude Code AGENTS.md support, shipped on 18 September 2026 according to the official Claude Code changelog. You do not have to rename anything, migrate anything or duplicate a single line: if a CLAUDE.md exists, Claude Code behaves exactly as before, and if it does not, the AGENTS.md that other coding agents already use becomes the source of truth. For anyone running Claude Code alongside other AI coding tools in the same repositories, this quietly removes one of the most annoying bits of duplication in the whole workflow.
📺 Watch: Claude Code Just Got a HUGE Customization Upgrade
🔥 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 →
Everything below comes straight from the changelog entry for version 2.1.277, dated 18 September 2026, plus the surrounding release notes Anthropic published the same week. You will see what the feature does, the exact precedence rule, how to change the behaviour in your settings, and where the feature has not rolled out yet — so you can decide in about two minutes whether your repositories need any changes at all.
What Claude Code AGENTS.md Support Actually Does
The changelog wording is short and worth reading as written: "in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead". AGENTS.md is the plain-markdown convention a growing number of AI coding tools use for repository-level agent instructions — the build commands, style rules, folder conventions and do-not-touch warnings you want every agent to respect. CLAUDE.md has always been Claude Code's own version of that file, and it still is.
What changed on 18 September 2026 is the fallback. Before 2.1.277, a repository that only carried an AGENTS.md was invisible to Claude Code's instruction loading: you either created a CLAUDE.md as well or went without project instructions. After 2.1.277, that AGENTS.md is picked up automatically whenever no CLAUDE.md exists. Teams that standardised on AGENTS.md for every tool now get Claude Code reading the same playbook with zero extra files, and open-source maintainers who kept both files in sync can retire one of them whenever they choose.
The Precedence Rule: CLAUDE.md Still Wins
The precedence logic in Claude Code is deliberately simple, and it matters because it means nothing breaks for existing projects. If a CLAUDE.md is present in the project, Claude Code reads it exactly as it always has, and the AGENTS.md — if one also exists — is ignored for instruction loading. Only when the project has no CLAUDE.md at all does the new AGENTS.md fallback kick in. The changelog frames the whole feature around that one condition: "in a project with no CLAUDE.md".
Practically, that gives you three clean setups. Projects that are Claude-Code-first keep a CLAUDE.md and change nothing. Projects that serve several different coding agents keep a single AGENTS.md and let every tool, Claude Code now included, read the same instructions. And projects that genuinely need tool-specific behaviour keep both files, knowing Claude Code will prefer its own. If you are still deciding how deep to go on instruction files in general, the walkthrough in learn Claude Code covers where project instructions sit in the wider setup.
If you want your whole agent stack configured once — instruction files, workflows and prompts that just work across every project — check out the AI Profit Boardroom → Get the full Agent OS stack. Want AI SEO help 1-on-1 instead? Book a free SEO strategy session and get a plan built around your business.
How To Switch Project Instructions In /config
The behaviour is not hard-wired. The same changelog entry notes you can "change it under 'Project instructions' in /config". Open Claude Code in the project, run the /config command, and look for the Project instructions setting — that is where you control which file Claude Code treats as the project's instruction source. The default after updating gives you the fallback behaviour described above, so most people never need to touch the setting at all.
The switch earns its keep in edge cases. Maybe your repository carries an AGENTS.md written for a very different tool, full of instructions that make no sense for Claude Code, and you would rather Claude Code ignore it. Or maybe you are mid-migration and want to test how the AGENTS.md reads before deleting your CLAUDE.md. Either way, the control lives in /config rather than in another file you have to remember, which is consistent with how recent Claude Code releases have handled configuration — the same settings-first approach covered in the Claude Code no-flicker mode write-up.
Why AGENTS.md Matters If You Run More Than One Coding Agent
The real value of Claude Code AGENTS.md support shows up the moment your stack includes more than one agent. Instruction drift is the failure mode: you update the build command in one tool's file, forget the other, and a week later an agent confidently runs the old command. One shared AGENTS.md means one place to state the rules — how to run tests, which directories are generated, what the commit conventions are — and every agent that respects the convention stays current, Claude Code now among them.
That consolidation thinking is the same idea behind treating your whole setup as one system rather than a pile of tools. The Agent OS guide shows how project-level instructions slot in alongside memory and orchestration as part of a full agent operating system, and the Hermes memory system page covers the file-based equivalent on the Hermes side — different agent, same principle that plain files you control beat scattered per-tool settings. If your agents produce work at volume, one instruction file that all of them obey is the difference between a team and a mess.
Where AGENTS.md Support Has Not Landed Yet
One caveat comes directly from the changelog: the feature is "not yet on Bedrock, Vertex or Foundry". If your organisation runs Claude Code through Amazon Bedrock, Google Vertex AI or Microsoft Foundry rather than through the Claude API directly, AGENTS.md fallback has not reached you as of the 18 September 2026 release, and your projects should keep their CLAUDE.md files for now. The changelog does not give a date for those platforms, so watch the release notes rather than assuming.
It is also worth being clear about what the feature does not do, because the release notes do not claim it. It does not merge the two files, it does not convert one format to the other, and it does not change anything about how instructions are interpreted once loaded — it only changes which file gets read when CLAUDE.md is absent. The same September releases carried plenty of other changes, from AGENTS.md's sibling fixes to the remote-session improvements covered in Claude Code fast mode for remote sessions, so the instruction-file change is one piece of a busy month rather than the whole story.
Quick Reference: How Claude Code Picks Its Instructions
| Your project has | What Claude Code 2.1.277+ reads |
|---|---|
| CLAUDE.md only | CLAUDE.md, exactly as before |
| CLAUDE.md and AGENTS.md | CLAUDE.md — the AGENTS.md is not used for instructions |
| AGENTS.md only | AGENTS.md, via the new fallback |
| Neither file | No project instructions, as before |
| Any of the above on Bedrock, Vertex or Foundry | CLAUDE.md only — AGENTS.md support has not shipped there yet |
📺 Watch: NEW Claude Update ACTUALLY CHANGES EVERYTHING!
Claude Code AGENTS.md FAQs
What version added Claude Code AGENTS.md support?
Version 2.1.277, dated 18 September 2026 in the official Claude Code changelog. Update to that version or later and the fallback is active by default, with the behaviour adjustable under Project instructions in /config.
Does AGENTS.md override my CLAUDE.md?
No. The fallback only applies in a project with no CLAUDE.md. If both files exist, Claude Code reads CLAUDE.md and ignores AGENTS.md for instruction loading, so existing projects behave exactly as they did before the update.
Should I delete my CLAUDE.md and switch to AGENTS.md?
Only if you run several coding agents against the same repositories and want one shared instruction file. If Claude Code is your only agent, there is no advantage to renaming — CLAUDE.md remains fully supported and is still what Claude Code prefers.
Does this work on Bedrock, Vertex or Foundry?
Not yet. The changelog states the feature is not yet available on Bedrock, Vertex or Foundry, so teams on those platforms should keep their CLAUDE.md files and watch future release notes for the rollout.
Can I control which file Claude Code uses?
Yes. The changelog points to the Project instructions option in /config, which is where you change how Claude Code sources instructions for the current project if the default fallback is not what you want.
Verdict: A Small Change That Removes Real Friction
Claude Code AGENTS.md support is not a headline feature, and that is precisely why it is worth acting on — it deletes a maintenance chore rather than adding a capability you must learn. If you keep duplicate instruction files today, you can consolidate to one AGENTS.md and trust the fallback; if you are Claude-Code-only, you change nothing and lose nothing. When you want to compare how the models behind these agents actually stack up before you push more work through them, the Goldie Bench write-up covers how the current crop of brains compares in hands-on tests. Either way, fewer files carrying the same words is the right direction, and this release gets you there in one update.
If you want agents that ship real client work from day one — with the instruction files, prompt libraries and workflows already built — check out the AI Profit Boardroom → Join 3,000+ AI operators inside. And if you would rather talk it through first, book a free SEO strategy session and map your next 90 days.
