Claude Code v2.1.277 Reads AGENTS.md When CLAUDE.md Is Missing

TL;DR: Starting with Claude Code v2.1.277 (18 Sep 2026), if a project has no CLAUDE.md, Claude Code reads AGENTS.md instead, and the behavior is configurable in /config (changelog, memory docs). If you already keep agent instructions for Codex, Cursor, or other tools in AGENTS.md, that file just became load-bearing for one more consumer — and the failure mode is silent, not loud.

What happened

The change is narrow and worth stating precisely, because the details decide whether it affects your repo at all:

• Version: Claude Code v2.1.277, dated 18 Sep 2026 (changelog).
• The rule: if no CLAUDE.md exists in the project, Claude Code reads AGENTS.md (memory docs).
• It is configurable: the behavior can be turned on or off in /config (memory docs).
• Not yet supported on Bedrock, Vertex, or Foundry (memory docs).
• Who announced it: an Anthropic engineer, with the change documented in the official changelog (announcement, changelog).

That is the whole news. No migration tool, no new file format, no deprecation of CLAUDE.md. It is a fallback path: CLAUDE.md still wins when present, and AGENTS.md is only consulted in its absence.

The Bedrock/Vertex/Foundry carve-out is the part most likely to bite someone reading a summary instead of the docs. If your team runs Claude Code through one of those providers, the fallback is not there yet, and a repo that relies on it will behave differently depending on how each developer launched the tool.

What developers are saying

The reaction, as summarized in the news, is broadly positive and centers on one theme: interoperability with Codex and Cursor, and the end of maintaining duplicated project rules. Posts appeared across several languages — English, Japanese, and Chinese — in roughly the 17 hours after the announcement (announcement, one example, another).

I am not going to invent quotes or attribute positions to specific people beyond what those posts say. The shape of the conversation is what matters: people who already maintain AGENTS.md for other agents see this as one less file to keep in sync, and the subtext is that per-agent rule files had become a maintenance tax rather than a feature.

There is no visible backlash in the summary, but there rarely is on announcement day. The interesting complaints tend to arrive a week later, once someone's CI job starts behaving differently.

The practical problem this creates

Here is the scenario that should worry you, and it is not exotic.

A repo has three tools pointed at it. Codex reads AGENTS.md. Cursor reads its own rules file. Claude Code, until now, read CLAUDE.md. Someone on the team — usually whoever got annoyed first — wrote AGENTS.md with real content: build commands, test invocation, the fact that the integration suite needs a local Postgres, the convention that migrations are generated and never hand-edited.

CLAUDE.md exists too, but it is stale. It was written months ago, it mentions a make test target that was renamed, and it says the API lives under /v1 when it moved to /v2. Nobody deleted it because nobody was sure whether it was still needed.

Before v2.1.277, that stale file was harmless-ish: Claude Code read it, got slightly wrong context, and a human occasionally corrected it. After v2.1.277, the situation is unchanged in that repo — CLAUDE.md still takes precedence, so the fallback never fires. The change only matters where CLAUDE.md is absent.

So the real scenario is the inverse: a repo where CLAUDE.md was deliberately deleted, or never existed, and where AGENTS.md was written for a different agent with different assumptions. Now Claude Code silently starts reading it. If that file contains instructions tuned for another tool — a different test command, a different package manager, an instruction to always run a codegen step — Claude Code will follow them, and nothing in the output will say "I am following AGENTS.md now."

The second-order problem is divergence. The news explicitly names the developer pain: maintaining CLAUDE.md plus AGENTS.md, or per-agent rule sets, in multi-tool projects, where the rules drift apart and the maintenance becomes overhead. This change removes one duplication path but does not remove the underlying problem, because CLAUDE.md still takes precedence when it exists. If you keep both, you still have two files, and now you have a precedence rule to remember on top.

A third issue: the Bedrock/Vertex/Foundry gap. If part of your team runs Claude Code against one of those providers, the same repo will resolve instructions differently for different people. That is a debugging session waiting to happen, and the symptom will look like "the agent forgot our conventions" rather than "the agent read a different file."

What to do about it

These are steps you can take today, in order of how much they reduce surprise.

1. Find out which files exist and which one wins

Run this in each repo you care about. It tells you whether the fallback is even reachable.

# Which instruction files exist at the repo root?
for f in CLAUDE.md AGENTS.md .cursor/rules; do
  if [ -e "$f" ]; then echo "present: $f"; else echo "absent:  $f"; fi
done

If CLAUDE.md is present, the fallback does not apply and you can stop here — but read step 2 anyway, because "present and stale" is its own problem.

2. Decide on one canonical file, and make the other a pointer

The cheapest way to avoid divergence is to have exactly one file with real content. If you want AGENTS.md to be canonical, CLAUDE.md can be a one-line redirect rather than a copy:

<!-- CLAUDE.md -->
Project instructions live in AGENTS.md. Read that file and follow it.

This keeps precedence explicit: Claude Code reads CLAUDE.md, which tells it to read AGENTS.md. You maintain one file. The pointer file changes roughly never.

The opposite choice — CLAUDE.md canonical, AGENTS.md a pointer — works too, but check whether your other tools follow pointers or expect content. Do not assume; test it.

3. Check /config before you rely on the fallback

The behavior is configurable (memory docs). That means two developers on the same repo can have different settings, and the repo alone will not tell you which. If your team standardizes on the fallback, say so somewhere a human will read it — the onboarding doc, the PR template, wherever your team actually looks.

