One AGENTS.md, every tool: the Claude Code symlink pattern

The promise and the one exception

Most agents read AGENTS.md natively — Codex, Cursor, Copilot, Gemini CLI, and more. Write it once, it just works. The exception is Claude Code, which reads CLAUDE.md and (as of now) doesn't read AGENTS.md natively.

The fix is one line

Keep one real file. Point the other name at it:

$ ln -s AGENTS.md CLAUDE.md

One file on disk, two filenames. Claude Code reads CLAUDE.md, everything else reads AGENTS.md, and since they're the same bytes they can't drift.

Don't keep two real copies

# DON'T: two real files with the same content
AGENTS.md
CLAUDE.md   # a separate copy → drifts the first time you edit one

Every team that manually syncs two copies eventually ships mismatched instructions. A symlink makes that impossible.

Monorepo + Windows notes

• Monorepo: repeat the symlink at each level that has an AGENTS.md.
• Windows: Git may need developer mode for symlinks; if a link checks out as a text file, recreate it after enabling symlink support.

Commit it

Commit the symlink so it's present on clone — or gitignore and recreate it via a setup script. Committing is the simpler default.

Free cheat sheet: the format, an annotated example, and the one-line test — AGENTS.md Cheat Sheet.

Go deeper: the full reference — cross-tool setup, the monorepo hierarchy, and a 30-day plan — AGENTS.md: The Complete Guide to the Cross-Tool Agent Standard.

Team using Claude Code alongside other agents — are you symlinking, or still syncing by hand? 👇