An article I found says Claude Code doesn't support AGENTS.md — is the article wrong?
Not necessarily wrong — it's more likely written before the v2.1.277 release on September 18, 2026. Before that date, Claude Code genuinely only read CLAUDE.md, and "no AGENTS.md support" was an accurate description at the time, with import or symlink as the only workaround. When verifying information like this, checking the publish date of the article or documentation matters more than trusting the content outright — this feature's cutoff falls within just a month, so old and new information are circulating side by side, making it easy to land on an outdated version.
Our team wants to switch to AGENTS.md, but we're not sure if anyone has already created a CLAUDE.local.md. What's the quickest way to check?
The most direct approach is to have each team member check their own local repo root for a CLAUDE.local.md file — since this file is conventionally excluded from version control, looking at the repo itself won't reveal it; each person has to check on their own machine. If it's confirmed no one has created one, switching to AGENTS.md alone should go smoothly. If someone already has one, rather than asking them to delete their personal config file, a more practical approach is usually to switch to claude-md-and-agents-md mode, letting both files load together, so no one has to worry about which one gets skipped.
With four official modes (claude-md-or-agents-md, claude-md-and-agents-md, claude-md, managed-only), how should a typical team choose?
If a team has no need for a cross-tool shared instructions file, sticking with the default claude-md-or-agents-md or setting it explicitly to claude-md makes little practical difference, since there's no AGENTS.md around either way. If a team genuinely maintains a cross-tool shared AGENTS.md and is worried about conflicting or missing content between the two files, claude-md-and-agents-md mode loads both together with deduplication — a more conservative choice, at the cost of spending tokens on both files. managed-only is meant for organizations that need centralized control and don't want individual developers' local settings or AGENTS.md interfering — most small teams typically won't need it.
I'm not technical — I just manage the team's content-guideline documents. What's the practical impact on me?
If you're responsible for maintaining the guideline document your team shows AI tools (whether it's called CLAUDE.md or AGENTS.md), the most practical impact is this: first figure out exactly which file and which mode your team is actually using — don't assume "it's just an instructions file, doesn't matter which one." If your team uses multiple AI coding tools, consolidating into a single AGENTS.md format that Claude Code reads natively saves you the hassle of maintaining two duplicate documents — but only after confirming no one on the team is silently bypassing that shared guideline because of a personal config file. Otherwise you update AGENTS.md, and someone keeps working off an outdated version without either of you noticing.
If you've recently looked up whether Claude Code reads AGENTS.md, you've probably run into two contradictory answers: one says "No — Claude Code only reads CLAUDE.md; AGENTS.md only works through an @AGENTS.md import or a symlink." The other says "Yes, it's supported — if there's no CLAUDE.md in the folder, Claude Code automatically reads AGENTS.md instead." Both answers were correct at some point — they just describe different moments in time. Before Claude Code v2.1.277 (released September 18, 2026), it genuinely only read CLAUDE.md, and an import or symlink was the only way to get AGENTS.md content to take effect. After v2.1.277, the official documentation now states plainly that "if there's no CLAUDE.md in a folder, Claude will check for and use AGENTS.md" — this is native support, no workaround required anymore.
According to reporting from The Register, AGENTS.md started as a cross-tool project-instructions spec pushed largely by the OpenAI camp, intended to let a single project-description file be shared across multiple AI coding tools instead of each tool maintaining its own differently-formatted file with largely duplicate content. Anthropic's decision to support this spec in v2.1.277 effectively acknowledges a real maintenance burden teams were already facing: repos accumulating CLAUDE.md, AGENTS.md, .cursorrules, and similar near-identical instruction files side by side.
The official default behavior is the 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 loaded as a fallback when no CLAUDE.md variant exists anywhere in that directory tree. This behavior is configurable: claude-md-and-agents-md loads both files together (CLAUDE.md takes priority, with deduplication), claude-md ignores AGENTS.md completely, and managed-only restricts loading to the organization's managed CLAUDE.md only.
This is a detail several technical writeups go out of their way to flag: CLAUDE.local.md (a developer's personal, not-version-controlled config file) counts exactly the same as a shared CLAUDE.md when Claude Code checks "does a CLAUDE.md variant exist." In practice, that means if a team's repo only has AGENTS.md (a deliberate choice to use the cross-tool shared format), but one developer creates a CLAUDE.local.md just to store their own personal preferences, under the default mode that developer's Claude Code silently stops reading the team's shared AGENTS.md and reads only their own local file instead — while every other teammate without a CLAUDE.local.md continues reading AGENTS.md normally. This "same repo, different developers loading different instructions" scenario is particularly time-consuming to debug, precisely because everyone appears to be working from the same repo on the surface.
If a team already maintains an AGENTS.md shared with other tools and wants Claude Code to pick up its content without maintaining two duplicate files, 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 at AGENTS.md directly. 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 path.
This feature hasn't yet extended to platforms like Bedrock, Vertex, or Foundry; sessions without feature-flag access, or with telemetry disabled, can't read AGENTS.md either; and a fresh Claude Code installation doesn't have this capability active until after its first session completes. If you've followed the setup steps and it still isn't working, these platform or configuration limits are the first place to check.
If your team only uses Claude Code and has no need for a cross-tool shared instructions file, sticking with the default mode and continuing to use only CLAUDE.md is the simplest choice — no extra action needed. If your team uses multiple AI coding tools and wants to maintain a single cross-tool shared instructions file, AGENTS.md with native support genuinely removes the duplicate-maintenance burden — but confirm first whether anyone on the team has already created a CLAUDE.local.md, since that will silently cause that person's Claude Code to fall back to their own local file instead of the team's shared AGENTS.md, producing a gap where the same repo loads different instructions for different people.