AGENTS.md

What is AGENTS.md, and why does this file exist?

AGENTS.md is a cross-tool project-instructions spec meant to let one project description file be shared across multiple AI coding tools, instead of each tool maintaining its own differently-formatted file with largely duplicate content. Reporting from The Register notes this spec was originally pushed mainly by the OpenAI camp, and Anthropic's decision in the September 18, 2026 v2.1.277 release to have Claude Code support it too effectively acknowledges a real maintenance burden: repos accumulating CLAUDE.md, AGENTS.md, .cursorrules, and similar near-identical instruction files side by side.

Before v2.1.277, Claude Code only recognized CLAUDE.md and didn't read AGENTS.md at all — an import or symlink was the only workaround to make its content take effect. After that release, the official documentation states plainly that "if there's no CLAUDE.md in a folder, Claude will check for and use AGENTS.md" instead — no workaround needed anymore.

If both CLAUDE.md and AGENTS.md exist in a repo, which one actually gets read?

The official default is claude-md-or-agents-md mode: as long as a CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md exists at or above the current directory, Claude Code loads only those and skips AGENTS.md entirely — AGENTS.md only gets read as a fallback when no CLAUDE.md variant exists anywhere in that directory tree. This is configurable: claude-md-and-agents-md loads both together (CLAUDE.md first, with deduplication), claude-md ignores AGENTS.md completely, and managed-only restricts loading to the organization's managed CLAUDE.md only.

The detail most easily missed: CLAUDE.local.md (a developer's personal, not-version-controlled config file) counts exactly the same as a shared CLAUDE.md for the purpose of "does a CLAUDE.md variant exist." That means if a team's repo only uses AGENTS.md, but one developer creates a CLAUDE.local.md for their own personal settings, under the default mode that developer's Claude Code silently stops reading the team's shared AGENTS.md — while teammates without that file are unaffected.

If a team already maintains an AGENTS.md and wants Claude Code to pick up its content without maintaining two duplicate files, what's the least work?

A community-written operations guide lists two methods that remain valid from the pre-v2.1.277 era: add a single @AGENTS.md import line at the top of CLAUDE.md, which Claude Code loads at session startup before continuing on to any Claude-specific instructions further down in CLAUDE.md; or create a symlink pointing CLAUDE.md directly at AGENTS.md. On Windows, creating a symlink requires Administrator privileges or Developer Mode, making the @AGENTS.md import method more practical for cross-platform teams.

Separately, running /init in a repo that already has an AGENTS.md also reads its content and folds it into the auto-generated CLAUDE.md, offering a one-time consolidation option without having to write the import line by hand.

I've configured everything but Claude Code still isn't reading AGENTS.md — where should I start debugging?

First confirm the version is at or after v2.1.277 (September 18, 2026) — this feature has a clear cutoff date, and tutorials circulating online are a mix of old and new, making it easy to land on an outdated explanation. Next, check which platform you're on: this feature hasn't yet extended to Bedrock, Vertex, or Foundry. Also, a session without feature-flag access, or with telemetry disabled, can't read AGENTS.md either, and a fresh Claude Code install doesn't have this capability active until after its first session completes.

If all of that checks out, check whether a CLAUDE.local.md unexpectedly exists somewhere in the directory tree — this is the most commonly overlooked cause. It causes Claude Code to determine "a CLAUDE.md already exists" and skip AGENTS.md entirely, and because this file typically doesn't show up in version control history, it's easy to miss while debugging.