[FEATURE] Always load AGENTS.md by default, even when CLAUDE.md exists, and make CLAUDE.md optional

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

Summary

Claude Code 2.1.277 added native AGENTS.md support through the built-in agents-md plugin. The default mode, claude-md-or-agents-md, loads AGENTS.md only when no CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md exists in the working directory or any directory above it. Teams therefore still have to keep a CLAUDE.md shim in every repository, so the new support does not let them stop maintaining CLAUDE.md.

Why the current default is not enough

• Multi-repo workspaces. A CLAUDE.md in a workspace directory that holds many checkouts disables AGENTS.md in every repository below it. No repository's AGENTS.md loads until each one gets its own CLAUDE.md shim or each user changes the setting.
• Personal notes. A CLAUDE.local.md also disables AGENTS.md (#96117).
• Unavailable sessions. The docs list sessions where AGENTS.md support is unavailable: third-party providers, telemetry disabled, and the first session after an upgrade. In those sessions only CLAUDE.md loads, so a team with any such member has to keep a CLAUDE.md shim in every repository.
• Discoverability. claude-md-and-agents-md is available only through /config or pluginConfigs."agents-md@builtin".options.instructionFiles in settings.json. Most users do not know it exists.

Related

• #6235: original AGENTS.md support request, 5,183 upvotes and 407 comments, now closed
• #34235: asks for AGENTS.md alongside CLAUDE.md, with CLAUDE.md taking precedence
• #96117: CLAUDE.local.md disables the AGENTS.md fallback
• #95589: AGENTS.md loads intermittently on 2.1.278

Proposed Solution

AGENTS.md is the project instruction file, with no setting to find or change:

1. Claude Code loads AGENTS.md wherever and however it loads CLAUDE.md, whether or not a CLAUDE.md exists. A CLAUDE.md, when present, loads beside it as a Claude-specific addition, and an AGENTS.md that a CLAUDE.md imports, links to, or symlinks loads once. This is the current claude-md-and-agents-md behavior made the default, so users never need to know the instructionFiles option exists.
2. AGENTS.md loading does not depend on feature-flag fetching, so it works on Bedrock, Vertex, and Foundry, with telemetry disabled, and in the first session after an install or upgrade.
3. CLAUDE.md is deprecated as the primary file: /init writes AGENTS.md, and the memory docs present AGENTS.md as the project instruction file and CLAUDE.md as optional. Existing CLAUDE.md files keep loading indefinitely; deprecation here means AGENTS.md becomes the documented default, not that CLAUDE.md support is removed.

With these in place, a repository can delete its one-line @AGENTS.md CLAUDE.md shim or remove the symlink and nothing changes for any user.

The change is additive: a repository with only CLAUDE.md sees no difference, and one whose CLAUDE.md already imports AGENTS.md loads the same content as today. The only affected repositories have both files without an import. For those, a one-line startup notice (like the existing "no CLAUDE.md found; AGENTS.md loaded: <path>") such as "AGENTS.md loaded beside CLAUDE.md: <path>" would make the change visible, and instructionFiles: "claude-md" remains available to opt out.

Alternative Solutions

• A one-line @AGENTS.md CLAUDE.md in every repository (current workaround). Works in every session type, but every repository carries a Claude-only file, and a new repository gets no instructions until someone adds one.
• CLAUDE.md as a symlink to AGENTS.md. Merges produce CONFLICT (distinct types) against branches where CLAUDE.md is a regular file, and checkouts without symlink support break.
• Setting instructionFiles to claude-md-and-agents-md per user (pluginConfigs."agents-md@builtin".options.instructionFiles in ~/.claude/settings.json). Works for the person who sets it. Every teammate has to find and set it, and it has no effect in sessions without feature-flag fetching.
• The current claude-md-or-agents-md default. Works in a standalone repository with only AGENTS.md, but any CLAUDE.md or CLAUDE.local.md in the same directory or above it switches AGENTS.md off.

Codex, Pi and many other coding harnesses read AGENTS.md natively, so a repository that keeps its instructions in AGENTS.md needs no tool-specific file for them.

Priority

Medium - Would be very helpful

Feature Category

Configuration and settings

Use Case Example

1. A workspace directory holds about 60 repository checkouts. Engineers work in it with both Claude Code and Codex, so each repository keeps its instructions in AGENTS.md, and the workspace root has an AGENTS.md with cross-repository conventions.
2. Under the current default, the workspace needs a CLAUDE.md for Claude to see the root instructions, and that CLAUDE.md switches AGENTS.md off in every repository below it. Each repository therefore carries a CLAUDE.md that exists only to import AGENTS.md. Some of those are one-line @AGENTS.md imports. Others are prose pointers ("See AGENTS.md") that load nothing, so Claude runs without the repository's instructions unless it decides to open the file.
3. With this feature, Claude Code loads the root AGENTS.md and each repository's AGENTS.md with no CLAUDE.md anywhere, the same way Codex does. The CLAUDE.md shims can be deleted, and a new repository gets its instructions as soon as it has an AGENTS.md.
4. This removes a Claude-only file from every repository, and with it the sessions that silently run without project instructions because a shim is missing or is only a prose pointer.

Additional Context

Tested on Claude Code 2.1.280 (macOS) in headless claude -p sessions, with pluginConfigs."agents-md@builtin".options.instructionFiles set to claude-md-and-agents-md:

| Directory contents | AGENTS.md content in context |
|---|---|
| AGENTS.md only | loaded |
| AGENTS.md and an unrelated CLAUDE.md | loaded |
| AGENTS.md, with CLAUDE.md a symlink to it | loaded once |
| Repository with its own CLAUDE.md, below a workspace directory that has only AGENTS.md | workspace AGENTS.md loaded |

The behavior this issue asks for already exists behind that option. The request is to make it the default and to remove the feature-flag dependency.