Claude Code AGENTS.md: What Actually Loads

On August 17 the most-upvoted issue in the Claude Code repository got closed. Not shipped: closed, with a two-sentence reply pointing at a workaround. Issue #6235 had asked for AGENTS.md support, collected 4,667 thumbs-up over almost exactly a year, and drew 361 comments before an Anthropic collaborator resolved it as completed. If you went looking for Claude Code AGENTS.md support this week and landed in a thread full of irritated developers, this is the actual state of things as of 2026-08-20, checked against the documentation rather than the thread.

Key Takeaways:

• Claude Code does not read AGENTS.md natively. The documentation states it plainly, and issue #6235 was closed on 2026-08-17 with a workaround rather than a feature.
• Use @AGENTS.md inside a CLAUDE.md rather than a symlink. It works on Windows without Administrator rights and leaves room for Claude-specific instructions underneath.
• Imports do not save context. Imported files load at launch, so an AGENTS.md pulled in this way costs the same tokens it would have cost inline.
• Monorepos need generated stubs and a CI check. One CLAUDE.md per AGENTS.md is unmaintainable by hand once the count passes a handful.
• Confirm with /context, not by assumption. Look under Memory files; ln -s prints nothing on success and a missing file looks identical to a loaded one from the outside.
• Commit the wiring, don't leave it local. Claude Code AGENTS.md setup that lives only on your laptop is invisible to CI, containers and every teammate who clones the repo after you.

What actually happened on August 17

The issue was opened on 2025-08-21 by a developer whose complaint was short and hard to argue with: Codex, Amp and Cursor were converging on one file, and CLAUDE.md doesn't travel well to teammates who use something else. It sat open for a year while the reaction count climbed past six thousand.

At 03:37 UTC on 2026-08-17, collaborator bcherny closed it as completed with this comment, quoted in full:

Claude Code reads CLAUDE.md, but you can share one file with other agents: create a CLAUDE.md containing just @AGENTS.md (an import), or symlink CLAUDE.md to AGENTS.md. Claude then loads your AGENTS.md at session start.

Two details in that screenshot did most of the damage. The close carries a "🤖 Generated with Claude Code" signature, and the linked pull request in the Development panel belongs to Piebald-AI/tweakcc, a third-party tool, not to anthropics/claude-code. A commenter asked the obvious question within hours: how did this get closed via someone else's repo? No changelog entry accompanied it either. I checked every Claude Code release published between 2026-08-06 and 2026-08-20 and none of them mentions AGENTS.md.

The one-line answer

Skip the thread and read the documentation, which is blunt about it. The memory page now carries a section headed AGENTS.md, and the first sentence is: "Claude Code reads CLAUDE.md, not AGENTS.md."

So the answer to the Claude Code AGENTS.md question is no. There is no native support, no fallback, no automatic discovery. What exists is a documented way to make one file serve both tools, which is a different thing and worth being precise about, because a lot of secondhand summaries this week claimed Claude Code "reads AGENTS.md as a fallback." It doesn't.

Two ways to point Claude Code at AGENTS.md

The documented patterns both work, and they behave differently in ways that matter later.

The import is a CLAUDE.md whose entire contents can be one line:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

Claude loads the imported file at session start, then appends whatever you wrote below it. That second part is the reason to prefer this over a symlink: you get a place for the handful of instructions that genuinely are Claude-specific without polluting the shared file.

The symlink is one command and carries no Claude-specific section:

ln -s AGENTS.md CLAUDE.md

It prints nothing on success, which trips people up. Run /context in your next session and look under Memory files to confirm it loaded; that's the only check that tells you the truth, and it's the step most of the angry thread skipped. On Windows the symlink needs Administrator rights or Developer Mode, so teams with mixed machines should standardise on the import and stop thinking about it.

Two commands sit alongside these. Running /init with CLAUDE_CODE_NEW_INIT=1 set will read an existing AGENTS.md while generating your CLAUDE.md, and /import copies a supported agent's configuration across, including instruction files, carrying MCP servers and skills with it. That one needs v2.1.213 or later. Neither is a substitute for the import line, since both produce a one-time copy that drifts the moment somebody edits the original.

Whichever you pick, commit it. The failure everyone hits with Claude Code AGENTS.md setup is treating it as local configuration: a symlink made on one machine is invisible to every other checkout, and the person who ends up debugging that is whoever joins the project next.

What the workaround doesn't fix

Here's where the closure starts looking premature rather than merely undocumented.

Nested files are the real problem. AGENTS.md is a repo-wide convention in name only, because a repo of any size doesn't have one AGENTS.md; it has one per package. One commenter on the thread pointed out that OpenAI's main repository carries 88 of them, which under the import pattern means 88 matching stub CLAUDE.md files, plus the discipline to create the eighty-ninth the day someone adds a new package. Nobody maintains that by hand for long. A one-file repo is fine; a monorepo is not.

Context cost is the second one, and it cuts the other way. The docs are explicit that splitting instructions into @path imports helps organisation but doesn't reduce context, since imported files load at launch regardless. Anyone who assumed the import trick would keep AGENTS.md out of the context window until needed has it backwards. Kent C. Dodds flagged a related finding on August 13: a paper evaluating AGENTS.md files found they often don't improve task success while adding more than 20% to inference cost. That's a genuine argument for Anthropic taking its time here, and it deserves stating even though it wasn't the argument Anthropic made.

