Claude Code and AGENTS.md in 2026: Which Instruction File Actually Loads

Claude Code 2.1.277 (18 September 2026) added native AGENTS.md support: in a project with no CLAUDE.md, it reads AGENTS.md instead. The rule every write-up repeats — CLAUDE.md wins, AGENTS.md is the fallback — is the default of four instructionFiles modes, not the whole behaviour. It also failed quietly: loading was gated behind the remote flag tengu_agents_md_mod, off by default, so sessions with telemetry disabled and users on Bedrock, Vertex, Foundry or an LLM gateway got no instructions at all. Version 2.1.280 fixed that. Skip AGENTS.md if you already ship a working CLAUDE.md — on the default mode it changes nothing.

By Rohit Raj — AI Consultant · Forward Deployed Engineer · LinkedIn

On 18 September 2026, Claude Code 2.1.277 shipped one changelog line: "Added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead." Five days later a post titled "Claude Code reads AGENTS.md only when telemetry is on" hit the Hacker News front page with 480 points and 282 comments, because for a large class of users the feature had shipped and done nothing.

The capability that changed is small and load-bearing. AGENTS.md is the cross-tool convention — Codex, Cursor, Aider and others read it — and until 2.1.277 Claude Code did not, so any team running two coding agents on one repo maintained two copies of the same instructions and watched them drift. Native support means one file, if you understand exactly when it loads.

That last clause is where every guide currently in the search results stops. They all state the same one-line precedence rule and move on to "what to put in your AGENTS.md." The rule is real, and it is the default setting of a four-mode configuration, sitting on top of a feature-flag mechanism that produced a genuinely confusing failure. One of the top-ranking comparison posts was published in June 2026 and still tells readers that Claude Code does not read AGENTS.md at all. If you are debugging why your instructions are being ignored, none of that gets you there.

Two changelog entries bracket this story, and both matter.

2.1.277, 18 September 2026 — "Added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead." The same release also "improved the large CLAUDE.md startup notice to also count instruction files together, so many mid-sized files and @-imports are caught," which tells you the instruction-file budget is now measured across the whole set rather than per file. If you were staying under the notice threshold by splitting one large file into five @-imported ones, that no longer works.

2.1.280 — "Changed AGENTS.md support to also work on Amazon Bedrock, Google Vertex AI, Microsoft Foundry, LLM gateways, and sessions with telemetry disabled."

That second line is the fix for the Hacker News post, and it is worth reading carefully because it names the affected population precisely. This was not only a telemetry-opt-out edge case. Every user on Bedrock, Vertex, Foundry or a gateway — which is to say most enterprise deployments, since those are the paths that exist for compliance and procurement reasons — was in the same bucket. The blog post that surfaced the bug was published on 23 September and could not name a fix version. The changelog can: 2.1.280.

The implementation lives in a built-in plugin, agents-md@builtin, which is why the behaviour is configurable at all and why it has its own settings key rather than living in the memory system.

The agents-md plugin exposes one option, instructionFiles, with four values. This is the matrix the SERP is missing.

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

`claude-md` — only CLAUDE.md is loaded, by the engine, exactly as before. The plugin adds nothing. This is the pre-2.1.277 behaviour, available as an explicit opt-out.

`claude-md-or-agents-md` — the default, and the one the one-line rule describes: "a project with no instruction files of its own gets its AGENTS.md files instead, loaded exactly where and how CLAUDE.md would be."

The definition of *its own* is the part that surprises people. A CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in any directory from the root down to the working directory leaves the whole project to the engine and the plugin stays out. Not the working directory — the whole chain. One stray CLAUDE.md three levels up in a monorepo silences every AGENTS.md beneath it. When no such file exists on that path, "every AGENTS.md and .claude/AGENTS.md on that path joins the instruction files."

`claude-md-and-agents-md` — both, everywhere: "every AGENTS.md is loaded beside CLAUDE.md, up and down the tree; a file CLAUDE.md already @-imports, or is a link to, is not loaded a second time (compared by path, then by content)." The dedupe is the useful detail. The community's standard workaround — echo '@AGENTS.md' > CLAUDE.md — does not double-load under this mode, because the plugin compares by path first and then by content.

`managed-only` — "the project's checked-in and private instruction files and the person's own are dropped from the context; the organization's managed CLAUDE.md and the engine's memory stay." This is the enterprise lockdown setting: what the organisation ships, and nothing a repo or an individual adds.

