Does Claude Code Read AGENTS.md? Sharing One File With Every Agent

Yes. Current versions of Claude Code read AGENTS.md as your project instructions without a CLAUDE.md, an import or a setting. The catch is the default rule: Claude reads AGENTS.md only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working folder or any folder above it. The moment one of those exists, Claude reads the CLAUDE.md files and ignores AGENTS.md, unless the CLAUDE.md imports it with @AGENTS.md or you change the Project instructions setting. If you want one file that every coding agent shares, the import is the safe choice; a symlink works too, except on Windows.

What the documentation says today

Anthropic’s memory documentation↗ (opens in a new tab) sets out three cases. An AGENTS.md with no CLAUDE.md or CLAUDE.local.md on the path: Claude reads the AGENTS.md. An AGENTS.md and a CLAUDE.md together: Claude reads the CLAUDE.md files only. A CLAUDE.md that imports AGENTS.md: Claude reads the CLAUDE.md, with the AGENTS.md included through the import. Reading AGENTS.md directly needs Claude Code v2.1.277 or later, so older installs still need the import.

Not every CLAUDE.md counts. The ones that switch AGENTS.md off are a CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working folder or above it. Your personal ~/.claude/CLAUDE.md, an organisation’s managed CLAUDE.md and .claude/rules/ files do not count, and keep loading alongside AGENTS.md.

When Claude does read AGENTS.md, it reads every AGENTS.md and .claude/AGENTS.md from your working folder upwards at the start of the session, and in an interactive session says so with a line such as no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md. A subfolder’s AGENTS.md loads later, when Claude opens a file in that subfolder and the subfolder has no CLAUDE.md of its own. @path imports inside an AGENTS.md are expanded. Three things are never read: AGENTS.local.md, AGENTS.override.md, and anything under a .agents/ folder.

The trap: a private CLAUDE.local.md

The case that catches people is a repository that relies on AGENTS.md, where one developer adds a CLAUDE.local.md for their own uncommitted notes. Because CLAUDE.local.md counts, Claude now reads that file and stops reading AGENTS.md for that developer only. Everyone else is fine, which makes it hard to spot. The same goes for AGENTS.override.md: Codex reads it, Claude Code does not, so a rule that lives only there reaches one agent and not the other. If an agent is ignoring rules you are sure you wrote, CLAUDE.md not working walks through the other causes.

The Project instructions setting

Type /config and set Project instructions to change the default. There are four values:

• claude-md-or-agents-md: the default. CLAUDE.md files, or AGENTS.md when there is no CLAUDE.md or CLAUDE.local.md on the path.
• claude-md-and-agents-md: both, each folder’s CLAUDE.md first and its AGENTS.md after. An AGENTS.md already pulled in by an import or a symlink is not read twice. This is the fix for the CLAUDE.local.md trap.
• claude-md: CLAUDE.md files only, the behaviour of older versions.
• managed-only: only your organisation’s managed CLAUDE.md and auto memory at launch.

The setting is personal. You can also put it in ~/.claude/settings.json, a --settings file or managed settings, but Claude Code ignores it in a project’s own settings files, so you cannot commit it to a repository and have it apply to everyone. That is the main reason a shared repository should not depend on it.

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

Some sessions cannot read AGENTS.md at all: versions before v2.1.277, installs where the built-in agents-md plugin is disabled in /plugin, and sometimes the first session after upgrading from an older version. In those, Project instructions does not appear in /config, and only an import gets AGENTS.md into context.

Two ways to share one file

The documentation describes two ways to keep AGENTS.md as the single source while Claude reads a CLAUDE.md. The first is an import at the top of CLAUDE.md, with any Claude-only lines below it. Claude reads the imported file first, then the rest.

@AGENTS.md

## Claude Code only
- Use plan mode for changes under src/billing/.

The second, when you have nothing Claude-specific to add, is a symlink: ln -s AGENTS.md CLAUDE.md. Claude reads through the link. Two constraints come with it. Claude’s Edit and Write tools refuse to write through a symlink and point Claude at the target, AGENTS.md, instead. And on Windows, creating a symlink needs Administrator rights or Developer Mode, and Git checks a committed symlink out as a plain text file unless core.symlinks is on, as the git-config reference↗ (opens in a new tab) describes. That clone ends up with a one-line CLAUDE.md containing the word AGENTS.md in place of your rules, and nothing warns you.