Then there's everything that isn't the instruction file. Skills, subagents, commands and hooks still live under .claude/, and a team sharing a repo across Codex and Claude Code ends up symlinking those directories one by one. Solving the Claude Code AGENTS.md problem at the instruction-file layer leaves that whole second tier untouched, which is why the developers who migrated properly this week describe it as an afternoon rather than a ten-second fix. One of them spent two hours on it and said so in the thread. If you're thinking through what belongs in a shared instruction file versus what should load on demand, our notes on context engineering for AI agents cover the tradeoff in more depth.

That second tier is also where tool sprawl gets expensive, and it's the reason MoClaw is deliberately not another config format to maintain: it runs as a hosted cloud AI computer alongside whatever you've already wired up, so adopting it doesn't add a fifth directory of rules to keep in sync with the other four.

Why the anger is about the close, not the feature

Read the last twenty comments and almost none of them argue that the workaround doesn't function. They argue about being closed as completed. "Completed" is a claim that the request was satisfied, and a symlink that users had already been running for months isn't the thing 4,667 people voted for. A separate issue, #34235, asked for the same feature in March and is still open with 110 reactions, which makes the resolution look more like inbox management than a decision.

This matters beyond one repo, and not because Anthropic did something unusual. Every coding agent is currently making the same bet: that its own config format is worth the friction it imposes on a team using four tools. Cursor kept .cursor/rules/. Copilot kept .github/copilot-instructions.md. Claude Code kept CLAUDE.md. Armin Ronacher, who maintains a good deal of Python's tooling, mentioned on August 16 that he'd deleted the CLAUDE.md files from his repos and found that simply telling Claude Code to go read AGENTS.md worked well enough. That's a reasonable position and also an admission that the file question is unsettled.

The part worth planning around is that your instruction files now have a lifespan measured against somebody else's roadmap. A symlink created on your MacBook doesn't exist in CI, doesn't exist in a fresh container, and doesn't exist on the Windows laptop your new teammate got issued. This is the specific gap MoClaw fills: a hosted cloud AI computer where the environment holding your symlinks, your .claude/ directory and your imports is set up once and stays set up, sitting alongside your local install rather than replacing it.

What to do this week

If your repo already has an AGENTS.md, add a CLAUDE.md containing @AGENTS.md and commit it. Ten seconds, survives everything, works on Windows.

If you maintain a monorepo, don't hand-write stubs. Generate them, and add a check to CI that fails when an AGENTS.md has no sibling CLAUDE.md; that's five lines of shell and it removes the failure mode where someone's new package silently gets no instructions at all.

Verify rather than assume. /context under Memory files is the ground truth, and CLAUDE.md content is delivered as a user message after the system prompt, so it shapes behaviour without guaranteeing compliance. For rules that must hold every time, the docs point you at a PreToolUse hook instead of a paragraph of prose.

The last one is about where the agent runs, not what it reads. Unattended runs are where file-resolution assumptions break: a scheduled job at 3am doesn't get to re-run /init when it discovers the symlink didn't come along. Keeping that work on MoClaw means the box that resolves your instruction files is the same box every night, which is a boring property until the night it isn't. We wrote about the broader version of that problem in running agents in parallel with humans.

FAQ

Does Claude Code read AGENTS.md?

No. As of 2026-08-20 the documentation says "Claude Code reads CLAUDE.md, not AGENTS.md." Claims that it reads AGENTS.md as a fallback are wrong.

Was issue #6235 actually implemented?

No. It was closed as completed on 2026-08-17 with a comment describing the import and symlink workarounds. No Claude Code release note between 2026-08-06 and 2026-08-20 mentions AGENTS.md, and issue #34235 requesting the same feature remains open.

What's the difference between the import and the symlink?

The import lets you add Claude-specific instructions below the @AGENTS.md line; the symlink makes the two files literally identical. The symlink also requires Administrator privileges or Developer Mode on Windows.

Will the import reduce my context usage?

No. Imported files are expanded and loaded at launch alongside the CLAUDE.md that references them, so the token cost is the same as pasting the content in directly.

How do I check whether my AGENTS.md actually loaded?

Run /context in a session and look at the list under Memory files. If CLAUDE.md isn't there, Claude can't see it, whatever the file system says.

Does this work for nested AGENTS.md files in a monorepo?

Only with one stub CLAUDE.md per directory. Claude Code walks up the directory tree from your working directory and loads subdirectory files on demand when it reads files there, so each AGENTS.md needs its own sibling.

Is there a Claude Code AGENTS.md plugin?

Community plugins exist, and the pull request linked to the closure of #6235 lives in the third-party tweakcc project rather than in Claude Code itself. Anything outside the repository patches the CLI at your own risk and breaks on upgrades, so the documented import remains the safer route for a shared team repo.

Can I bring my whole Codex setup over instead?

Partly. /import appends a one-time copy of instruction files such as AGENTS.md to the matching CLAUDE.md and carries over MCP servers, commands, subagents and skills. It needs Claude Code v2.1.213 or later, and the copy doesn't stay in sync afterwards.