Claude Code Now Reads AGENTS.md: What Changed in 2.1.277

On September 18, 2026, support for AGENTS.md was added in Claude Code 2.1.277. If the feature is available in the session and in the working directory, and there is no CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md anywhere in the directory chain above it, Claude Code reads AGENTS.md by default without a manual import. Previously, this was done through an @AGENTS.md import in CLAUDE.md or through a CLAUDE.md symbolic link to AGENTS.md—for more details, see the article about one instructions file for several agents.

If you use Claude Code and one or two other tools in the same repository, the Project instructions mode you choose determines which instruction files Claude Code reads. Below are the conditions for each of the four modes and the steps for switching from the old setup.

More materials on configuring tools are available in the Ailoot documentation.

What changed in Claude Code 2.1.277’s support for AGENTS.md?#

The official Claude Code project CHANGELOG.md on GitHub puts it this way:

Translation: support for AGENTS.md has been added—in a project without CLAUDE.md, Claude Code now reads AGENTS.md instead; this can be switched in “Project instructions” in /config (not yet available on Bedrock, Vertex, or Foundry).

Before this version, the absence of CLAUDE.md, .claude/CLAUDE.md, and CLAUDE.local.md in the working folder and above did not, by itself, enable reading of AGENTS.md. An explicit import, symbolic link, or manual hook was required. Now, when the feature is available, the agent picks up the file automatically.

Which files block automatic reading of AGENTS.md#

If you have a personal ~/.claude/CLAUDE.md with coding style settings, it will not prevent Claude Code from reading the project AGENTS.md. But any CLAUDE.local.md in the working folder—even one not added to Git and used for personal notes—blocks automatic reading of AGENTS.md in the default mode. An explicit import continues to work; to read both files directly, you need to switch modes.

If a direct-reading mode is selected under Project instructions (see “4 Project instructions modes—which one to choose” below) and there is no CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md in the working directory or above, Claude Code reads every AGENTS.md and .claude/AGENTS.md in those directories when the session starts. For the case with no blocking files, the documentation shows a line like this in an interactive session:

no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md

An AGENTS.md file in a subdirectory is loaded when Claude opens a file there using the Read tool. In claude-md-or-agents-md mode, this happens only if that subdirectory does not have its own CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md. For claude-md-and-agents-md, the documentation describes the general rule: CLAUDE.md and AGENTS.md are read together, with CLAUDE.md first and then AGENTS.md in each directory. AGENTS.local.md, AGENTS.override.md, and anything in the .agents/ directory are not read automatically.

Materials on configuring an AI agent's workspace, including instruction files containing project context, are available in the Ailoot documentation.

4 Project instructions modes—which one to choose#

The behavior of the modes in the table is described in Anthropic's documentation. The right column gives recommendations for choosing one:

You can also choose the mode without the interface, through settings.json:

{
  "pluginConfigs": {
    "agents-md@builtin": {
      "options": {
        "instructionFiles": "claude-md-and-agents-md"
      }
    }
  }
}

Claude Code ignores this value in project and local settings. According to Anthropic's documentation, it can be set in ~/.claude/settings.json, in a --settings file, or in organization-managed settings.

If you have already configured a shared instruction file for several AI tools in one repository, the instructions for versions before 2.1.277 explain how the @ import works. This method still works today.

Why isn't Project instructions in /config#

First check the version with the claude --version command. If it is below 2.1.277, update Claude Code. If the version is suitable but the section still does not appear, check the other reasons listed above. While the feature is unavailable, importing @AGENTS.md in CLAUDE.md remains a working fallback.

What to do with the old @AGENTS.md import#

The next steps depend on the old setup. First, make sure the feature is available in your session, as described in the previous section.

• CLAUDE.md with an @AGENTS.md import. You can leave it as is—Claude Code will not read the file twice under any Project instructions value. Deleting CLAUDE.md is optional: the import already gives Claude access to the contents of AGENTS.md. Continue to check loading through the import using /memory; a direct question to Claude about the contents of the instructions is only a weak check.
• CLAUDE.md that asks in words to read AGENTS.md. Such a request is not an import and does not, by itself, guarantee that the file will be loaded. Replace the wording with an @AGENTS.md import if you want to keep CLAUDE.md (for example, for tools that also read it). If you decide to delete CLAUDE.md entirely and have claude-md-or-agents-md mode selected, first check that CLAUDE.md contains no unique instructions and that there is no other CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md in the working directory or above; otherwise, Claude Code will keep reading the remaining file instead of AGENTS.md. After deleting it, make sure the transition has taken place: when no blocking files remain, the line AGENTS.md loaded appears in an interactive session. If CLAUDE.md remains and both files are read in claude-md-and-agents-md mode, check /memory (in version 2.1.280+). A direct question to Claude cannot distinguish direct loading from an import.
• CLAUDE.md symbolic link to AGENTS.md. You can keep it: there will be no duplicate reading in any mode. Before deleting the link in claude-md-or-agents-md mode, check that the needed instructions are preserved and that there is no other CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md in the working directory or above it. Check loading in the same way: the AGENTS.md loaded line at session start when no blocking files exist, or /memory (2.1.280+). If CLAUDE.md remains in claude-md-and-agents-md mode, a direct question to Claude is only a weak check. The absence of an error is not enough to confirm loading.
• A SessionStart hook that manually printed the contents of AGENTS.md. When the file is read directly, such a hook adds a second copy to the context. While the hook is running, the question “what is in your instructions?” does not confirm direct loading: Claude may answer based on text added by the hook. Switch in this order:
  1. Check that the feature is available: version 2.1.277 or higher, the session receives feature flags, the plugin is enabled, and the first session after installation or update is complete. Choose a direct-reading mode—neither claude-md nor managed-only. For the default mode, also check that there are no blocking files.
  2. Remove the hook.
  3. Close the session and open a new one. The SessionStart hook adds its text at startup, so its contents remain in the context of an already-open session. Claude's answer about the instruction contents in such a session will not confirm direct loading.
  4. Check loading in the new session. In version 2.1.280+, the path to AGENTS.md is visible in /memory. In versions 2.1.277–2.1.279, if there are no blocking files, look for the AGENTS.md loaded line at startup: the documentation describes it specifically for the case where no CLAUDE.md was found. If you keep CLAUDE.md and use claude-md-and-agents-md mode, checking is limited: /memory does not show AGENTS.md in these versions, the documentation does not describe a load line for this case, and a paraphrase of the instructions cannot distinguish direct reading from an @ import inside CLAUDE.md. In that case, update to 2.1.280+ and check /memory.

How to check that AGENTS.md loaded#

Two more differences from ordinary CLAUDE.md: InstructionsLoaded hooks do not fire for this kind of AGENTS.md (they do work for AGENTS.md imported via @ syntax from CLAUDE.md or connected by a CLAUDE.md symbolic link); directories added with the --add-dir flag together with the CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD variable load only that directory's CLAUDE.md—its AGENTS.md is not included.

If you need to review the contents of a large project instruction file, see the separate analysis on how to configure CLAUDE.md without making it bloated. It covers the structure of instructions, while the conditions for loading AGENTS.md are described above.

What next#

The feature was released on September 18, 2026, in version 2.1.277. Anthropic may clarify details of the modes in future releases, so before changing settings in an important project, compare this article with the current /config and the official changelog.