Claude Code Now Reads AGENTS.md: Configuration, Modes, and Caveats

Title

Claude Code Now Reads AGENTS.md: Configuration, Modes, and Caveats

Meta Description

Claude Code v2.1.277+ automatically reads AGENTS.md when a repository lacks CLAUDE.md. This article explains the priority logic of the four project instruction modes, how to configure them via the settings key, and practical caveats such as content conflicts and version compatibility.

Article Content

In its latest version v2.1.277+, Claude Code introduced an important change: when a repository has no CLAUDE.md file, it will automatically read AGENTS.md as project instructions. This seemingly minor change touches on a long-standing fragmentation problem in the AI coding tool ecosystem—the format war over project-level instruction files.

Why AGENTS.md Matters

In the AI coding assistant space, different tools have long defined their own formats for project instruction files. Claude Code uses CLAUDE.md, Cursor has its own rules files, and other tools have their own approaches. AGENTS.md emerged in an attempt to provide a cross-tool common standard, allowing the same project instructions to be reused across multiple AI coding assistants.

Claude Code's choice to fall back to AGENTS.md when CLAUDE.md is missing is essentially a compromise between compatibility and its own ecosystem: it neither fully abandons the priority of CLAUDE.md nor ignores the community's demand for a common standard. For development teams using multiple AI coding tools simultaneously, this means maintaining a single AGENTS.md may cover more scenarios and reduce the cost of duplicate configuration.

AGENTS.md is an open-standard initiative aimed at unifying the project instruction format for AI coding assistants, driven by the community rather than led by any single vendor. Its core idea is to use a tool-agnostic Markdown file to carry contextual information such as project structure, coding conventions, test commands, and build processes, so that different assistants like Claude Code, Cursor, and GitHub Copilot can all read the same instructions. In contrast, CLAUDE.md is the native format Anthropic defined for Claude Code, and Cursor's .cursorrules or rules directory are also tool-private. The value of standardization lies in reducing configuration duplication when multiple tools coexist, but the cost is that tools may differ in field semantics, priority, and parsing details—so "universal" is currently more of a direction than a guarantee.

How the Four Project Instruction Modes Work

Claude Code has designed four modes for project instructions, which determine the priority and reading behavior between CLAUDE.md and AGENTS.md.

The Core Logic of the Modes

The differences among these four modes are mainly reflected in two dimensions: whether AGENTS.md is read, and how to handle the situation when both files exist simultaneously. The default behavior is that CLAUDE.md takes priority—as long as CLAUDE.md exists in the repository, Claude Code will not look at AGENTS.md. Only when CLAUDE.md is missing does AGENTS.md enter the reading scope.

The other modes allow developers to adjust this priority, for example by forcing AGENTS.md to be ignored, or by merging and reading both when they coexist. This design gives teams flexibility: projects in transition can gradually migrate from CLAUDE.md to AGENTS.md without having to switch all at once.

Controlling Behavior via the Settings Key

The four modes are not switched via command-line arguments but controlled by a settings key. This means the configuration can be written into project-level or user-level settings files and distributed along with the repository, so team members don't need to memorize parameters individually. For teams that need to unify AI assistant behavior, this centralized configuration approach is more reliable than per-person configuration.

In Claude Code's configuration system, settings keys are typically written into JSON files such as .claude/settings.json (project-level) or ~/.claude/settings.json (user-level), and can also be overridden via environment variables or managed policies. Project-level configuration is distributed with the repository and takes effect as soon as the team clones it; user-level configuration applies to all projects on the local machine. Priority generally follows the principle of "project overrides user, specific overrides global." Understanding this is important: the four instruction modes are controlled by the settings key, which means their effective scope depends on which level the configuration is written to. Teams should explicitly place key configuration in project-level files to avoid inconsistent behavior caused by differences in personal local settings.

Caveats in Practical Use

Although the fallback mechanism is designed relatively conservatively, there are still several pitfalls in practical use.

The most direct issue is content conflict. If a repository has both CLAUDE.md and AGENTS.md and their contents are inconsistent, AGENTS.md will be completely ignored in the default mode. Developers may mistakenly believe that the instructions in AGENTS.md have taken effect, when in fact only CLAUDE.md was read. During migration, keeping the two files in sync or explicitly deleting one of them is a necessary step to avoid confusion.

Version compatibility also requires attention. The ability to read AGENTS.md is only supported starting from v2.1.277+, and team members using older versions of Claude Code will not get the same behavior. If a team relies on AGENTS.md as the sole source of instructions, it needs to confirm that all members have upgraded, otherwise the same repository will behave inconsistently on different machines.

Another detail is the positioning of AGENTS.md. It is designed as a cross-tool standard, but how each tool parses its contents may not be entirely consistent. How Claude Code interprets the instructions in AGENTS.md when reading it may differ from other tools. Treating AGENTS.md as absolutely portable configuration without actual verification is a risky practice.

Version pinning is also an easily overlooked aspect. Claude Code's auto-update behavior, the globally installed npm version, and the fixed version numbers in CI environments can all cause different execution environments to fall on opposite sides of the v2.1.277 dividing line. It is recommended to explicitly record the minimum version requirement in team documentation or CI configuration, and to do a simple regression verification after upgrading: confirm in a test repository without CLAUDE.md that AGENTS.md is indeed being read. In addition, if AGENTS.md is shared by multiple tools, avoid writing special syntax that is only meaningful to one tool; keeping the content as general-purpose natural language instructions will make portability more reliable.

Impact on AI Coding Workflows

The signal value of this change is greater than the feature itself. It shows that mainstream AI coding tools are beginning to take the standardization of project instructions seriously, rather than continuing to reinforce their own private formats. For developers, the most practical short-term benefit is that in repositories without CLAUDE.md, Claude Code is no longer completely "blind" but can obtain project context through AGENTS.md.

In the long run, if more tools follow suit in supporting AGENTS.md, project-level AI instructions are expected to move from "one set of configuration per tool" to "one file reused in multiple places." But the realization of this vision depends on whether tools converge in their interpretation of the standard, and whether the community is willing to treat AGENTS.md as the primary carrier rather than a fallback option. Claude Code's current approach—CLAUDE.md first, AGENTS.md as fallback—is a pragmatic intermediate state that retains control over its own ecosystem while leaving an interface for standardization.

For teams currently using Claude Code, it is recommended to first confirm the version, then decide whether to introduce AGENTS.md based on the project's current situation. If the team only uses Claude Code, continuing to use CLAUDE.md is perfectly fine; if multiple AI coding tools are used simultaneously, the reuse value of AGENTS.md begins to emerge.

One-line Summary

Claude Code falls back to reading AGENTS.md when CLAUDE.md is absent, balancing compatibility and standardization.

Paragraph Summary

Claude Code v2.1.277+ introduces a change: when a repository lacks CLAUDE.md, it automatically reads AGENTS.md as project instructions. The article notes that this touches on the long-standing fragmentation of project instruction file formats in AI coding tools, with AGENTS.md attempting to provide a cross-tool common standard. Claude Code has designed four project instruction modes, centrally controlled by a settings key, which determine whether AGENTS.md is read and the priority when both files coexist, with CLAUDE.md taking priority by default. In practical use, attention must be paid to content conflicts causing AGENTS.md to be ignored, incompatibility with older versions causing inconsistent behavior, and portability risks arising from parsing differences across tools. The article argues that the signal value of this move is greater than the feature itself, and that it is a pragmatic intermediate state that retains its own ecosystem while leaving an interface for standardization, recommending that teams first confirm the version and then decide whether to introduce AGENTS.md based on whether multiple tools are used together.