Claude Code AGENTS.md support finally landed this week. If your project folder has an AGENTS.md file that Claude Code ignored for months, the symlink tricks can retire, and the fix takes about two minutes.
What actually changed in Claude Code AGENTS.md support
The official Claude Code changelog says it straight: in a project with no CLAUDE.md, Claude Code now reads AGENTS.md instead. The change shipped in version 2.1.277 on September 18, 2026, and you can adjust the behavior under “Project instructions” in the /config menu.
If you’ve never hit this problem, here’s the deal. AGENTS.md is an open file format for giving AI coding agents instructions. Think of it as a README, but the reader is a robot. Build commands, test routines, style rules, things the agent should never touch. It started as a community convention and grew into a real standard: OpenAI Codex, GitHub Copilot, Cursor, Aider, Windsurf, and others read it natively, and it’s now stewarded under the Linux Foundation’s Agentic AI Foundation.
Claude Code was the stubborn one. It only read its own CLAUDE.md file. The GitHub issue asking for AGENTS.md support collected over 5,200 reactions, one of the loudest feature requests in the entire tracker.
Why this matters even if you work alone
Two scenarios make this worth your time.
First, mixed teams. Your teammate or your CI uses Codex, you use Claude Code. Before, you either kept two instruction files in sync by hand or hoped nobody forgot an update. Now one AGENTS.md serves both tools, so the instructions stay identical automatically.
Second, borrowed repos. You clone a project that already has an AGENTS.md with build steps and warnings. With the new release, Claude Code picks it up on its own. No more discovering the hard way that the agent skipped the migration step the file explicitly warned about.
One developer on Hacker News described asking Claude Code to “follow the instructions in this directory” in a folder with only an AGENTS.md. It found nothing. That failure mode is gone now.
The road to this release
The community asked for this for a long time. Issue #6235 opened back in August 2025 and snowballed into the most-upvoted request in the Claude Code tracker, with hundreds of comments debating formats and precedence rules.
While Anthropic stayed quiet, developers engineered workarounds. The popular one: a CLAUDE.md containing a single line, @AGENTS.md, which tells Claude Code to import the open-standard file. Windows users without symlink permissions leaned on that trick hard. Others symlinked CLAUDE.md to AGENTS.md so both names pointed at the same real file. Claude Code AGENTS.md support makes all of that plumbing optional instead of mandatory.
AGENTS.md vs CLAUDE.md: which one wins?
Quick comparison, since the two files now coexist in the same tool:
| AGENTS.md | CLAUDE.md | |
|---|---|---|
| Who reads it | Codex, Copilot, Cursor, Aider, Windsurf, and now Claude Code as fallback | Claude Code only |
| Format | Open standard under the Linux Foundation | Claude-specific, supports @imports and auto memory |
| Priority in Claude Code | Fallback | Wins when both exist |
| Best for | Shared rules across every tool your team uses | Claude-only notes, imports, personal overrides |
Bottom line: keep CLAUDE.md if you have one, since it still takes priority. Otherwise, one AGENTS.md now covers the whole toolbox.
How to set it up in two minutes
Nothing to install. If your Claude Code is updated to 2.1.277 or later, it just works. Here’s the checklist:
Step 1: Update Claude Code. Run claude –version to confirm you’re on 2.1.277 or newer. If not, update your install first.
Step 2: Check what’s in your project. If you already have a CLAUDE.md, keep it. CLAUDE.md still wins when both files exist, so your existing setup keeps working exactly as before.
Step 3: No CLAUDE.md? Drop an AGENTS.md in your project root. Claude Code reads it automatically at session start.
Step 4: Want to change how it loads? Open /config and look under “Project instructions.”
Step 5: Windows or a repo where you can’t add files? The old workaround still works: put a single line, @AGENTS.md, inside CLAUDE.md, and Claude Code imports it.
Step 6: Verify. Start a session and ask “which instruction files did you load?” You should get AGENTS.md back, along with its rule count.
One caveat for enterprise users: the changelog notes the feature is not yet available on Bedrock, Vertex, or Foundry. If your company runs Claude Code through one of those platforms, you’re on the old behavior until further notice.
What goes inside the file
A good AGENTS.md is short and bossy. Agents do better with clear rules than with essays. A solid starter:
## Build
- npm run build
## Test
- npm test
## Rules
- Never edit files in generated/
- Run tests before claiming done
- Follow existing code style, no refactorsKeep it under a page. Long files dilute the rules that matter, and the agent’s context window is not infinite. If a rule only matters for one folder, some tools support nested AGENTS.md files per directory, so put the rule where it applies.
The bigger shift: one file, every agent
Zoom out, because this change is about more than one tool. The industry has been consolidating on shared instruction files instead of per-vendor ones. When Anthropic, OpenAI, and Block joined the Linux Foundation effort to standardize agent instructions, the direction got obvious. Claude Code joining the party makes AGENTS.md the closest thing coding agents have to a universal config.
Practical effect for you: write your rules once. When a new agent tool shows up next quarter, odds are decent it already speaks the same file. Your setup cost drops to zero, and your rules stop drifting between tools. Claude Code AGENTS.md support is the loudest signal yet that per-vendor config files are on their way out.
Common questions, answered briefly
Does CLAUDE.md still take priority? Yes. The new support is a fallback. If both files exist, Claude Code reads CLAUDE.md and ignores the rest.
Do I need to delete my CLAUDE.md? No. If it imports AGENTS.md with the @AGENTS.md line, you can keep the same setup running. Plenty of teams will.
Which version shipped Claude Code AGENTS.md support? Version 2.1.277, released September 18, 2026. Anything older ignores the file.
Is my project too small for this? If an agent touches it, rules help. Even a five-line file with build and test commands saves the agent from guessing.
Start today
Update Claude Code, check your projects for AGENTS.md files you’ve been ignoring, and consolidate your duplicate instruction files into one. The symlink tricks can retire.
Want to go deeper on Claude Code? Learn the /goal command that keeps long tasks on track, see how hooks stop AI mistakes before they happen, or browse everyday tasks Claude Code can handle without any programming background. One instruction file, fewer surprises: that’s the whole game.
