Claude Code Now Reads AGENTS.md: CLAUDE.md vs AGENTS.md and the .claude Directory

What is claude.md, and what should you put in it?

CLAUDE.md is a plain-text Markdown file containing instructions that Claude Code reads into its session context. It gives you a place to record information you would otherwise repeat: build and test commands, coding conventions, project architecture, and workflow rules.

There is no required document format. You can organize it with ordinary Markdown headings and lists, choosing the structure that makes your project’s instructions easy to understand. Claude Code’s /init command generates a starter file based on the project, as described in the official best practices documentation.

A useful starting point is to cover four areas:

• Build and test commands: the commands contributors should use to build the project and check changes.
• Coding conventions: naming, formatting, and other conventions relevant to the repository.
• Project architecture: the main components and how they fit together.
• Workflow rules: the steps you want Claude to follow when making and checking changes.

Treat these as persistent guidance. Instructions enter Claude’s context; they are not enforced configuration. If you need to configure Claude Code itself, use the appropriate settings file rather than expecting prose in CLAUDE.md to function as a settings value.

The distinction matters when organizing a repository: project knowledge belongs in instruction files, while application configuration belongs in settings. The Claude Code guide hub provides a starting point for the surrounding workflow.

Where CLAUDE.md belongs

Claude Code supports shared project instructions and personal instructions at several locations. The instruction-file documentation describes these established locations and how instruction discovery works.

Ancestor instruction files load at launch. Files in subdirectories load on demand, allowing instructions to become relevant as Claude works in those parts of the project.

For shared instructions, choose a location that makes sense to your team. A root-level CLAUDE.md puts the guidance alongside the repository’s other top-level files. .claude/CLAUDE.md places it with the project’s Claude-specific files.

Personal instructions affect more than file organization

CLAUDE.local.md serves a different purpose from the shared project file: it holds your personal instructions for that project. In version 2.1.277, its presence also affects whether Claude Code falls back to AGENTS.md.

That means adding a local instruction file can change which shared instructions enter the context. Before creating one in a repository that relies on AGENTS.md, check the Project instructions setting described below.

The locations above come from living documentation whose exact September 19 wording was not verified. The fallback behavior in the next section is documented specifically for the tagged 2.1.277 release.

Does Claude Code read AGENTS.md automatically?

Yes, conditionally. The Claude Code 2.1.277 release notes state: “Added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead”.

The default behavior is a fallback, so the presence of an AGENTS.md file alone does not mean it will load. In this release, the check includes more than a root-level CLAUDE.md.

What suppresses the default fallback?

Any of these files anywhere along the path from the filesystem root to the working directory suppresses the default AGENTS.md fallback:

• CLAUDE.md
• .claude/CLAUDE.md
• CLAUDE.local.md

Managed instructions, personal instructions in ~/.claude/CLAUDE.md, and .claude/rules/ do not suppress that fallback.

For example, consider a repository with a shared AGENTS.md and no qualifying Claude instruction file along the ancestor path. The default mode reads the AGENTS instructions. If you then add CLAUDE.local.md, the default fallback is suppressed—even though the new file contains personal instructions rather than the team’s shared guidance.

How AGENTS.md discovery works

The built-in support is provided by the agents-md plugin, version 0.1.0. It discovers both AGENTS.md and .claude/AGENTS.md along the ancestor path and attaches nested instructions when Claude reads files below the project root.

Content already loaded through an import or link is deduplicated. This matters if a Claude instruction file already brings in the same AGENTS content.

As of the September 19 publication cutoff, the release announcement says this support is not yet available on Bedrock, Vertex, or Foundry.

Configure Claude Code to read one file or both

Open /config and change Project instructions to choose the instruction-loading behavior. The tagged v2.1.277 plugin README documents four exact values.

The README includes an important qualification for managed-only: nested CLAUDE.md attachments can still arrive. Do not interpret the value as a guarantee that no nested Claude instruction content can enter the conversation.

Exact configuration for version 2.1.277

To load both instruction families, use this configuration:

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

For this release, put it in user settings at ~/.claude/settings.json, a file supplied through --settings, or managed settings. Project .claude/settings.json does not supply these plugin options.

