CLAUDE.md vs AGENTS.md
The short answer
CLAUDE.md is the instructions file Claude Code is built around. AGENTS.md is an open format that Cursor, Codex and Grok document reading, and that Claude Code can read too. If you run more than one agent, keep your shared rules in one AGENTS.md and have CLAUDE.md import it with an @AGENTS.md line.
CLAUDE.md and AGENTS.md are both plain Markdown files of standing instructions for coding agents. CLAUDE.md is the file Claude Code is built around. AGENTS.md is an open format that several agents read. The question is which files your agents read, and how to avoid keeping the same rules twice.
TL;DR
- Same kind of file, different readers. Each vendor's docs say which file its agent reads.
- Running more than one agent: keep the shared rules in one AGENTS.md. Claude Code now reads it directly; add a CLAUDE.md that imports it only for Claude-specific lines.
- Running only Claude Code: a CLAUDE.md alone is fine. See CLAUDE.md best practices.
- Neither file is the place for this week's priorities, customer evidence or one job's spec.
When to use this: you use two or more coding agents on one repository. When not: you use one agent. Use that agent's file and skip the rest.
Which file does each agent read?
This is what each vendor's own documentation says. It was checked against those pages on 21 October 2026, and the tools change, so check the linked page for yours.
| Agent | What its docs say |
|---|---|
| Claude Code | Reads CLAUDE.md files. It "can read AGENTS.md as your project instructions", by default only when there is no CLAUDE.md in your working directory or above it. A CLAUDE.md can import AGENTS.md. |
| Cursor | "Cursor supports AGENTS.md in the project root and subdirectories." Nested files are combined with parent directories, and more specific instructions take precedence. |
| Codex | "Codex reads AGENTS.md files before doing any work." It walks from the project root toward your current directory, and files closer to you override earlier guidance. |
| Grok | Project rules are "Markdown files that Grok loads into context for every session in a directory tree", and the docs suggest an AGENTS.md at the repo root. Grok also reads CLAUDE.md files in each directory. |
Sources: Anthropic, Cursor, Codex and xAI. The agents.md site keeps a longer list of tools that support the format.
What is the difference between the two files?
Not much in content. Both hold commands, conventions, layout and boundaries. The differences are practical:
- Who reads it. CLAUDE.md is Claude Code's file. AGENTS.md is the one several agents document reading.
- Where it can sit. CLAUDE.md can be a project file, a personal file in your home folder, or a private CLAUDE.local.md that you keep out of git. Cursor, Codex and Grok each document how they find AGENTS.md in subdirectories.
- What is specific to Claude Code. Imports with @path, path-scoped rules and a managed organization file are Claude Code features. They have no place in a file other agents also read.
When should I keep both?
Keep both when you use Claude Code alongside other agents, and you want Claude-specific lines such as "use plan mode for changes under src/billing/". Anthropic's docs say that when both files exist and the CLAUDE.md does not import the AGENTS.md, Claude reads the CLAUDE.md files only. So a CLAUDE.md without the import quietly hides your shared rules from Claude Code.
If you only use Claude Code, keep a CLAUDE.md. If you do not use Claude Code, keep an AGENTS.md. Do not add a file for an agent you do not run.
How do I keep one source of truth?
Put the shared rules in AGENTS.md. Claude Code now reads AGENTS.md directly when there is no CLAUDE.md (v2.1.277 or later), so AGENTS.md alone works for every agent. If you want Claude-specific lines, make CLAUDE.md a thin file that imports it. Anthropic's docs show this:
- Create a CLAUDE.md next to your AGENTS.md.
- Put @AGENTS.md on the first line.
- Add any Claude-specific lines below it.
Claude reads the imported file first, then the rest. The docs also show a symlink (ln -s AGENTS.md CLAUDE.md) if you need no Claude-specific content, but note two limits: Claude's edit tools will not write through the link, and on Windows a committed symlink can check out as a one-line text file. If anyone on your team uses Windows, use the import.
After setting up either, run /context in your next session and confirm CLAUDE.md appears under Memory files.
A minimal AGENTS.md and the CLAUDE.md that imports it
Two files. The first is the shared rules, short enough to read in a minute. The second is the whole CLAUDE.md for a team that wants nothing Claude-specific.
# AGENTS.md
## Project
<One line: what this is.>
## Commands
- Install: <command>
- Test: <command>. Run it before every commit.
- Lint: <command>
## Conventions
- <A rule you can check>
- <A rule you can check>
## Project layout
- <folder>: <what lives there>
## Do not touch
- <generated or vendored folder>
- <anything that needs a person's yes first>
---
# CLAUDE.md (same repository, next to AGENTS.md)
@AGENTS.md
How do I move from one file to the other?
- You have a CLAUDE.md and add Cursor, Codex or Grok. Rename it AGENTS.md, then create a new CLAUDE.md that imports it. The agents.md site suggests the same move: rename the file and keep a link under the old name.
- You have an AGENTS.md and add Claude Code. Nothing to do at first: Claude reads it when there is no CLAUDE.md. Add a CLAUDE.md with the import when you want Claude-specific lines.
- You have two diverging copies. Pick the more accurate one as AGENTS.md, diff the other against it, and keep only the lines that are specific to one agent.
What are neither of these files for?
Both are for how you work. Neither is for:
- What to build next. Priorities change weekly. A rules file is read at the start of every session, so a stale one misleads every session.
- Customer evidence. Quotes, accounts and revenue back a decision, and belong with the priority.
- One job's spec. The why, the files and the Done When lines for one piece of work. See how to write a PRD for Claude Code.
- Enforcement. Anthropic's docs say Claude treats CLAUDE.md as context, not enforced configuration. To block an action, use a hook or a permission, not a sentence.
Where does Annsa fit?
The rules file holds how you work. Annsa holds what to build next and why. It is the source of direction for your agents.
- Ranked priorities from feedback that arrives from Slack, Intercom, call transcripts, surveys, imports, GitHub, the API or by hand, each with the exact words, the account and its revenue. Inside your bets, in your order, what a person marked broken comes first, then what customers asked for, then ideas.
- A spec on each priority: the why, the evidence and Done When lines. Your agent or Ask writes it.
- The same list for every agent. Claude Code, Cursor, Codex and Grok connect over MCP (remote, nothing to install), claim the work, read the spec and record evidence against each Done When line.
- Decide once. A decision saved as a principle is read by every agent.
Annsa does not edit your CLAUDE.md or AGENTS.md. See how to give AI coding agents product context, context engineering and what a coding agent is.
Sources: How Claude remembers your project, Anthropic. AGENTS.md, the open format. Cursor rules, Cursor. Custom instructions with AGENTS.md, OpenAI Codex. Project rules, xAI.