[BUG] CLAUDE.local.md switches off the AGENTS.md fallback, so a personal note silently drops all shared project instructions

Preflight Checklist

• [x] I have searched existing issues. Closest: #95589 (AGENTS.md loading is intermittent with no CLAUDE.md anywhere) and #96005 (dedup of the AGENTS.md fallback against other instruction channels). Neither covers CLAUDE.local.md. This one is deterministic: 5/5 runs in every scenario below.
• [x] This is a single bug report
• [x] I am using the latest version of Claude Code (2.1.280)

What's Wrong?

In the default instructionFiles mode (claude-md-or-agents-md), a CLAUDE.local.md counts as "the project has a CLAUDE.md". When one exists anywhere on the path from cwd to the project root, no AGENTS.md is loaded at all, including the ones in parent directories.

CLAUDE.local.md is the personal, usually gitignored file. A developer who adds a private note to a repo that keeps its shared instructions in AGENTS.md loses every project rule, and nothing tells them: no warning, no startup notice. The session looks like a project that has no shared instructions.

Each scenario was run 5 times with claude -p, asking for a codeword stored in each file (AGENTS.md holds PINEAPPLE42, CLAUDE.local.md holds MANGO7):

| Files | cwd | AGENTS.md loaded | CLAUDE.local.md loaded |
|---|---|---|---|
| AGENTS.md | root | 5/5 | n/a |
| AGENTS.md, CLAUDE.local.md | root | 0/5 | 5/5 |
| AGENTS.md, CLAUDE.local.md, CLAUDE.md containing @AGENTS.md | root | 5/5 | 5/5 |
| root AGENTS.md | sub/ | 5/5 | n/a |
| root AGENTS.md, sub/CLAUDE.local.md | sub/ | 0/5 | 5/5 |
| sub/AGENTS.md, sub/CLAUDE.local.md | sub/ | 0/5 | 5/5 |

The cause appears to be in the bundled agents-md plugin, which puts CLAUDE.local.md in the list of names that switch the fallback off and then skips every AGENTS.md when any ancestor matches:

var z=["AGENTS.md",".claude/AGENTS.md"];
var C=["CLAUDE.md",".claude/CLAUDE.md","CLAUDE.local.md"];
// prompt.context
w = ... || await s.fs.ancestors({names:C}).then((d)=>d.length>0, ...)
let T = w ? [] : await s.fs.ancestors({names:z})

What Should Happen?

CLAUDE.local.md adds to the project instructions without deciding whether AGENTS.md loads. Only a committed CLAUDE.md or .claude/CLAUDE.md should switch the fallback off, since that is the file a project uses in place of AGENTS.md.

If the current behavior is intended, it should at least be visible: a startup notice such as agents-md: AGENTS.md skipped because <path>/CLAUDE.local.md exists, and a line in the docs.

Error Messages/Logs

None. The session prints no notice when AGENTS.md is skipped.

Steps to Reproduce

1. Create a repo containing only an AGENTS.md:

``sh
mkdir repro && cd repro && git init -q
echo "The project codeword is PINEAPPLE42." > AGENTS.md
``

1. Ask for the codeword:

``sh
claude -p "Without using any tools, answer only from instructions already in your context. Reply exactly: project=<project codeword or NONE>; local=<local codeword or NONE>"
`
Output: project=PINEAPPLE42; local=NONE`

1. Add a personal note:

``sh
echo "The local codeword is MANGO7." > CLAUDE.local.md
``

1. Run the same command as step 2. Output: project=NONE; local=MANGO7
2. Optional: move CLAUDE.local.md to sub/ and run the same command from sub/. Output: project=NONE; local=MANGO7, so the root AGENTS.md is still dropped.

Ask for both codewords. If you ask only for "the project codeword", the model reports MANGO7 in step 4, because it takes the local codeword as the answer.

Workaround: a committed CLAUDE.md containing @AGENTS.md loads both files (5/5, third row of the table). According to its option description, /config > Project instructions > claude-md-and-agents-md should also work, but I did not test it.

Claude Model

Opus

Is this a regression?

No, this never worked

Last Working Version

_No response_

Claude Code Version

2.1.280 (Claude Code)

Platform

Anthropic API

Operating System

Other Linux

Terminal/Shell

Non-interactive/CI environment

Additional Information

• Default instructionFiles (not set in any settings file); tengu_agents_md_mod is true in ~/.claude.json.
• A user-level ~/.claude/CLAUDE.md does not trigger this. A repo under $HOME still loads its AGENTS.md (3/3).
• Found while migrating a monorepo from CLAUDE.md to AGENTS.md. We kept one-line CLAUDE.md files containing @AGENTS.md next to each AGENTS.md specifically to avoid this.