How to link CLAUDE.md and AGENTS.md

Two ways to keep one instruction file for every harness

Claude Code reads CLAUDE.md. But Codex, Cursor, GitHub Copilot, OpenCode, Amp, and most of the other agentic harnesses read AGENTS.md.

Some widely shared guides claim Claude falls back to AGENTS.md when CLAUDE.md is missing. It doesn’t. I really wish Anthropic would just adopt the open AGENTS.md standard. But they won’t! Why would they reduce your switching costs :/

If you run more than one harness (I run 4), you either maintain two instruction files that slowly drift apart, or you make one a pointer to the other.

There are two ways to do this:

• Symlink the two files

• Import @AGENTS.md in your @CLAUDE.md

This article will show you how to do both, and how to choose between them.

The quick way to symlink CLAUDE.md and AGENTS.md

If you want to symlink CLAUDE.md and AGENTS.md, it’s actually pretty straightforward.

From the repo root, with AGENTS.md as the real file:

ln -s AGENTS.md CLAUDE.md
git add CLAUDE.md
git commit -m "symlink CLAUDE.md to AGENTS.md"

Then, you can verify it with:

git ls-files -s CLAUDE.md

Mode 120000 means Git stored a symlink. 100644 means you committed a regular file. Then open Claude Code, run /context, and confirm CLAUDE.md is listed under Memory files.

But read on to learn how to use an @import in your CLAUDE.md to make this link more reliable.

Why AGENTS.md should be the source of truth

You should absolutely point CLAUDE.md at AGENTS.md, not the reverse.

AGENTS.md is the file most harnesses read natively, including cloud agents that clone your repo on infrastructure you don't control. The canonical file should be the one that works with zero configuration.

Beyond that, Claude Code's @path/to/file imports aren't part of the AGENTS.md convention. Copilot CLI and Gemini CLI happen to support @ references too, but Codex's AGENTS.md docs describe no import mechanism, so to Codex an import line is just text. Keep the canonical file as plain markdown so it stays portable.

If you’re curious about customizing coding agents, you’re obviously in the right spot. I spend dozens of hours researching each of these guides so you have a shortcut to building software with AI.

I’d love to have you join us and get notified when we share more tutorials like this.

Thank you for being a reader of The AI-Augmented Engineer! Deep tutorials like this are exclusive to paid members of the newsletter. This support makes it possible for me to do the research and prep necessary to deliver value-packed guides like this.

I’d love to have you join our almost 200 members!

Import @AGENTS.md in your CLAUDE.md