# Claude Code Now Reads AGENTS.md: What Changed in 2.1.277
> On September 18, 2026, Claude Code 2.1.277 gained direct support for AGENTS.md: when the file is loaded, how to choose one of 4 modes, and what to do about imports.
Source: https://ailoot.ai/blog/en/claude-code-agents-md-support/
Canonical: https://ailoot.ai/blog/en/claude-code-agents-md-support/
Language: en
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-041
Revision: sha256-39fa3735faa17d6b342601d656d26914794523d2785c25ca98bd27cce5f69720
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](https://ailoot.ai/blog/en/agents-md-claude-md-one-instruction-file/).
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](https://ailoot.ai/docs/).
[Ailoot Guides](https://ailoot.ai/docs/)
## What changed in Claude Code 2.1.277’s support for AGENTS.md?
Key takeaway
As of September 18, 2026, Claude Code reads `AGENTS.md` by default if there is no `CLAUDE.md`, `.claude/CLAUDE.md`, or `CLAUDE.local.md` anywhere in the directory chain from the working folder upward. If such a file exists, automatic reading of `AGENTS.md` through Project instructions is not enabled. An explicit `@AGENTS.md` import from `CLAUDE.md` continues to work. User-level `~/.claude/CLAUDE.md`, organization-managed `CLAUDE.md`, and `.claude/rules/` are loaded independently of the choice between project files. The mode is switched through `/config`. The feature is not yet available on Bedrock, Vertex, or Foundry.
The official Claude Code project CHANGELOG.md on GitHub puts it this way:
Added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead; change it under "Project instructions" in /config (not yet on Bedrock, Vertex or Foundry)
— Anthropic, claude-code CHANGELOG.md commit, ca02e7d, https://github.com/anthropics/claude-code/commit/ca02e7deeb0707f558b0afd7e9e5d67a382e12b3
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
Key takeaway
In the default mode, `CLAUDE.md`, `.claude/CLAUDE.md`, and `CLAUDE.local.md` are checked in the working directory and above. Personal `~/.claude/CLAUDE.md`, organization-managed `CLAUDE.md`, and `.claude/rules/` files do not block reading of `AGENTS.md` and are loaded alongside it.
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](https://ailoot.ai/docs/).
[Ailoot Guides](https://ailoot.ai/docs/)
## 4 Project instructions modes—which one to choose
Key takeaway
In the Project instructions section of the `/config` command, there are four values: `claude-md-or-agents-md` (default—one of the two files), `claude-md-and-agents-md` (both together), `claude-md` (only `CLAUDE.md` is read automatically, even if the project has only `AGENTS.md`), and `managed-only` (at startup—only the organization-managed `CLAUDE.md` and auto memory, with no project or personal files). The change takes effect with the next message sent and in every new session.
The behavior of the modes in the table is described in Anthropic's documentation. The right column gives recommendations for choosing one:
| Value | What Claude Code reads | When to use it |
|----|----|----|
| `claude-md-or-agents-md` | `CLAUDE.md`, or `AGENTS.md` if there is no `CLAUDE.md`, `.claude/CLAUDE.md`, or `CLAUDE.local.md` in the working directory or above | Default, if the repository uses only one of the two files and there are no blocking files above it |
| `claude-md-and-agents-md` | Both files together: in each directory, `CLAUDE.md` first, then `AGENTS.md` | You need a shared `AGENTS.md` for all tools plus a short `CLAUDE.md` only for Claude; or you need to read `AGENTS.md` when `CLAUDE.local.md` exists |
| `claude-md` | Only `CLAUDE.md`; automatic reading of `AGENTS.md` through Project instructions is disabled, even if `AGENTS.md` is the only file (an explicit `@AGENTS.md` import from `CLAUDE.md` still works) | `AGENTS.md` is written for another tool and could confuse Claude |
| `managed-only` | At session start—only the organization-managed `CLAUDE.md` and auto memory; project, local, and user `CLAUDE.md`, `.claude/rules/`, and all `AGENTS.md` files are excluded from the initial set. However, `CLAUDE.md` and `.claude/rules/` files in subdirectories are still loaded later when Claude opens a file there. The mode limits the initial set and does not provide full isolation from project files | For organizations that care which set of instructions Claude Code starts a session with, regardless of whether the project itself contains `CLAUDE.md` or `AGENTS.md` |
You can also choose the mode without the interface, through `settings.json`:
```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](https://ailoot.ai/blog/en/agents-md-claude-md-one-instruction-file/) explain how the `@` import works. This method still works today.
## Why isn't Project instructions in /config
Key takeaway
According to Anthropic's documentation, the Project instructions section may be missing for the following reasons:
- Claude Code is below version 2.1.277.
- The session does not receive feature flags from Anthropic—for example, when using Bedrock, another third-party provider, or telemetry is disabled.
- This is the first session immediately after installing or updating from an older version. If this is the only reason, the feature will appear in the next session. `AGENTS.md` itself will load only if the conditions of the selected mode are met.
- The built-in `agents-md` plugin is disabled in `/plugin`.
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
Key takeaway
You can keep the `@AGENTS.md` import in `CLAUDE.md` and the symbolic link: the file will not be read twice in any mode. A textual request to “read AGENTS.md” should be replaced with an import if you keep `CLAUDE.md`. Before deleting a file, save all needed instructions and check the conditions of the selected mode. If you switch to direct reading, remove any `SessionStart` hook that manually printed the contents of `AGENTS.md`; otherwise, a second copy of the file will enter the context. After that, check loading in a new session; the way to check depends on the version and whether blocking files exist.
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
Key takeaway
Starting with version 2.1.280, `AGENTS.md` loaded through Project instructions appears in `/memory` and in the Memory files list of the `/context` command. In versions 2.1.277–2.1.279, it does not appear there, even though the commands themselves work and show loaded `CLAUDE.md` and other memory files. In these versions, if there are no blocking files, check for the `AGENTS.md loaded` line at session startup. Asking Claude about the contents of the instructions is only a weak check: the answer cannot distinguish direct reading from an `@` import and may rely on text added by a `SessionStart` hook. Therefore, it makes sense to ask only in a new session after removing such a hook.
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](https://ailoot.ai/blog/en/claude-md-template/). 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.
### Sources
- [Claude Code, CHANGELOG.md commit with the 2.1.277 entry on GitHub (September 18, 2026)](https://github.com/anthropics/claude-code/commit/ca02e7deeb0707f558b0afd7e9e5d67a382e12b3)
- [Claude Code Docs: How Claude remembers your project - AGENTS.md section](https://code.claude.com/docs/en/memory)
[Ailoot Guides](https://ailoot.ai/docs/)
[Go to Ailoot](https://ailoot.ai/)
## Questions about Claude Code Now Reads AGENTS.md: What Changed in 2.1.277
### Why is AGENTS.md not loaded even though the file exists?
In the default mode, a CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md in the working directory or an ancestor blocks automatic AGENTS.md selection. Also check the Claude Code version, feature availability, and the Project instructions mode in /config.
### How can I verify direct loading after removing a manual hook?
Open a new session so the old SessionStart output is absent. In version 2.1.280 or later, inspect /memory or the Memory files list in /context; on 2.1.277-2.1.279, the startup loading line applies when no blocking CLAUDE.md files exist. A paraphrase from Claude alone is weak evidence.
## Ailoot · The company and its project portfolio
Ailoot combines established operating experience, a large client base, stable service and ongoing KPI control.
The company and its project portfolio: millions of customers; monthly sales in the billions.
Ailoot brings that operating experience to API access for AI features in customer products, agents, applications and automations.