Which one to choose

• Only AGENTS.md, nothing Claude-specific, everyone on a current version: no CLAUDE.md at all. Claude reads AGENTS.md directly.
• You have Claude-specific lines, or anyone might run an older version or a session without AGENTS.md support: a CLAUDE.md that starts with @AGENTS.md. It works in every case, and the documentation says keeping the import never makes Claude read the file twice.
• Anyone on the team works on Windows: the import, never the symlink.
• A macOS or Linux team with nothing Claude-specific that wants no second file to maintain: the symlink is acceptable, but the import costs one line and has no caveats.
• Never a CLAUDE.md that says in words “read AGENTS.md”. Claude only sees the file if it decides to open it. Replace the sentence with the import.
• Never a SessionStart hook that prints AGENTS.md. On a version that reads the file directly, the hook adds a second copy.

One layout for Claude Code, Codex, Copilot and Cursor

The layout that serves all four keeps the rules in AGENTS.md and makes every other file a pointer or a short addition. Codex reads AGENTS.md from the root down to the working folder, according to OpenAI’s AGENTS.md guide↗ (opens in a new tab), and Cursor reads it at the root and in subfolders.

GitHub’s repository instructions page↗ (opens in a new tab) says that when Copilot is working, the nearest AGENTS.md in the directory tree takes precedence. So the file below is read by all four, and the others only add to it.

AGENTS.md                         # the rules: setup, build, test, never-touch, work tracking
packages/billing/AGENTS.md        # only what is true inside billing
CLAUDE.md                         # @AGENTS.md, then Claude-only lines (optional)
.github/copilot-instructions.md   # the few rules that must always hold, written out
.cursor/rules/                    # only if you need Cursor-specific globs
.gitignore                        # CLAUDE.local.md

• Keep anything written in CLAUDE.md harmless to other tools, because Cursor also applies a root CLAUDE.md.
• If you keep a CLAUDE.md, a subfolder with only an AGENTS.md is read by Codex, Copilot and Cursor, but not by Claude under the default setting. Either add a one-line CLAUDE.md with @AGENTS.md beside it, or keep the root free of CLAUDE.md so the default rule reads every AGENTS.md.
• Some Copilot chat surfaces never read AGENTS.md, so the non-negotiables go in copilot-instructions.md in full. The surface-by-surface detail is in does GitHub Copilot support AGENTS.md?
• What to write inside the file is in AGENTS.md examples; how every tool ranks its files when several apply is in AI context files compared.

Check what actually loaded

Run /context in a new session and look under Memory files. With an import or a symlink you should see CLAUDE.md; with the default rule and no CLAUDE.md, the session prints the AGENTS.md loaded line at the start. Do this on a Windows clone as well as your own machine, and again after anyone adds a CLAUDE.local.md. Two smaller differences are worth knowing if you automate around instruction files: InstructionsLoaded hooks do not fire for an AGENTS.md read through the setting, though they do for one that a CLAUDE.md imports, and a folder added with --add-dir loads its CLAUDE.md but not its AGENTS.md. Across several repositories at once, managing multiple projects with CLAUDE.md covers the rest.

Point every agent at the same board

One shared file is also the natural place for the one rule every agent should follow the same way: where the work is recorded. Put a short work-tracking section in AGENTS.md and Claude Code, Codex, Copilot and Cursor all read it. With a fenbs board connected over MCP, it can tell each of them to call fenbs_get_context first, which returns the board’s AI context, the notes about how you work that you keep on the board rather than in the file. A lesson one agent writes there with fenbs_add_context_note reaches the next agent, whichever tool it is, and every change each one makes is recorded under its own name.

## Work tracking
- Tasks live on the fenbs board. Start every session with fenbs_get_context.
- Before starting, move the task to In Progress; when you stop, comment what
  changed and how it was tested, and move it to Completed only if tests pass.
- File anything you notice but do not fix as a new task: bug, feature or enhancement.