CLAUDE.md vs AGENTS.md: Which File Each Agent Reads, and How to Keep One Copy

One repo, five agents, one set of rules. Here is the file layout that works.

Here's CLAUDE.md vs AGENTS.md as one quick-answer table:

Picture this: a teammate adds a CLAUDE.local.md to keep their sandbox URL out of git. Next session, Claude Code stops reading the AGENTS.md the rest of the team spent a month tuning.

Wait. Who deleted our rules?

No one did. Claude Code's default is to read AGENTS.md only when there's no CLAUDE.md, CLAUDE.local.md or .claude/CLAUDE.md in your working directory or above it. That one quiet rule is why the file layout matters more than the file content.

We checked every tool on this page against its own docs on 10 November 2026. If you're still deciding what to write in the file, our AGENTS.md best practices guide covers length, templates and examples. This page is about which agent reads which file.

CLAUDE.md vs AGENTS.md: the one-line layout

The layout we recommend for any repo touched by more than one agent fits in one sentence: rules live in AGENTS.md, and every CLAUDE.md is a pointer.

The nested pointer is the part most guides skip. Once a CLAUDE.md sits at the root, Anthropic's memory docs say Claude Code reads "your CLAUDE.md files only". By default, a package's AGENTS.md with no CLAUDE.md beside it never loads for Claude.

So every folder that has an AGENTS.md also gets a one-line CLAUDE.md. Claude Code loads a subdirectory CLAUDE.md once it reads, writes or edits a file there, and the import pulls in the AGENTS.md next to it.

Which tools read which file

Here's what each tool's own docs say today. Where a doc is silent, the table says "not documented" instead of guessing.

Three things jump out of that table.

First, AGENTS.md is the only file all seven read. Second, CLAUDE.md leaks: Cursor applies it to every conversation regardless of any alwaysApply frontmatter, and Copilot's cloud agent accepts it as an alternative.

Third, Hermes Agent and OpenClaw also load a personality file, SOUL.md, that has nothing to do with project rules. Our SOUL.md guide for Hermes covers where that one lives.

CLAUDE.md vs AGENTS.md: the differences that actually matter

The file names are the easy part. Four behaviours decide whether your rules actually arrive.

Loading order

Claude Code concatenates every file it finds, from the filesystem root down to your working directory, with CLAUDE.local.md after CLAUDE.md in each folder. Nothing overrides anything. Anthropic's docs warn that "if two instructions contradict each other, Claude may pick one arbitrarily."

Codex also joins files root first, and says files closer to your working directory "override earlier guidance because they appear later in the combined prompt." OpenCode V2 combines its files and "does not resolve conflicts between them." Cursor merges Team, Project and User rules, with earlier sources winning a conflict.

Four tools, four merge rules. The only safe nested file is one that adds rules, never one that reverses them.

Nested files

Claude Code, Hermes Agent and OpenCode all pick up a subfolder's file as the agent starts working there. Codex's docs describe no such step. It builds its chain once per run, from the project root down to where you launched it, and it "stops searching once it reaches your current directory."

So if you start Codex at the repo root and edit packages/payments, that package's AGENTS.md isn't in the loaded chain. Launch from the package, or keep must-know rules at the root.

Imports

Of the seven, only Claude Code documents expanding @path imports. Paths resolve relative to the file that holds them, imports can nest four hops deep, and they work inside an AGENTS.md that Claude reads directly too.

Cursor treats @file as a pointer: its docs say the file's contents "are not inlined into the prompt." OpenCode asks you to list extra files in the instructions array of opencode.json instead. Codex, Copilot, Hermes Agent and OpenClaw don't document import syntax at all, so to them @AGENTS.md is just text.

Sections a tool doesn't understand

AGENTS.md has no required fields. The agents.md FAQ says it's "just standard Markdown", so every tool reads every heading, including a "## Claude Code" section meant for one agent.

Two quirks are worth knowing. Claude Code strips block-level HTML comments from CLAUDE.md before Claude sees them, which makes them handy for maintainer notes.

Hermes Agent lists hidden HTML comments among the prompt-injection signs its scanner checks: a comment containing words like "ignore", "override", "system", "secret" or "hidden" is flagged, and a hit blocks the whole file. In a shared AGENTS.md, keep notes for humans out of comments.

One source of truth: import, symlink or keep them separate

You have three ways to stop two files drifting apart. We've ranked them.

The import (our pick)

This is the layout Anthropic's docs show for sharing one file with other coding tools:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

It works on every Claude Code version, it survives a teammate adding CLAUDE.local.md, and Anthropic says keeping the import "never makes Claude read AGENTS.md twice." One catch: Cursor applies CLAUDE.md to every conversation, so anything you write under the import reaches Cursor's agent as well. Put Claude-only rules in .claude/rules/ instead, which loads alongside AGENTS.md and doesn't count as a CLAUDE.md.

The symlink

