Claude Code v2.1.277 Can Keep Shared AGENTS.md When CLAUDE.md Exists

At a glance

Claude Corner tip

• Stop losing shared `AGENTS.md` playbooks when a repo also has `CLAUDE.md` or `CLAUDE.local.md`.
• Set Project instructions to `claude-md-and-agents-md` in `/config` (or the matching `pluginConfigs` setting) so both files load.
• Pin Claude Code to `v2.1.277` or newer before relying on native `AGENTS.md` support.

You keep one `AGENTS.md` for Codex and other agents, then add a Claude-specific `CLAUDE.md` (or a personal `CLAUDE.local.md`), and Claude Code quietly stops reading `AGENTS.md`. Under the default Project instructions value `claude-md-or-agents-md`, any `CLAUDE.md`, `.claude/CLAUDE.md`, or `CLAUDE.local.md` in the working directory or above it wins, so the shared file never loads. From v2.1.277 you can flip Project instructions to `claude-md-and-agents-md` and keep both.

Why it matters

Cross-tool repos want one instruction file that every agent can share. Claude-only notes still belong in `CLAUDE.md`, but the default fallback means adding that file hides `AGENTS.md` instead of layering on it. Teams then re-paste conventions, or they invent symlinks and `@AGENTS.md` imports that duplicate context. Reading both is the deliberate split: shared rules stay in `AGENTS.md`, Claude-specific guidance stays in `CLAUDE.md`, and managed policy still applies. Pair it with Claude Corner: Subagent Prompt Bloat → Set omitClaudeMd when the risk is worker context bloat, and use this setting when the risk is the parent session never seeing the shared playbook. The one move: pin past v2.1.277, set Project instructions to both files, and confirm Claude can quote `AGENTS.md` content.

How to load AGENTS.md beside CLAUDE.md

Works in Claude Code CLI and in Desktop or VS Code sessions that expose `/config`. Prefer Claude Code `v2.1.278` (or newer) so you keep current auto-mode classifier defaults while taking AGENTS.md support from `v2.1.277`.

1. Confirm the pin: `claude –version` should report at least `v2.1.277` (prefer `v2.1.278+`). 2. In the repo, keep (or create) `AGENTS.md` for shared agent rules and `CLAUDE.md` for Claude-only notes. 3. In a session, run `/config`, open Project instructions, and choose `claude-md-and-agents-md`. 4. Optional fleet pin: set the same value under `pluginConfigs[“agents-md@builtin”].options.instructionFiles` in `~/.claude/settings.json`, a `–settings` file, or managed settings (not project/local settings files). 5. Start a fresh session in that repo and ask what its project instructions say, or look for the default-path `AGENTS.md loaded` notice when no CLAUDE.md is present on a test branch.

#!/usr/bin/env bash
set -euo pipefail

# Native AGENTS.md support needs v2.1.277+; prefer current fleet pin when already on it.
npm install -g "@anthropic-ai/claude-code@2.1.278"
claude --version  # expect v2.1.278 (minimum for this tip: v2.1.277)

# Example: shared playbook + Claude-only addendum in the same repo root.
cat > AGENTS.md <<'MD'
# Shared agent rules
- Run unit tests before proposing a commit.
- Prefer small, reviewable diffs.
MD

cat > CLAUDE.md <<'MD'

... click "Show full code" below to expand

#!/usr/bin/env bash
set -euo pipefail

# Native AGENTS.md support needs v2.1.277+; prefer current fleet pin when already on it.
npm install -g "@anthropic-ai/claude-code@2.1.278"
claude --version  # expect v2.1.278 (minimum for this tip: v2.1.277)

# Example: shared playbook + Claude-only addendum in the same repo root.
cat > AGENTS.md <<'MD'
# Shared agent rules
- Run unit tests before proposing a commit.
- Prefer small, reviewable diffs.
MD

cat > CLAUDE.md <<'MD'
# Claude-only
- Use plan mode before edits under src/billing/.
MD

# Persist "read both" in user settings (ignored if placed only in project/local settings).
mkdir -p ~/.claude
python3 - <<'PY'
import json
from pathlib import Path
path = Path.home() / ".claude" / "settings.json"
data = json.loads(path.read_text()) if path.exists() else {}
pc = data.setdefault("pluginConfigs", {})
entry = pc.setdefault("agents-md@builtin", {})
opts = entry.setdefault("options", {})
opts["instructionFiles"] = "claude-md-and-agents-md"
path.write_text(json.dumps(data, indent=2) + "\n")
print("Wrote", path)
PY

# Interactive check: /config → Project instructions → claude-md-and-agents-md
claude -p "Summarize which project instruction files you loaded (CLAUDE.md, AGENTS.md, or both). Quote one line from each if present."

Gotchas

• Default remains `claude-md-or-agents-md`: if any counting `CLAUDE.md` / `CLAUDE.local.md` exists on the path, `AGENTS.md` is skipped unless you choose both (or import `@AGENTS.md` from `CLAUDE.md`).
• `~/.claude/CLAUDE.md`, managed policy `CLAUDE.md`, and `.claude/rules/` do not count as the CLAUDE.md that hides `AGENTS.md`.
• Bedrock, some third-party providers, and telemetry-disabled sessions may not load `AGENTS.md` directly; import it from `CLAUDE.md` there instead.
• Direct `AGENTS.md` reads do not appear under `/memory` or `/context` Memory files the way `CLAUDE.md` does; confirm with the loaded notice or by asking Claude.
• `AGENTS.local.md`, `AGENTS.override.md`, and `.agents/` directories are not read through this setting.
• This how-to is for Claude Code / Desktop project instructions. It is not an API Messages request shape.

Recommended AI prompt

Copy this paragraph into ChatGPT, Claude, Gemini, Grok, or whatever you use.

You are helping me configure Claude Code so repositories that already use AGENTS.md for other coding agents still load that file when a CLAUDE.md is present. Context: from Claude Code v2.1.277, Project instructions defaults to claude-md-or-agents-md (CLAUDE.md wins and AGENTS.md is skipped when any CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md exists in the working directory or above). Setting Project instructions to claude-md-and-agents-md loads both, with CLAUDE.md first and AGENTS.md after in each directory. The same value can be set under pluginConfigs agents-md@builtin options.instructionFiles in user, –settings, or managed settings. Ask which repos have AGENTS.md only, CLAUDE.md only, or both, which Claude Code version we pin (minimum v2.1.277), and whether we use Bedrock or telemetry-off sessions that need an @AGENTS.md import instead. Then produce (1) a short decision table for which Project instructions value to use, (2) a sample CLAUDE.md plus AGENTS.md split, (3) a verification prompt to confirm both loaded, and (4) gotchas about CLAUDE.local.md hiding AGENTS.md and about /context not listing direct AGENTS.md reads. Keep it concrete and copy-paste ready.