Root AGENTS.md as project instructions

Claude Code 2.1.277+ can treat root AGENTS.md as project instructions when no project CLAUDE.md or CLAUDE.local.md is present. Docs: memory. Format overview: agents.md.

The 2.1.277 changelog entry reads: "Added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead; change it under 'Project instructions' in /config".

Later releases closed the early gaps

The changelog entry for 2.1.281 says AGENTS.md support now also covers Amazon Bedrock, Google Vertex AI, Microsoft Foundry, LLM gateways and sessions with telemetry disabled. The memory docs say /memory and /context list a directly loaded AGENTS.md from 2.1.280 on. The table and failure modes below note where older builds still differ.

Proprietary license and a usable built-in plugin

The repository's LICENSE.md reads: "© Anthropic PBC. All rights reserved. Use is subject to Anthropic's Commercial Terms of Service." The changelog lists releases up to 2.1.288 as of 3 October 2026. AGENTS.md loading ships as the built-in agents-md plugin, and the memory docs list the sessions where it is unavailable. We rate it usable.

Native load or an @AGENTS.md import

SituationDo this
Repo already has AGENTS.md only; first-party Anthropic API or claude.ai loginUpgrade to ≥2.1.277; rely on default claude-md-or-agents-md
Need Claude-specific rules plus shared AGENTS.mdSet Project instructions to claude-md-and-agents-md, or put @AGENTS.md at the top of CLAUDE.md
Team uses Bedrock, Vertex, Foundry, an LLM gateway, or disables telemetryUpgrade to ≥2.1.281 for direct load; on older builds keep the @AGENTS.md import inside CLAUDE.md
Personal notes in CLAUDE.local.md inside an AGENTS.md repoSwitch to claude-md-and-agents-md or move personal notes elsewhere
Migrating from Cursor or Copilot/init (and /import on newer builds) can fold other rule files into CLAUDE.md

Failure modes

  • Silent suppression: a leftover CLAUDE.local.md counts as a CLAUDE.md for the default check and blocks AGENTS.md.
  • Wrong override file: Claude Code does not read AGENTS.override.md, AGENTS.local.md, or .agents/ trees. Codex may. Mixed-agent repos can diverge.
  • Plugin disabled: if you disable the built-in agents-md plugin in /plugin, direct AGENTS.md load stops and Claude reads CLAUDE.md files only.
  • Confirmation gap on older builds: before 2.1.280, /memory and /context did not list an AGENTS.md loaded directly. On 2.1.280 or later, run /memory and look for its path. On older builds, look for the AGENTS.md loaded line or ask Claude what its project instructions say.
  • Upgrade lag: the memory docs say AGENTS.md may not load in the first session after an upgrade from 2.1.276 or earlier. It loads from the next session.

Minimal checklist

  1. claude --version ≥ 2.1.277
  2. Decide Project instructions value in /config
  3. Put shared instructions in AGENTS.md
  4. Add CLAUDE.md only for Claude-only policy, or as an @AGENTS.md import for cloud-provider sessions on builds before 2.1.281
  5. Verify on a fresh session before deleting any @AGENTS.md workaround

Changelog, memory docs, format home and license

The Claude Code changelog, the memory docs, the AGENTS.md format home and the repository license are listed under Sources below.