Changes apply when context is next rebuilt, such as on the next turn or in a new conversation. Keep that timing in mind when checking whether a setting has changed the loaded instructions.

Importing shared instructions remains an option

You can also place @AGENTS.md inside a neighboring CLAUDE.md. That explicitly imports the shared instructions through the Claude instruction file.

Claude instruction-file imports use @path/to/file.md and were introduced in v0.2.107. Version 2.1.277 deduplicates AGENTS content already imported by CLAUDE.md.

This gives you two ways to organize shared guidance: configure Claude Code to load both files, or use an import to bring AGENTS content into a Claude instruction file. Choose the arrangement that makes the relationship clear to repository contributors.

What belongs in the .claude directory?

The .claude directory holds several kinds of project files. They serve different purposes, so choose the location based on whether you are writing persistent guidance, configuration, a reusable prompt, a subagent definition, or a procedure.

Personal settings across projects live in ~/.claude/settings.json. Personal subagent definitions use ~/.claude/agents/, and personal skills use ~/.claude/skills/<name>/SKILL.md.

Commands, subagents, and skills

A command file such as .claude/commands/deploy.md creates /deploy. Version 2.1.3 merged slash commands and skills, and existing command files continue to work alongside skills.

Subagent definitions use Markdown with YAML frontmatter. The required fields are name and description; relevant optional fields include tools, model, and permissionMode. Manage them with /agents, and use the subagents guide for that part of your project setup.

Skills package reusable procedures in a folder containing SKILL.md, with optional scripts and reference material. Claude can select relevant skills, or you can invoke one with /skill-name; the skill body loads when used. The skills guide covers this workflow.

These structures predate the AGENTS fallback release. The tagged changelog confirms that project settings, commands, agents, and skills existed by v2.1.277. The detailed directory descriptions draw on living documentation whose exact cutoff-day wording was not verified.

CLAUDE.md versus auto memory

CLAUDE.md and auto memory differ in who writes the content. You write instruction files to define project guidance; Claude saves useful context into auto memory.

The tagged changelog records automatic saving and management through /memory in version 2.1.59. Auto memory therefore serves a separate role from the instructions you deliberately maintain in CLAUDE.md or AGENTS.md.

When deciding where information belongs, use that authorship distinction. Put explicit build commands, conventions, architecture notes, and workflow rules in your instruction files. Use /memory to manage the useful context Claude saves automatically.

Key takeaways

• CLAUDE.md contains persistent Markdown instructions that Claude Code reads into context; it does not enforce configuration.
• Claude Code 2.1.277 adds conditional AGENTS.md fallback, with Bedrock, Vertex, and Foundry excluded at release.
• An ancestor CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md suppresses the default fallback.
• Set Project instructions to claude-md-and-agents-md to load both instruction families.
• In v2.1.277, the plugin options belong in user settings, a --settings file, or managed settings—not project .claude/settings.json.
• The .claude directory also holds settings, commands, subagents, and skills; auto memory contains context saved by Claude.

FAQ

What is CLAUDE.md?

CLAUDE.md is a plain-text Markdown file containing persistent instructions for Claude Code, such as build commands, coding conventions, architecture notes, and workflow rules. Claude reads it into session context, and /init can generate a starter file based on the project.

Which file loads when both CLAUDE.md and AGENTS.md exist?

In Claude Code 2.1.277’s default claude-md-or-agents-md mode, a qualifying Claude instruction file suppresses AGENTS fallback. Select claude-md-and-agents-md to load both, or import neighboring AGENTS instructions with @AGENTS.md inside CLAUDE.md.

Why does adding CLAUDE.local.md stop AGENTS fallback?

Version 2.1.277 includes CLAUDE.local.md among the files that suppress default fallback when found from the filesystem root to the working directory. Its presence can therefore change whether shared AGENTS instructions load, even though its purpose is personal project guidance.

Can I enable both files in project .claude/settings.json?

In v2.1.277, project .claude/settings.json does not supply the agents-md plugin options. Use /config, or put the documented pluginConfigs configuration in user settings, a --settings file, or managed settings.