By Jay · September 2026
Claude Code Imports AGENTS.md - Until It Doesn't
AGENTS.md is currently the closest thing to an industry standard Agent interface, used by over 60,000 open-source projects. OpenAI's Codex, Cursor, Pi Agent, and a growing list of other tools all read a project's AGENTS.md file automatically to pick up project-specific instructions - things like coding conventions, style rules, and "don't do this" warnings that live outside the code itself.
Claude Code doesn't. It reads CLAUDE.md. If your repo only has AGENTS.md, Claude Code silently ignores it.
How to inform Claude
Anthropic documents the correct fix for exactly this situation: create a CLAUDE.md that imports the existing file with a single line:
@AGENTS.mdClaude Code's own documentation (code.claude.com/docs/en/memory) describes this as the intended pattern for repos that already use AGENTS.md for other tools - load the shared file, optionally append Claude-specific instructions after it, without duplicating content across two files. A symlink (ln -s AGENTS.md CLAUDE.md) is offered as an alternative, with a caveat that it needs Administrator privileges or Developer Mode on Windows.
A fairly easy (if annoying) fix.
It works great until ...
Claude Code's documentation makes a specific claim about long sessions:
Project-root CLAUDE.md survives compaction: after /compact, Claude re-reads it from disk and re-injects it into the session.
We tested this directly rather than taking it on faith. After setting up the @AGENTS.md import and running /compact, we checked what had actually survived. CLAUDE.md itself did come back into context, exactly as documented - we could see it re-appear as a fresh file read immediately after compaction.
The @AGENTS.md import inside it did not resolve. The one-line pointer survived; the content it was supposed to pull in did not. We only discovered this by deliberately reading AGENTS.md again by hand and noticing it hadn't already been sitting in context on its own.
That's the part worth flagging clearly: the documented safeguard against instruction loss during compaction only covers the file named CLAUDE.md itself. An import pointing at another file is not guaranteed to re-resolve on every compaction event. If your actual rules live in the imported file rather than inline in CLAUDE.md, compaction will quietly drop them again, the exact failure mode the import was supposed to prevent in the first place.
The fix we landed on
Don't rely on the import alone for anything you actually need enforced. Duplicate the critical rules directly into CLAUDE.md, and keep the import as a convenience for tools that read both files:
@AGENTS.md
## Style rules (duplicated here as a safeguard - see AGENTS.md for the source of truth)
- No em-dashes. Never use the em-dash character anywhere in this project...It's redundant on purpose. CLAUDE.md is the one file Claude Code has committed to reliably reloading after compaction. Anything that matters shouldn't depend on an indirection layer that hasn't been shown to survive the same event.
Why this matters beyond one project
AGENTS.md exists specifically so a project's conventions don't need to be re-taught to every coding agent a team uses. Claude Code is, as far as we've tested, the one mainstream coding harness that doesn't read it by default, requiring a project-specific workaround instead. That's a small tax on any team using more than one tool.
The compaction gap is the silent killer though - it works until it suddenly doesn't. Compaction is supposed to be invisible: a context-management mechanic, not a place where your actual project rules quietly go missing.
If you're running Claude Code against a repo that has an existing AGENTS.md, do what we did: add the import, then verify it actually resolves after a /compact, rather than trusting the documentation's claim. If it doesn't resolve for you either, duplicate your critical rules straight into CLAUDE.md and treat the import as a nice-to-have, not a guarantee.
NOTE: this does waste context window by duplicating the same instructions, but you are likely carrying around unused MCP server definitions that are far worse.