If you use more than one coding agent, you’ve probably hit this. Cursor, Codex, and a pile of other tools read AGENTS.md. Claude Code reads CLAUDE.md. Same project, same instructions, two files. Now every time you tweak one, you have to remember to tweak the other.
There’s a simple fix, and it isn’t a symlink.
The one-line version
Claude Code’s memory files support imports with @path syntax. So at the top of your CLAUDE.md, you just point it at AGENTS.md:
@AGENTS.mdThat’s the whole trick. When Claude Code starts a session, it expands that import and loads everything in AGENTS.md as if it were written directly in CLAUDE.md. You maintain one file. Both agents stay in sync. Nothing to remember.
Adding Claude-specific stuff
The nice part about the import (versus a symlink) is that CLAUDE.md is still its own real file, so you can add instructions that apply only to Claude Code underneath the import:
@AGENTS.md
## Claude Code
Use plan mode for changes under `src/billing/`.Claude loads the imported AGENTS.md first, then appends whatever you write below it. So you get the shared baseline plus a place for the Claude-only notes that wouldn’t make sense for other tools.
What about a symlink?
A symlink works too, and if you have zero Claude-specific instructions it’s perfectly fine:
ln -s AGENTS.md CLAUDE.mdTwo reasons I reach for the import instead. First, the symlink makes CLAUDE.md a literal copy of AGENTS.md, so there’s no room for Claude-only additions. Second, on Windows, creating a symlink needs Administrator privileges or Developer Mode turned on. The @AGENTS.md import has none of that baggage and works the same everywhere.
A couple of things worth knowing
The import resolves relative to the file doing the importing, not your working directory, so @AGENTS.md sitting next to CLAUDE.md in the project root just works. Both relative and absolute paths are allowed, and imported files can import other files up to four hops deep.
The first time Claude Code sees an import in a project, it shows an approval dialog listing the file. Approve it once and you’re done. (For a same-directory file like this, you usually won’t even see friction.)
One more: if you ever want to mention a path in CLAUDE.md without importing it, wrap it in backticks. Writing `@AGENTS.md` keeps it as literal text; @AGENTS.md outside backticks triggers the import.
That’s it. One line, one source of truth, and you never have to diff two instruction files again.
This page may contain affiliate links. Please see my affiliate disclaimer for more info.