There is also a legacy key, projectInstructions, still honoured and mapped onto the new values: none → managed-only, claude → claude-md, agents-fallback → claude-md-or-agents-md, both → claude-md-and-agents-md. If you set that key months ago and forgot, it is still in force and it is the reason your precedence does not match the blog posts.

Because the plugin registered itself against a remote feature flag that defaulted to off.

In the shipped bundle the registration reads var W = !1; — isOnByDefault is false — and the gate is var B = () => Oa("tengu_agents_md_mod", W);, a lookup of the flag tengu_agents_md_mod with false as the fallback. Fetching that flag requires a network call. Disable the call and you get the fallback: the plugin never activates, AGENTS.md is never read, and nothing warns you.

Either of these was enough to trigger it:

export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
export DISABLE_TELEMETRY=1

The failure mode is nasty for a specific reason: reading a local Markdown file needs no network access, so nobody debugging "my instructions are ignored" thinks to re-enable telemetry. The agent runs, answers, and behaves as though the project has no conventions at all.

Here is the test that settles it in two commands — a canary word in a file the agent should have read:

mkdir /tmp/agents-canary && cd /tmp/agents-canary
printf 'The project canary word is PERIWINKLE.\n' > AGENTS.md
claude -p 'What is the canary word from the project instructions?'

If the answer contains PERIWINKLE, your instruction file loaded. If the agent says it has no such information, it did not — and on an affected version, adding more detail to AGENTS.md will not change that. This is worth keeping in your repo as a smoke test regardless of version; it is the only check that distinguishes "the agent read my conventions and disagreed" from "the agent never saw them."

The workaround while pinned to 2.1.277–2.1.279 is a one-line CLAUDE.md:

echo '@AGENTS.md' > CLAUDE.md

The @path import is handled by the engine, not the plugin, so it never consulted the flag. The real fix is upgrading to 2.1.280 or later.

Three situations where the choice is not arbitrary.

A monorepo with per-package conventions. Packages carry their own AGENTS.md; the repo root has a CLAUDE.md with build and review rules. On the default claude-md-or-agents-md, that root file wins the whole tree and every package-level AGENTS.md is inert — the exact case the "root down to working directory" rule describes. You want claude-md-and-agents-md, so root rules and package rules both load. This is the single most common misconfiguration I would expect in 2026, because the repo looks correct and behaves as though half the files are empty.

Two agents, one repo. The common setup is Claude Code plus Codex, or plus Cursor. Put shared conventions in AGENTS.md — Codex and Cursor read it — and keep CLAUDE.md for what is genuinely Claude-specific: slash commands, subagent definitions, hook behaviour, MCP server expectations. Under claude-md-and-agents-md both load and each tool gets what it can use. Under the default, adding any CLAUDE.md silently disables the shared file for Claude Code only, which produces the worst possible symptom: two agents that follow different rules on the same codebase, with no error anywhere.

A regulated team on Bedrock or Vertex. Use managed-only when the organisation's conventions must be the only ones in context and a contributor's checked-in file cannot override them. Note the interaction with the bug above: these are exactly the deployments that were affected before 2.1.280, so verify with the canary test rather than assuming. Managed instructions and a silently-disabled plugin look identical from the outside until you check.

Four ways to get one set of instructions into Claude Code, compared on what actually differs.

The honest reading: @AGENTS.md from a one-line CLAUDE.md is still the most robust option in September 2026. It is version-independent, immune to the flag bug, survives every instructionFiles mode, and costs one line. Native AGENTS.md is cleaner once your whole team is on 2.1.280+ and you have set the mode deliberately. Symlinks work until a Windows contributor commits the link as a text file.

One thing no mode changes: the nested-file semantics. A nested AGENTS.md "attaches on a text Read only," so directory-level conventions arrive when the agent reads a file in that directory — not up front.

If you have a CLAUDE.md that works and you run only Claude Code, native AGENTS.md support gives you nothing. On the default mode your existing file wins the whole tree; adding AGENTS.md beside it is a no-op that will confuse the next person who reads the repo. Skip it.

Four documented limitations are worth weighing before you migrate, none of which appear in the guides currently ranking:

Nested files attach on a text Read only. The engine also attaches a directory's CLAUDE.md for a file @-mentioned in the prompt, for the IDE's opened file or selection, and for the Read tool's notebook, image and PDF results. AGENTS.md does not get those paths — so on an image-heavy or notebook-heavy workflow, CLAUDE.md genuinely covers more.

