Should I rename CLAUDE.md to AGENTS.md?
Not quite. Move the shared content to AGENTS.md, then keep a short CLAUDE.md containing @AGENTS.md. With only AGENTS.md, Claude Code reads it, but adding any CLAUDE.md later silently stops that by default.
CLAUDE.md is Claude Code's own file; AGENTS.md is the open format most other agents read. If your team uses more than one agent, the answer is both: AGENTS.md as the source, CLAUDE.md as a one-line import.
Both are plain Markdown instruction files at the repository root. The difference is who reads them. Last verified 2026-11-13 against the vendor documentation.
| CLAUDE.md | AGENTS.md | |
|---|---|---|
| Primary reader | Claude Code | Codex, Cursor, Windsurf, Jules, Zed, Cline and others |
| Also read by | Copilot cloud agent, code review and CLI; Zed | Copilot cloud agent, code review, CLI and VS Code chat; Claude Code when no CLAUDE.md exists |
| Imports | Yes, @path, up to 4 hops | No import syntax in the format |
| Private variant | CLAUDE.local.md | AGENTS.local.md (Windsurf), AGENTS.override.md (Codex) |
| Governance | Anthropic product feature | Open format, stewarded by the Agentic AI Foundation |
Since v2.1.277, Claude Code can read AGENTS.md, but by default only when there is no CLAUDE.md or CLAUDE.local.md in the working directory or above it. As soon as you add a CLAUDE.md, AGENTS.md is skipped unless you change the Project instructions setting to claude-md-and-agents-md. That default is why a CLAUDE.md that imports AGENTS.md is the most predictable setup.
Even then, naming the shared file AGENTS.md costs nothing and keeps the door open.
This is the setup 2prompt's generator produces: a full AGENTS.md and thin wrappers that point to it.
Keep the content in AGENTS.md and make CLAUDE.md a pointer:
# CLAUDE.md
@AGENTS.md
## Claude Code
- The shared project instructions are imported from AGENTS.md on the line above. Edit AGENTS.md, not this file, so every agent stays in sync.
- Put Claude-only preferences below this line. Personal, uncommitted notes belong in CLAUDE.local.md.Do not also switch Claude Code to claude-md-and-agents-md, or AGENTS.md loads twice. A symlink from CLAUDE.md to AGENTS.md is the other option the Claude Code docs mention, though imports are more portable on Windows.
The most common failure is quiet drift. Someone fixes the test command in CLAUDE.md, nobody updates AGENTS.md, and a teammate using Codex keeps running the old command. A second failure is surprise: a project that worked with only AGENTS.md stops sharing it with Claude Code the day someone adds a CLAUDE.md for a personal note.
Both problems disappear once AGENTS.md is the only file with shared content and CLAUDE.md is a one-line import.
A quick audit helps: search the repository for every instruction file, list what each contains, and check that only AGENTS.md carries shared rules.
Details on each file: CLAUDE.md format and AGENTS.md format.
Not quite. Move the shared content to AGENTS.md, then keep a short CLAUDE.md containing @AGENTS.md. With only AGENTS.md, Claude Code reads it, but adding any CLAUDE.md later silently stops that by default.
Only if you both import AGENTS.md from CLAUDE.md and set the Project instructions option to load CLAUDE.md and AGENTS.md together. Pick one of the two approaches.
Copilot cloud agent, code review and CLI read both AGENTS.md and CLAUDE.md. VS Code chat reads AGENTS.md. Copilot Chat on GitHub.com reads neither and uses copilot-instructions.md.
It is not better written, just more widely read. CLAUDE.md has useful features like imports and a local variant. AGENTS.md reaches more agents, which is why it makes a good single source with CLAUDE.md importing it.