4. Audit AGENTS.md as if it were production config

If Claude Code is now going to read a file that was written for another agent, read it yourself first. The things that break are boring:

• Test commands that assume a different runner.
• Package manager instructions (pnpm vs npm) that conflict with the lockfile in the repo.
• Instructions to run codegen or migrations that you do not want triggered on every session.
• Paths that moved.
• Rules that were true for a different model's context window and are now just noise.

None of this is a Claude Code problem. It is the ordinary problem of a config file that grew without an owner.

5. Keep the provider gap in mind

If anyone on the team uses Bedrock, Vertex, or Foundry, the fallback is not supported there yet (memory docs). Do not write a repo setup that only works on one path. The pointer-file approach in step 2 sidesteps this entirely, because it does not depend on the fallback firing.

6. If you script against an OpenAI-compatible API, keep the model name out of the code

This is not about instruction files, but it is the adjacent habit that pays off when you are swapping models across agents. Hardcoding a model string in application code means every swap is a code change. Reading it from config means it is a config change:

# Illustrative example only — not production code.
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["YOUR_API_KEY"],
    base_url="https://YOUR_GATEWAY_URL/v1",
)

MODEL = os.environ.get("MODEL_NAME", "YOUR_MODEL_NAME")

resp = client.chat.completions.create(
    model=MODEL,
    messages=[{"role": "user", "content": "Summarize this diff."}],
)

The point is not the specific client library. The point is that "which model" should be a value, not a literal, so that a swap does not require a deploy.

Where a single OpenAI-compatible key for many models fits

This is the part where I have to be careful, because it is easy to overstate.

This change is about an instruction file. It is not an Anthropic endorsement of any gateway, and nothing here should be read as one. The fallback to AGENTS.md has nothing to do with how you authenticate or which endpoint you call.

The connection is at the workflow level, not the file level. Developers who run several agents and several models — Claude Code plus Codex plus whatever else — are the same developers who end up with per-agent rule files and per-provider billing. The news removes one duplication (rule files) and leaves the other (keys, billing, model switching) untouched.

That is where a gateway with one OpenAI-compatible key across many models is relevant: not because it changes how AGENTS.md is read, but because the multi-model workflow that makes AGENTS.md worth standardizing is also the workflow where managing N keys and N billing relationships gets tedious. BeefAPI is an OpenAI-compatible gateway with prepaid USD credit and one key for 21 models, aimed at developers who switch models often (pricing, site).

If you are evaluating that kind of setup, the pricebook is the honest place to look, and it is worth reading as a price list rather than a performance claim. As read at 2026-09-18T19:27:31Z it lists 27 models, including claude-sonnet-5 at $0.8 / $4 per 1M tokens (input / output, cache read $0.08), gpt-5.6-terra at $0.6 / $3.6 per 1M tokens (input / output, cache read $0.06), gemini-3.1-pro at $1 / $6 per 1M tokens (input / output, cache read $0.1), and qwen3.8-flash at $0.12 / $0.38 per 1M tokens (input / output, cache read $0.014). Cheaper models are cheaper; that says nothing about whether they are good enough for your task, and you should test that yourself.

Here is a worked example of how you might reason about cost, with made-up token counts, purely to show the arithmetic shape:

# EXAMPLE ONLY — invented token counts, not measured.
# Assume a task uses 200,000 input tokens and 50,000 output tokens.

model_a: $0.8 / $4 per 1M tokens
  input:  200,000 / 1,000,000 * $0.8 = $0.16
  output:  50,000 / 1,000,000 * $4   = $0.20
  total:  $0.36

model_b: $0.12 / $0.38 per 1M tokens
  input:  200,000 / 1,000,000 * $0.12 = $0.024
  output:  50,000 / 1,000,000 * $0.38 = $0.019
  total:  $0.043

Do not treat those totals as a recommendation. They exist to show that the input/output split matters, and that cache reads are priced separately from fresh input — which is the detail people miss when they compare two models by a single headline number.

Where this does not help: it does not fix divergent project rules. If your AGENTS.md and CLAUDE.md disagree, a gateway will faithfully route your request to whichever model you picked, and that model will faithfully read the wrong file. It also does not help if your problem is that Claude Code is not reading AGENTS.md at all — check /config, check that CLAUDE.md is genuinely absent, and check whether you are on Bedrock, Vertex, or Foundry, where the fallback is not supported yet (memory docs).

What to watch next

These are open questions from the news, not predictions:

• Does the Bedrock/Vertex/Foundry gap close? The docs currently say the behavior is not supported there (memory docs). Until it does, multi-provider teams have a split-brain setup.
• What does /config actually expose? The behavior is configurable (memory docs), but the practical question is whether teams can set it per-repo rather than per-machine. If it is per-machine, repo-level standardization is harder than it sounds.
• Does precedence stay this simple? Right now CLAUDE.md wins when present. Any future change to that ordering would silently flip which file a repo actually uses.
• Do other tools converge on AGENTS.md? The conversation is about interoperability with Codex and Cursor (announcement). Whether they all agree on precedence and file discovery is a separate question from whether they read the file.
• What breaks in CI? The posts summarized are from the first ~17 hours (one example, another). Non-interactive runs are where file-discovery changes tend to surface, and that signal has not arrived yet.

If you do one thing today: check whether CLAUDE.md exists in your repos, and if it does not, read the AGENTS.md that Claude Code is now going to follow. It takes two minutes and it is the difference between a config change and a mystery.

Disclosure: I work on BeefAPI.