If you don't need Claude-specific content, Anthropic's docs list a symlink as the other option:

ln -s AGENTS.md CLAUDE.md

It has three costs. On Windows, creating it needs Administrator rights or Developer Mode, and Git checks a committed symlink out as a plain text file unless core.symlinks is enabled, leaving that clone with a one-line CLAUDE.md.

Claude Code's Edit and Write tools also refuse to write through a symlink. And Cursor and Copilot both read files named AGENTS.md and CLAUDE.md; neither documents whether it notices that the two are the same file.

No CLAUDE.md at all

Since v2.1.277, Claude Code reads AGENTS.md on its own when there's no CLAUDE.md. It's the cleanest layout, but the CLAUDE.local.md trap above switches it off, and so do versions before v2.1.277 and, in some cases, the first session after upgrading from v2.1.276 or earlier.

Fine for a solo repo. Fragile for a team.

Keep them separate

Do this only when Claude needs a lot that other agents must not see. Even then, start the CLAUDE.md with @AGENTS.md so the shared rules exist once.

AGENTS.md vs skills.md vs copilot-instructions.md vs instructions.md

The autocomplete asks about all of these, so here's one paragraph each.

skills.md

There's no single skills.md file. A skill is a folder with a SKILL.md inside it, following the Agent Skills open standard: .claude/skills/<name>/SKILL.md in Claude Code, .agents/skills in Codex. The difference from AGENTS.md is when it loads: Codex and Claude Code read a skill's full instructions only when the task calls for it, so multi-step procedures belong there.

copilot-instructions.md

This is Copilot's own repository-wide file, at .github/copilot-instructions.md. Every Copilot surface GitHub lists, from Chat on GitHub.com to Xcode, supports it, which AGENTS.md can't yet claim on Copilot.

instructions.md

Copilot's path-specific files are named NAME.instructions.md under .github/instructions/, with an applyTo glob in the frontmatter. They're Copilot's version of Cursor's file-scoped rules and Claude Code's paths rules.

README.md and AGENT.md

The agents.md site puts it plainly: "README.md files are for humans." And AGENT.md, singular, is a typo the same site suggests fixing with a rename plus a symlink back for older tools.

What belongs in the file and what belongs in hooks

Here's the line we draw. If a machine can check a rule, a machine should enforce it. AGENTS.md keeps the judgment calls.

Three vendors say the same thing in their own docs. Anthropic calls CLAUDE.md "context, not enforced configuration" and says to use a PreToolUse hook to block an action "regardless of what Claude decides." OpenAI's AGENTS.md guide says to "reserve formatting and lint checks for CI." Cursor's rules page says not to copy entire style guides: "Use a linter instead."

A sentence in AGENTS.md is a request. A hook, a CI check or a permission rule is a wall. Put each rule where it belongs.

So formatting, lint, "tests must pass" and forbidden paths go to pre-commit hooks, CI and permission rules. In Claude Code, a deny rule in the committed .claude/settings.json holds for everyone on the repo:

{
  "permissions": {
    "deny": ["Edit(/generated/**)", "Read(./.env)"]
  }
}

Codex has its own hooks, including PreToolUse and Stop, plus rules for which commands may run outside its sandbox. What stays in AGENTS.md: which of two valid approaches your team prefers, when to stop and ask, and what an unfamiliar module is for.

That split also keeps the file short, and the research we summarised in the best practices guide linked above is clear that every extra line in a context file costs you on every run.

Keeping it in sync across many repos and many developers

One repo is easy. Forty repos and 500 developers is where files quietly drift. Here's what each layer can do.

Claude Code, organisation-wide

IT can deploy a managed CLAUDE.md to every machine, at /Library/Application Support/ClaudeCode/CLAUDE.md on macOS, /etc/claude-code/CLAUDE.md on Linux and WSL, and C:\Program Files\ClaudeCode\CLAUDE.md on Windows, using MDM, Group Policy or Ansible. Or skip the file and put the text in the claudeMd key of managed-settings.json, which lives in the same three folders.

Developers can't exclude the managed file with claudeMdExcludes. Several teams can each own a piece of the policy through a managed-settings.d/ folder, and a claude.ai organisation can push server-managed settings instead.

Make Claude read both files everywhere

The Project instructions value lives under pluginConfigs in settings, and Claude Code honours it from user or managed settings but ignores it in project files. Set it once in managed settings:

{
  "pluginConfigs": {
    "cc-plugin-agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}

If some machines run Claude Code older than v2.1.285, the plugin ID there was agents-md@builtin, so use that ID instead. Newer versions read either.

Skills and hooks

Package them as a Claude Code plugin, which can hold skills, hooks, subagents and MCP servers. Register your marketplace with extraKnownMarketplaces and switch plugins on with enabledPlugins.

Cursor does the same through team marketplaces and enforced Team Rules. Copilot has organisation instructions on Business and Enterprise plans, but only for sessions on GitHub's website and code review.

A template repo and one CI check

New repos start from a template, and CI fails when the files drift:

test -f AGENTS.md || { echo "AGENTS.md missing"; exit 1; }
[ "$(wc -l < AGENTS.md)" -le 150 ] || { echo "AGENTS.md over 150 lines"; exit 1; }
grep -qx '@AGENTS.md' CLAUDE.md || { echo "CLAUDE.md must import AGENTS.md"; exit 1; }

Running several agents against the same repo at once? Our guide to AGENTS.md for multi-agent setups covers splitting roles without the files contradicting each other.

A starter AGENTS.md and a two-line CLAUDE.md

Copy these, then cut anything your agents already get right without being told.

# AGENTS.md

## Stack
TypeScript 5, Node 22, pnpm workspaces, Vitest, Postgres via Drizzle.

## Commands
Install: `pnpm install`
Test one file: `pnpm vitest run path/to/file.test.ts`
Full check before a PR: `pnpm check`

## Conventions
Money is integer cents, never floats.
New endpoints go in `src/api/<resource>/` with a test beside them.
Prefer small pure functions over classes in `src/lib/`.

## Ask first
Before adding a dependency, changing a migration, or touching `src/billing/`.

## Enforced elsewhere (do not restate here)
Formatting, lint and forbidden paths are enforced by hooks and CI.

# Claude Code: shared rules live in AGENTS.md
@AGENTS.md

The heading line is there for humans and for Cursor, which reads CLAUDE.md too and will see what the file is for. Claude Code expands the import.

OpenClaw truncates each file at 20,000 characters by default, and Hermes Agent's cap never drops below that, so a file this size fits everywhere. Our notes on AGENTS.md optimization for OpenClaw cover what to trim when you get close.

One instruction file across agents, and where BetterClaw fits

Everything above is about coding agents in a repo. But the same rules often need to reach agents that never open your repo: the one triaging support email overnight, or the one watching a deploy channel.

Those always-on agents are what BetterClaw runs. You bring your own model keys, with zero markup across 28+ providers, so the model stays your choice and your bill, and agents reach your tools through 500+ connectors.

The principle from this page carries straight over: keep one written set of rules, and enforce the hard limits outside the prompt. Plans start from $19 a month, and your first workspace starts with a 7-day free trial. See BetterClaw plans

Write the rules once, then stop thinking about file names

Every agent on this page will keep inventing its own file. Some new one will ship next quarter with a new name and a new fallback order.

You don't have to chase them. Write the rules once in AGENTS.md, point everything else at it in one line, and move anything that must never break into a hook. Then the only question left is the one worth your time: is this rule still earning its line?

Frequently Asked Questions

What is the difference between CLAUDE.md and AGENTS.md?

AGENTS.md is the cross-tool instruction file read by Codex, Copilot, Cursor, OpenCode, Hermes Agent and OpenClaw. CLAUDE.md is Claude Code's own file, with extras like @path imports and a managed, organisation-wide version. Keep the rules in AGENTS.md and make CLAUDE.md a one-line import.

Does Claude Code read AGENTS.md?

Yes, from v2.1.277, but by default only when there's no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or above it. To read both, set Project instructions to claude-md-and-agents-md in /config, or put @AGENTS.md in your CLAUDE.md. It never reads AGENTS.override.md or AGENTS.local.md.

Can I symlink CLAUDE.md to AGENTS.md?

Yes. ln -s AGENTS.md CLAUDE.md works, and Anthropic lists it as an option. Avoid it if anyone clones the repo on Windows, where Git can check the link out as a one-line text file, and note that Claude Code's edit tools won't write through it. The @AGENTS.md import avoids both problems.

What is skills.md?

There's no single skills.md file. Skills are folders that each hold a SKILL.md, following the Agent Skills open standard, in .claude/skills/ for Claude Code and .agents/skills for Codex. Their full instructions load only when the task needs them, which makes them the right home for multi-step procedures.

How big should AGENTS.md be?

Aim for under 100 lines. Anthropic's ceiling for CLAUDE.md is 200 lines, Codex stops adding files at 32 KiB combined, Cursor suggests rules under 500 lines, and Hermes Agent and OpenClaw truncate long files. Shorter files cost less on every run.

How do teams share AGENTS.md across repos?

Start new repos from a template and add a CI check that the file exists, stays under your line limit and that CLAUDE.md imports it. For Claude Code, deploy organisation-wide guidance as a managed CLAUDE.md or the claudeMd key in managed-settings.json. Ship shared skills and hooks as plugins from a team marketplace.

Does Codex read CLAUDE.md?

Not by default. Codex reads AGENTS.override.md and AGENTS.md, plus any names you add to project_doc_fallback_filenames in ~/.codex/config.toml, and it uses at most one file per directory. Keep shared rules in AGENTS.md so Codex sees them without extra setup.