A nested file the plugin attaches is not registered in the loop's read-file state, so after a compaction the engine does not restore it among the recently read files. On a long session that compacts several times, nested conventions can quietly fall out of context. Anything you cannot afford to lose belongs in the root file.

--add-dir directories contribute no AGENTS.md, where the engine can load their CLAUDE.md. If your workflow pulls in a sibling repo, that repo's conventions only arrive via CLAUDE.md.

/memory and the # shortcut do not know AGENTS.md files. The ergonomic path for adding a convention mid-session still writes to CLAUDE.md. On an AGENTS.md-only repo, that habit silently creates the very file that disables your AGENTS.md under the default mode.

That last one is a trap worth stating plainly: using # once, in an AGENTS.md-only project on the default setting, can turn your whole instruction set off. Not because anything broke — because a CLAUDE.md now exists, and existence is the test.

The migration is ten minutes. Making it hold is the actual work, and it is three things.

Pin the floor and say so. AGENTS.md behaviour differs across 2.1.277, 2.1.279 and 2.1.280. Put the minimum version in your contributing docs and in the instruction file itself. A team where half the developers are two patches behind has two different agent configurations and no way to see it.

Set the mode explicitly, in checked-in settings. Do not inherit the default and hope. Write instructionFiles into the project's settings so it is reviewable, and grep for the legacy projectInstructions key while you are there — an old value still wins and still maps onto the new modes.

Make the canary test CI, not folklore. The three-command check above is the only way to prove instructions loaded. Run it in CI on the version you pin, asserting the canary word appears. Every instruction-file bug I have seen reduces to nobody being able to answer "did the agent actually read this?" — and the difference between an agent that ignored your conventions and one that never received them changes what you fix.

The deeper failure mode is not configuration. Teams write a 400-line CLAUDE.md, watch the agent behave inconsistently, and add another 200 lines. Cutting the file in half usually works better, because instruction files compete with the actual task for attention, and 2.1.277's own change — counting instruction files together for the size notice — is Anthropic telling you the same thing. What earns its place is what the repo cannot be read to discover: the migration you must not run, the deploy path, the one test that must pass. Not a restatement of your directory structure.

If your team is standing up Claude Code across a real codebase and wants this set up once, properly — modes, pinned versions, a CI check that proves instructions load — that is the work I do as a Claude Code consultant. Instruction files are usually one layer of it; the other is the tool surface the agent gets, which is MCP integration work. For teams who want that capability built in-house rather than handed over, I take fractional forward deployed engineer engagements a couple of days a week.

Q: Does Claude Code read AGENTS.md? Yes, since version 2.1.277 (18 September 2026). On the default setting it reads AGENTS.md only in a project with no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in any directory from the root down to the working directory. If one exists anywhere on that path, AGENTS.md is ignored.

Q: Which file wins, CLAUDE.md or AGENTS.md? CLAUDE.md, on the default claude-md-or-agents-md mode. Set instructionFiles to claude-md-and-agents-md in the agents-md@builtin plugin config and both load, up and down the tree, with a file already @-imported deduped by path and then by content.

Q: Why is my AGENTS.md being ignored? Three likely causes. A CLAUDE.md exists somewhere between the repo root and your working directory. You are on 2.1.277–2.1.279 with DISABLE_TELEMETRY=1 or CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1, or on Bedrock, Vertex, Foundry or a gateway — all fixed in 2.1.280. Or a legacy projectInstructions setting is still pinning the mode.

Q: Do I need both CLAUDE.md and AGENTS.md? Only if you run more than one agent. Put shared conventions in AGENTS.md for Codex and Cursor, keep Claude-specific configuration in CLAUDE.md, and set claude-md-and-agents-md so both load. Running Claude Code alone, one file is enough.

Q: What is the safest way to share one instruction file across agents? A one-line CLAUDE.md containing @AGENTS.md. The engine handles @ imports, so it worked through the flag bug, works on every instructionFiles mode and every version, and does not break on Windows checkouts the way a symlink can.

A one-line changelog entry cost some teams five days of an agent quietly ignoring every convention they had written down, and the tell was never an error message — it was output that looked plausible and followed none of the rules.

That is the shape of most production AI work: not the model, the wiring around it. If you want it done once and verifiable, I take fixed-scope pilots and longer founding engineer engagements with teams shipping AI into real products.