[FEATURE] AGENTS.md fallback per directory: wherever CLAUDE.md is looked up and not found, load AGENTS.md from that same directory

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

With the default claude-md-or-agents-md mode, one CLAUDE.md-type file anywhere in the tree switches off AGENTS.md for the whole tree, including files in directories that have no CLAUDE.md of their own.

I tested this on 2.1.293 with the default setting. Each case used a fresh git repo with a different marker word in each file. I checked what Claude Code attached in the saved session transcript, not what the model said. The prompt read sub/file.txt.

| Setup | AGENTS.md (root) | sub/AGENTS.md |
|---|---|---|
| Only AGENTS.md files | loads at start | loads when sub/ is touched |
| Same, plus a personal ~/.claude/CLAUDE.md | loads | loads |
| CLAUDE.md in the repo root | no | no |
| CLAUDE.local.md in the repo root (no CLAUDE.md) | no | no |
| .claude/CLAUDE.md (no CLAUDE.md) | no | no |
| CLAUDE.md in a directory above the repo (e.g. ~/code/CLAUDE.md) | no | no |
| CLAUDE.md only in sub/ | loads | no (sub/CLAUDE.md loads instead) |
| Only .claude/rules/*.md | loads | loads |

The sub/-only row shows that per-directory resolution already exists for nested directories. It just isn't applied everywhere.

What this breaks in practice:

• Workspace notes kill every repo's rules. A CLAUDE.md in a folder that holds many checkouts silently disables AGENTS.md in every repo under it. Nothing warns about it.
• A personal file drops shared rules. A CLAUDE.local.md with personal notes drops all the shared AGENTS.md rules (#96117).
• Nested AGENTS.md needs a shim per folder. Many repos keep a root CLAUDE.md that is just @AGENTS.md. The root AGENTS.md then loads, but no nested AGENTS.md ever does. Teams have to add a one-line CLAUDE.md (@AGENTS.md) next to every nested AGENTS.md. In a large monorepo that is a shim in every folder, and a missing one fails silently: that folder's rules never reach Claude, while other tools that read AGENTS.md still see them.

Proposed Solution

Resolve instruction files per location, not per tree.

For every place Claude Code looks for a CLAUDE.md, if no CLAUDE.md is found there, look for an AGENTS.md in that same place.

Concretely:

1. At startup, for each directory from the working directory up to the root: load CLAUDE.md / .claude/CLAUDE.md if present, otherwise that directory's AGENTS.md.
2. Lazily, when a file in a subdirectory is read or edited: load that subdirectory's CLAUDE.md if present, otherwise its AGENTS.md. This already happens in the sub/-only case above.
3. A CLAUDE.md in one directory never suppresses an AGENTS.md in another directory.
4. CLAUDE.local.md is personal and additive. It loads alongside whatever that directory resolves to and never counts as a replacement for AGENTS.md.
5. When a directory has both files, keep today's behaviour there: CLAUDE.md wins. A team that wants both writes @AGENTS.md in it, so nothing is loaded twice.

This keeps every current CLAUDE.md setup working unchanged. It removes the need for per-folder shims, and it makes AGENTS.md work the same way CLAUDE.md already does.

Alternative Solutions

• The claude-md-and-agents-md setting. It already fixes this: in my test it loaded nested AGENTS.md without shims, and didn't load an AGENTS.md twice when CLAUDE.md imports it. But it isn't the default, and it only works from user or managed settings, so a repo can't turn it on for its team.
• #96466 (always load AGENTS.md, even when CLAUDE.md exists). This request is the narrower version of it: a directory with a CLAUDE.md keeps working exactly as today, and AGENTS.md is used everywhere else.
• One-line CLAUDE.md shims next to every AGENTS.md, plus a CI check that none is missing. This is what we do now. It is easy to break: every new folder needs two files, and a missing shim fails silently.
• Symlinking CLAUDE.md to AGENTS.md. Edit/Write refuse to write through symlinks (#66559), and the links break on Windows checkouts.

Priority

Medium - Would be very helpful

Feature Category

Configuration and settings

Use Case Example

• A monorepo has AGENTS.md at the root and in many package folders, shared with other AI tools.
• The root CLAUDE.md holds a few Claude-only notes plus @AGENTS.md.
• Today: a package's AGENTS.md reaches Claude only if someone remembered to add a CLAUDE.md shim next to it.
• With the proposed fallback: editing packages/foo/src/x.ts loads packages/foo/AGENTS.md automatically, because that folder has no CLAUDE.md.
• A developer who keeps ~/code/CLAUDE.md (notes about all their repos), or a CLAUDE.local.md in the repo, no longer silently loses the team's rules.

Additional Context

Related: #96466 (load AGENTS.md always), #96117 (CLAUDE.local.md disables the fallback), #98796 (nested AGENTS.md not loaded on @-mention), #31005 / #6235 (AGENTS.md support).