AGENTS.md and Claude Code: How to Use One File for Every Tool
The whole promise of AGENTS.md is one file every agent reads — and most major tools deliver on it natively. The one important exception is Claude Code, which reads its own file, CLAUDE.md, and as of this writing does not read AGENTS.md natively. The fix is a single line: a symlink that lets one real file serve both names with zero duplication and zero drift.
What Works Without Any Setup
Across most of the ecosystem you write AGENTS.md once and it simply works. Codex, Cursor, GitHub Copilot, Gemini CLI, Devin, Factory, Jules, Amp, VS Code and Windsurf all read it as their project context with no extra step. For a team standardising on the file, that is the entire payoff: a single source of truth every agent honours.
The Claude Code Exception
Claude Code is the notable holdout. There is a long-standing community request to add native AGENTS.md support — an open issue with thousands of upvotes — but no committed timeline. Until then, you cannot rely on Claude Code picking up an AGENTS.md on its own.
The One-Line Fix
Keep one real file, AGENTS.md, and create a symbolic link named CLAUDE.md that points at it. Both names now resolve to the same content on disk, so Claude Code reads "its" file and every other tool reads AGENTS.md:
$ ln -s AGENTS.md CLAUDE.mdNever Keep Two Real Copies
The tempting alternative — maintaining a separate AGENTS.md and a separate CLAUDE.md with the same content — is the one approach to avoid. Two real files drift the first time someone updates one and not the other, and then your tools are quietly working from different instructions. A symlink is one file; two copies is a bug waiting to happen. On Windows, note that Git may need developer mode to create symlinks, and a checked-out link can arrive as a plain text file — recreate it after enabling symlink support if so.
Commit the Link
Most teams commit the symlink directly so it is present for everyone on clone. A cleaner-looking alternative is to gitignore it and recreate it with a setup script, at the cost of a little onboarding friction. Either is defensible; committing it is the simpler default.