Claude Code and AGENTS.md: how it reads the file, imports and migration

Claude Code reads AGENTS.md as your project instructions when your repository has no CLAUDE.md, so a repo set up for Codex, Cursor or other agents works without extra files. If you have both files, Claude reads only CLAUDE.md by default, and you either import AGENTS.md from it with @AGENTS.md or change the Project instructions setting.

Direct support arrived in Claude Code v2.1.277. Before that, teams relied on workarounds such as symlinks and hooks. This guide covers what loads when, how to keep one shared file, and how to clean up old workarounds, all based on the official memory documentation.

When does Claude Code read AGENTS.md?

The Claude Code docs give a simple table for the default behavior:

Not every file counts in that check. A CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or any parent counts, so Claude reads those instead of AGENTS.md. Your personal ~/.claude/CLAUDE.md, your organization's managed CLAUDE.md and .claude/rules/ files do not count, and they keep loading alongside AGENTS.md.

When Claude does read AGENTS.md, here is what happens:

• At session start, it loads every AGENTS.md and .claude/AGENTS.md in your working directory and the directories above it. In an interactive session you see a line like no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md.
• In subdirectories, a nested AGENTS.md loads when Claude opens a file there with the Read tool, as long as that subdirectory has no CLAUDE.md file of its own.
• Inside each file, @path imports expand and claudeMdExcludes patterns apply, just like in CLAUDE.md.
• Never read: AGENTS.local.md, AGENTS.override.md or anything under a .agents/ directory.

One trap is worth knowing. Because CLAUDE.local.md counts, adding one for your personal notes in a project that relies on AGENTS.md stops Claude from reading AGENTS.md for you. The fix is the claude-md-and-agents-md setting described below.

How do you use @AGENTS.md in CLAUDE.md?

If your project needs both a shared AGENTS.md and some Claude-only instructions, put an import at the top of a CLAUDE.md next to it. Claude reads the imported file first, then the rest:

@AGENTS.md

## Claude Code

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

That example is the one the docs use. Imports work the same way they do anywhere in CLAUDE.md: relative paths resolve from the file that contains the import, and imported files can import others up to four hops deep. The Claude Code memory guide covers imports in more detail.

The import is also the fallback when Claude cannot read AGENTS.md directly. The docs list three such cases: a version before v2.1.277, a session where you disabled the built-in plugin that reads AGENTS.md with /plugin, and in some cases the first session after upgrading from v2.1.276 or earlier.

If you have no Claude-specific content, a symlink works too:

ln -s AGENTS.md CLAUDE.md

Check two constraints first. Claude's Edit and Write tools refuse to write through a symlink and point Claude at AGENTS.md instead. And on Windows, creating a symlink needs Administrator privileges or Developer Mode, while Git checks a committed symlink out as a plain text file unless core.symlinks is enabled. The docs recommend the import for any team with Windows users.

How do you change which instruction files load?

Type /config in a session and set Project instructions to one of four values:

With claude-md-and-agents-md, Claude Code skips an AGENTS.md it already loaded, so one that your CLAUDE.md imports or symlinks to is not read twice.

You can set the same value in a settings file. It lives under pluginConfigs for the built-in plugin cc-plugin-agents-md@builtin, and Claude Code reads it from ~/.claude/settings.json, a --settings file or managed settings. It ignores this entry in project and local settings files, so it is a per-person or per-organization choice, not something a repo can force.

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

Before v2.1.285 the plugin ID was agents-md@builtin. Claude Code v2.1.285 and later reads either ID, so use the old one if older versions also read your settings file. For more on settings scopes, see the Claude Code settings guide.

How is AGENTS.md different from CLAUDE.md in Claude Code?

An AGENTS.md read through the Project instructions setting behaves like CLAUDE.md in most ways. The docs list three differences:

• InstructionsLoaded hooks do not fire for it. They do fire for an AGENTS.md that a CLAUDE.md imports or symlinks to.
• Directories added with --add-dir while CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD is set load their CLAUDE.md, but not their AGENTS.md.
• External imports: an @path import of a file outside your working directory loads only if you already approved external imports for that project, with no prompt. In CLAUDE.md, Claude Code asks you.

If you rely on any of those three, keep a CLAUDE.md with an @AGENTS.md import rather than depending on direct loading.

How do you migrate an old AGENTS.md workaround?

Many repos set up Claude Code to read AGENTS.md before it did so natively. The docs say what to do with each common setup:

• A CLAUDE.md containing @AGENTS.md: you can leave it. The import never makes Claude read AGENTS.md twice. Delete the CLAUDE.md if it holds nothing else, or keep it if some sessions cannot load AGENTS.md directly.
• A CLAUDE.md that tells Claude in words to read AGENTS.md: replace the sentence with an @AGENTS.md import, or delete the file. A sentence only works if Claude decides to open the file.
• A CLAUDE.md symlinked to AGENTS.md: leave it or delete the symlink. Either way Claude reads the content once.
• A SessionStart hook that prints AGENTS.md: remove it. Once Claude reads AGENTS.md directly, the hook adds a second copy to the context.

Going the other direction, from another tool's files into CLAUDE.md, has its own commands. /init reads Cursor rules and Copilot instructions when it generates a CLAUDE.md, and with CLAUDE_CODE_NEW_INIT=1 set it also reads AGENTS.md, Windsurf, Devin and Cline rules. /import brings a supported agent's configuration into Claude Code, appending a one-time copy of files such as AGENTS.md to the matching CLAUDE.md, along with MCP servers, commands, subagents and skills. A one-time copy will drift from the original, so prefer the import or direct loading if other tools keep using AGENTS.md.

Which setup should your team use?

Pick based on who touches the repo:

• Claude Code plus other agents, no Claude-only rules: keep a single AGENTS.md and no CLAUDE.md. Claude reads it directly on current versions.
• Claude Code plus other agents, with some Claude-only rules: AGENTS.md for shared rules and a short CLAUDE.md that starts with @AGENTS.md. This also covers people on older versions.
• Claude Code only: a CLAUDE.md is enough. See what AGENTS.md is if you expect to add other tools later.
• Large monorepo: nested files load on demand in either format, and claudeMdExcludes applies to both. The large codebases guide covers layering.

Whatever you choose, verify it. Run /context in a new session and check the Memory files list, and run /doctor prompt-audit to have Claude look for outdated or conflicting content across your CLAUDE.md, CLAUDE.local.md and AGENTS.md files. For how Codex treats the same file, including the override files Claude ignores, see the Codex AGENTS.md guide.

Where should reusable instructions live?

AGENTS.md works best for facts every session needs: build commands, layout and conventions. Multi-step procedures belong in skills, which load only when relevant. If you reuse the same instruction blocks across many repos, Kipt keeps prompts and Agent Skills as Markdown in a private GitHub repo you own, so a snippet you paste into each new AGENTS.md, or a procedure that should become a Claude Code skill, is easy to find and reuse.