CLAUDE.local.md Blocks AGENTS.md

The annoyance

I added CLAUDE.local.md so my sandbox URL would stay off git, the way the earlier note said, and I kept AGENTS.md because that is the file Cursor and Codex already read. From v2.1.277 Claude can read AGENTS.md, so I expected both, and the standing instructions were gone, and nothing threw.

I ran /context. Memory files listed CLAUDE.md and CLAUDE.local.md. AGENTS.md was not there. I had the usual suspects. A stale CLI. A worktree. Then I read the memory page. CLAUDE.local.md counts, so Claude reads the CLAUDE.md files only.

This is the 2.1.277 update to Claude Code ignores AGENTS.md. That note was the world before Claude looked for that name. It does now, and only when none of the three CLAUDE.md files sit in the working directory or above it, and CLAUDE.local.md is one of those three. Teams who keep both files hit the same silent miss.

What Anthropic actually says

From the official How Claude remembers your project page, under “AGENTS.md”, the default table is the exclusive one. User ~/.claude/CLAUDE.md, managed organisation files and .claude/rules/ do not count, and they keep loading alongside AGENTS.md. A project CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md in the working directory or above it does count:

“An AGENTS.md and a CLAUDE.md or CLAUDE.local.md in your working directory or above it — Your CLAUDE.md files only”

The personal project file is in that list. Official text:

“Because CLAUDE.local.md counts, adding one to keep your own uncommitted instructions in a project that relies on AGENTS.md stops Claude from reading AGENTS.md for you. To keep your CLAUDE.local.md and still have Claude read AGENTS.md, set Project instructions to claude-md-and-agents-md.”

Direct reads need the version, and some sessions never get them. Official text:

“Reading AGENTS.md directly requires Claude Code v2.1.277 or later. In some sessions, such as those on Amazon Bedrock or with telemetry disabled, Claude can't read AGENTS.md, so import it from a CLAUDE.md there instead.”

The same page adds the first session after the upgrade, disableAllHooks or allowManagedHooksOnly, and the built-in agents-md plugin turned off in /plugin. In those sessions Claude reads CLAUDE.md files only, and Project instructions does not appear in /config, so the import is the move.

The both-files value can also go under pluginConfigs in ~/.claude/settings.json, a --settings file, or managed settings. Official docs say Claude Code ignores it in project and local settings files.

And a direct read does not show up where we used to look:

“AGENTS.md doesn't appear in /memory or /context when Claude reads it directly, so check for the AGENTS.md loaded line or ask Claude what its project instructions say instead.”

The fix

If we want the local file and the cross-agent file in the same session, set Project instructions in /config:

# In-session: /config
# Set Project instructions to claude-md-and-agents-md.
# The change applies from the next message, and in every new session.

The same JSON looks finished in the project file, and from that file it does nothing:

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

Put that object in the user file, a --settings file, or managed settings if we want it as a default on this machine:

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

If the session cannot load AGENTS.md at all — Bedrock, telemetry off, the first session after the upgrade, hooks disabled, or the agents-md plugin off — Project instructions will not appear in /config, and the import is the documented move. That is still the standing fix from the earlier AGENTS.md note:

@AGENTS.md

## Claude Code

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

Keep the local file. CLAUDE.local.md is personal is still the right split for sandbox URLs and prefs. The miss is treating that file as invisible to the AGENTS.md check. It is not.

Prove it

Start a new session in a repo that has both files. Confirm the default is CLAUDE.md files only. Then set the both-files value and look for the loaded line, not a Memory files row.

# Start a new session in a repo that has AGENTS.md and CLAUDE.local.md.
# Default: Claude reads your CLAUDE.md files only.
# /memory and /context Memory files will not list AGENTS.md when it is read directly.
# After /config → Project instructions → claude-md-and-agents-md,
# look for the AGENTS.md loaded line in the conversation.
# Do not treat a missing Memory files row as proof it did not load.

Checklist

1. Confirm a CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md sits in the working directory or above it. That is the silent miss from v2.1.277.
2. Set Project instructions to claude-md-and-agents-md in /config if we want both files.
3. Or put the pluginConfigs object in ~/.claude/settings.json, managed settings, or a --settings file. Do not put it in the project or local file.
4. Or import with @AGENTS.md from a CLAUDE.md. Use that in Bedrock, telemetry-off, first-session-after-upgrade, and hooks-disabled sessions.
5. Do not use /memory or /context Memory files to prove a direct read. Look for the AGENTS.md loaded line.

Why it fails

I treated CLAUDE.local.md as personal-only, and I treated AGENTS.md as now-loaded from v2.1.277, and both pieces of advice are true, and together they collide. The local file looks finished. The cross-agent file is in the tree. Nothing throws. Same family as Claude Code ignores AGENTS.md and CLAUDE.local.md is personal — the file is present, the documented load rule is a different one, and the setting that keeps both lives in /config or the user file, not the project file.

If you want to run this with other operators rather than on your own, we are doing that in the public Skool community, and that is https://www.skool.com/navaigate.

Sources

• Anthropic — How Claude remembers your project
• Claude Code Ignores AGENTS.md
• CLAUDE.local.md Is Personal
• NavAIgate Skool community