Does Claude Code read AGENTS.md?

Which version of Claude Code supports AGENTS.md?

2.1.277, published to npm on 2026-09-18. The changelog line is short: “in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead; change it under ‘Project instructions’ in /config (not yet on Bedrock, Vertex or Foundry).”

It closed a long wait. The feature request, anthropics/claude-code#6235, was opened in August 2025 and had over 5,000 thumbs up when it was closed on 2026-08-17. Before 2.1.280, /memory and /context did not list an AGENTS.md that Claude read directly, so on 2.1.277 to 2.1.279 the only way to check was to ask Claude what its project instructions said.

What are the instructionFiles modes?

The support ships as a built-in plugin, agents-md, with one option, instructionFiles. It takes four values.

The option was first keyed projectInstructions, with the values claude, agents-fallback, both and none. A value stored under the old key is still honoured for now, and the transcript says how it was read.

Where do I set it?

In a session, /config and the row called Project instructions. By hand, in ~/.claude/settings.json, a --settings file, or managed settings:

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

A project's .claude/settings.json is not read for this option, and neither is .claude/settings.local.json. You cannot commit the mode to a repo and have every teammate pick it up. Each person sets it for themselves, or an admin sets it in managed settings. A change applies from the next context Claude Code builds: the next turn after the reload, a new conversation, /clear, or a compaction.

What happens if both AGENTS.md and CLAUDE.md exist?

Under the default, Claude Code reads your CLAUDE.md files and ignores AGENTS.md. The check is narrower than it sounds, and one part of it catches people.

• These count and switch AGENTS.md off: a CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or any directory above it.
• These do not count and load alongside AGENTS.md: your ~/.claude/CLAUDE.md, the organization's managed CLAUDE.md, and .claude/rules/ files.
• Never read: AGENTS.local.md, AGENTS.override.md (a Codex convention), and anything under .agents/.

The catch is CLAUDE.local.md. It is a personal, gitignored file, so adding one to keep your own notes in a repo that runs on AGENTS.md quietly stops Claude from reading AGENTS.md for you, and only for you. Set the mode to claude-md-and-agents-md if you want both.

Why is Claude Code ignoring my AGENTS.md?

If there is no CLAUDE.md in the way, the usual cause is that the session never fetched its feature flags. Per the environment variable docs, that happens when:

• DISABLE_TELEMETRY, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, DISABLE_GROWTHBOOK or DO_NOT_TRACK is set. For the first two, any non-empty value counts, including 0 and false. Unset them.
• The session runs on a third-party provider such as Amazon Bedrock, Google Vertex or Microsoft Foundry, or through a Claude apps gateway.
• It is the first session after an install or an upgrade. The flags are fetched during that session and apply from the next one.
• The built-in agents-md plugin is turned off in /plugin.

The quickest tell: if /config has no Project instructions row, this session cannot load AGENTS.md. When it does load, an interactive session prints a line such as no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md, and from 2.1.280 the path shows in /memory.

How did you use AGENTS.md with Claude Code before?

Four workarounds were common. The docs now say what to do with each.

• A CLAUDE.md containing @AGENTS.md. Keep it. The import never causes a double read, whatever the mode, and it is the only form that works in sessions without flags.
• A CLAUDE.md symlinked to AGENTS.md. Harmless; Claude reads the content once. On Windows clones Git checks the link out as a one-line text file unless core.symlinks is on.
• A SessionStart hook that prints AGENTS.md. Remove it. With native support it adds a second copy.
• A CLAUDE.md that says “read AGENTS.md”. Replace the sentence with an import. In words, Claude only sees the file if it decides to open it.

If anyone on the team, or any CI job, runs with telemetry off, keep the one-line import. It costs nothing when native support is on:

# CLAUDE.md
@AGENTS.md

# Claude-only notes go below the import

Is AGENTS.md treated exactly like CLAUDE.md?

Almost. An AGENTS.md read through the setting does not fire InstructionsLoaded hooks, does not load from --add-dir directories, and nested ones attach only when Claude opens a file in that directory with the Read tool. The plugin README lists the rest. For most repos none of this matters. For a monorepo with per-package files, it is worth a test.

One file for every agent. Who keeps it true?

Native support settles where the instructions live. Claude Code, Codex, Cursor and Copilot can now all read one AGENTS.md; the comparison is in AGENTS.md vs CLAUDE.md. It does not settle who writes the file, or when a line in it stops being true.

Take one decision. In #eng-payments the team agrees that webhook handlers acknowledge with a 200 and enqueue, and never do the work inline. That line reaches AGENTS.md only if someone remembers to open a pull request. When the queue is replaced next quarter, the line stays until someone remembers to delete it.

Harbor is built for that gap. It reads where the team already decides: Slack, pull request review threads, docs. A person approves what it finds, or you let policy approve the routine ones; you set the gate. Each agent gets the facts that apply to its task on the first turn, and when a repo change removes what a fact was about, Harbor can retire it. harbor init installs the hooks for Claude Code, Codex and Cursor in one pass. The quickstart takes a few minutes.

Related: whether to commit CLAUDE.md and the .claude folder, and how long the file should be once every agent is reading it.