AGENTS.md vs CLAUDE.md: the difference, and which file your agent reads

The AGENTS.md vs CLAUDE.md question comes down to who reads the file. Both do the same job: they tell a coding agent how your project works and what it must never do. AGENTS.md is an open format that Codex, Cursor, GitHub Copilot, Hermes and many others read. CLAUDE.md is the file Claude Code looks for first. If you use more than one agent, keep your rules in AGENTS.md and let CLAUDE.md import it.

AGENTS.md vs CLAUDE.md: what is the difference?

Both are plain Markdown files in your repo. Both are advice, not hard limits: Anthropic’s docs call CLAUDE.md “context, not enforced configuration”.

• AGENTS.md is a shared standard, described at agents.md as an open format for guiding coding agents. It is now stewarded by the Agentic AI Foundation under the Linux Foundation, so no single vendor owns it.
• CLAUDE.md is Claude Code’s memory file. It loads at the start of every session and adds Claude-only features, such as @path imports and a personal CLAUDE.local.md.

Which file does each agent read?

Table 1 shows what six common agents read, according to each vendor’s own docs.

Agent	Reads by default	CLAUDE.md?
Claude Code	CLAUDE.md; AGENTS.md only when there is no CLAUDE.md	Yes, first choice
Hermes	One file, first match: .hermes.md, AGENTS.override.md, AGENTS.md, CLAUDE.md, .cursorrules	Only if there is no AGENTS.md
OpenAI Codex	AGENTS.override.md, then AGENTS.md, per folder	Only if you add it as a fallback name
GitHub Copilot (on GitHub)	AGENTS.md anywhere, plus .github/copilot-instructions.md	Yes, a single one in the repo root
Cursor	AGENTS.md in the root and subfolders, plus .cursor/rules	Not in its rules docs
Gemini CLI	GEMINI.md; AGENTS.md once you add it to context.fileName	Not by default

Sources: Hermes context files, Codex AGENTS.md guide, GitHub’s Copilot instructions, Cursor rules and Gemini CLI context files.

Does Claude Code read AGENTS.md?

Yes, since version 2.1.277, but only as a fallback. Some guides written earlier this year still say it does not, so check the date on anything you read. Anthropic’s memory docs set out the rules:

• Only AGENTS.md in the project: Claude Code reads it.
• AGENTS.md and a CLAUDE.md: Claude Code reads CLAUDE.md only.
• A CLAUDE.md that imports AGENTS.md: Claude Code reads both, through the import.

Two details catch people out. A personal CLAUDE.local.md also counts as a CLAUDE.md, so adding one quietly stops Claude from reading AGENTS.md. And the first session after upgrading from version 2.1.276 or earlier may not read it yet, so the import is the safe choice.

To load both files without an import, type /config in Claude Code, open Project instructions and pick the option that loads CLAUDE.md and AGENTS.md together. That setting is per user, so it does not travel with the repo. The import does.

Which setup should you use?

Pick the line that matches your situation:

• You only use Claude Code: write a CLAUDE.md and you are done.
• You use Claude Code and another agent: put the rules in AGENTS.md and create a CLAUDE.md that starts with @AGENTS.md. This works in every Claude Code session, old or new.
• You cloned a repo that only has AGENTS.md: change nothing. Do not add an empty CLAUDE.md, because that switches the fallback off.
• You need Claude-only rules: put them in CLAUDE.md below the import line. Claude reads the imported file first, then the rest.

Skip the symlink trick (ln -s AGENTS.md CLAUDE.md) if anyone uses Windows. Anthropic’s docs warn that a symlink there needs Administrator rights or Developer Mode. Git may also check it out as a plain text file, which leaves a one-line CLAUDE.md instead of your rules.

Hermes fits this setup without changes. It loads only one file, and AGENTS.md ranks above CLAUDE.md, so it reads your shared rules and skips the Claude-only lines.

Set it up in three steps

These steps give every agent in Table 1 the same rules. Run them from the repo folder.

1. Ask Claude Code or Hermes to write AGENTS.md with the prompt below.
2. Check that CLAUDE.md contains only the line @AGENTS.md, plus any Claude-only rules under it.
3. Start a new Claude Code session, type /context, and confirm that CLAUDE.md appears under memory files.

Read this repo and write AGENTS.md in the root, under 100 lines: what the project is, how to run and test it, and the rules (never print secrets, start every session with git pull, end with commit and push). If CLAUDE.md already holds rules, move them into AGENTS.md first. Then create CLAUDE.md containing only the line @AGENTS.md. Do not create .hermes.md. Show me both files before you save them.

Keep the file short. Anthropic suggests under 200 lines per CLAUDE.md, and an import does not make the imported text cheaper, because it loads in full.

Troubleshooting

Claude Code ignores my AGENTS.md

Check for any CLAUDE.md or CLAUDE.local.md in the folder or above it, and run claude --version to rule out a version older than 2.1.277. The fastest fix is the @AGENTS.md import.

Hermes ignores AGENTS.md

Check for a .hermes.md, HERMES.md or AGENTS.override.md in the folder. The first two outrank everything, and the override replaces AGENTS.md. Also make sure Hermes started inside the repo folder.

Codex ignores CLAUDE.md

That is by design. Codex reads CLAUDE.md only if you list it under project_doc_fallback_filenames in ~/.codex/config.toml, and then only in folders without an AGENTS.md. Moving the rules to AGENTS.md is simpler.

Frequently asked questions

Is CLAUDE.md only for Claude Code?

Mostly, but not only. Hermes reads it when there is no AGENTS.md, and GitHub Copilot on GitHub accepts a single CLAUDE.md in the repo root. Codex and Gemini CLI skip it unless you configure them.

What is the difference between AGENTS.md and skills?

An instruction file loads in every session, so it suits facts and rules that always apply. A skill is a packaged procedure. In Claude Code, a skill’s body loads only when it is used, so long step-by-step instructions belong in a skill, not in AGENTS.md.

What’s next

One shared rules file is also the base for handing work from one agent to another. When Claude hits its limit mid-task shows how Hermes picks up from the same Git repo, with a handoff note and the exact prompts to pull and push.

This article is part of the Agentic AI series.

The Tested Weekly

One email a week with the guides we tested, sources linked. No spam.

Email Address

Subscribe