Does Claude Code Support AGENTS.md? The Complete 2026 Reference

A common question after Claude Code starts mainstream adoption: does Claude Code support AGENTS.md? Teams already using AGENTS.md for OpenAI Codex, Cursor, or other agents naturally want one source of truth. The expected answer is “yes” — but the actual answer is more nuanced.

Claude Code does NOT read AGENTS.md directly. This is explicit in Anthropic’s official documentation (May 2026): “Claude Code reads CLAUDE.md, not AGENTS.md.”

This reference walks through:

• Why Claude Code does not read AGENTS.md directly
• The three official integration patterns Anthropic recommends
• How /init behaves when AGENTS.md already exists
• Windows-specific symlink considerations
• What teams maintaining both files should know

The Official Statement

From code.claude.com/docs/en/memory (May 2026):

Claude Code reads CLAUDE.md, not AGENTS.md. If your repository already uses AGENTS.md for other coding agents, create a CLAUDE.md that imports it so both tools read the same instructions without duplicating them. You can also add Claude-specific instructions below the import.

So Claude Code’s stance is: stick with CLAUDE.md as the entrypoint, but make AGENTS.md feed into it. The mechanisms below all preserve this design while letting AGENTS.md remain the source of truth for cross-tool instructions.

Why Not AGENTS.md Directly?

Anthropic’s reasoning (inferred from doc context and design decisions):

1. Backward compatibility — CLAUDE.md was introduced before AGENTS.md became a cross-tool standard. Existing Claude Code users have CLAUDE.md committed to repositories.
2. Claude-specific extensions — Claude Code supports @import, claudeMdExcludes, .claude/rules/ path-scoped rules, and other features that aren’t in the AGENTS.md spec.
3. Hierarchy semantics — Claude Code loads CLAUDE.md from ancestor directories (parent → current → subdirectories), which is more nuanced than AGENTS.md’s flat discovery.
4. Auto memory integration — Claude Code’s auto memory writes to ~/.claude/projects/<project>/memory/, which interacts with CLAUDE.md loading order.

Forcing AGENTS.md to behave like CLAUDE.md would either break the AGENTS.md spec for other tools, or fragment Claude Code’s loading semantics.

Integration Pattern 1: Import AGENTS.md via @-syntax

This is the recommended pattern for repositories that want AGENTS.md as the source of truth and need Claude-specific extensions.

# CLAUDE.md

@AGENTS.md

## Claude Code Extensions

- Use plan mode for changes under `src/billing/`
- Run `npm run test:integration` before commits to `prod/**`
- Subagent: `code-reviewer` should auto-run on PR generation

How this works:

1. Claude Code starts a session and loads CLAUDE.md
2. The @AGENTS.md directive expands AGENTS.md content inline
3. Claude-specific instructions follow

The first time Claude encounters an @import, it shows an approval dialog listing the files. Once approved, future sessions read the imports silently.

Maximum import depth: 5 hops. AGENTS.md can itself import other files, and so on, but the chain caps at 5.

Path resolution: Imports are relative to the file containing them, not the working directory. @AGENTS.md resolves to ./AGENTS.md from CLAUDE.md’s location.

Integration Pattern 2: Symlink (Unix-like systems)

For repositories where Claude-specific extensions aren’t needed, a symlink is simpler:

ln -s AGENTS.md CLAUDE.md

Now Claude Code reads AGENTS.md via the CLAUDE.md symlink. No duplication, no @import to manage.

Tradeoff: Cannot add Claude-specific content below the symlink, since the file IS AGENTS.md. If you later need Claude-specific extensions, you’ll need to convert the symlink to a regular file with @AGENTS.md import.

Windows Note

On Windows, creating a symlink requires Administrator privileges OR Developer Mode enabled. For teams with mixed OS environments:

• Linux/macOS developers: symlink works
• Windows developers: get an error or warning when checking out the repo

Recommendation for cross-platform teams: Use @AGENTS.md import (Pattern 1) instead. It works identically on all OSes.

Integration Pattern 3: Maintain Both Files Independently

For teams that want maximum flexibility, you can maintain CLAUDE.md and AGENTS.md as separate files with overlapping content.

project-root/
├── AGENTS.md       # For Codex, Cursor, other tools
└── CLAUDE.md       # For Claude Code, may share common rules

When this makes sense:

• The AGENTS.md content is sensitive to formatting that Claude doesn’t need
• Different audiences read each file (e.g., AGENTS.md targets Codex-specific phrasing, CLAUDE.md targets Claude-specific phrasing)
• The teams maintaining each file don’t have organizational overlap

When this is risky:

• Drift — one file gets updated, the other doesn’t, agents behave differently
• Conflict — contradictory rules in each file produce inconsistent outputs

For most teams, Pattern 1 (@import) is the safest default.

What /init Does When AGENTS.md Exists

Running /init in a repo that already has AGENTS.md triggers a special flow:

Running /init in a repo that already has an AGENTS.md reads it and incorporates the relevant parts into the generated CLAUDE.md. It also reads other tool configs like .cursorrules and .windsurfrules.

Specifically:

1. Claude reads AGENTS.md
2. Claude reads .cursorrules and .windsurfrules if present
3. Claude generates a CLAUDE.md that synthesizes the relevant parts
4. You review and edit before committing

This is the “smart conversion” path for migration. If you’re moving an AGENTS.md-first repo to also use Claude Code, /init does the heavy lifting of producing a sensible starting CLAUDE.md.

With CLAUDE_CODE_NEW_INIT=1, an interactive multi-phase flow asks:

• Which artifacts to set up (CLAUDE.md, skills, hooks)
• Which sections of AGENTS.md should be Claude-specific vs shared
• Whether to use @AGENTS.md import or generate a standalone CLAUDE.md

The interactive flow is the cleanest way to bootstrap a Claude Code setup in an existing AGENTS.md repo.

What About Subdirectory CLAUDE.md / AGENTS.md?

Both CLAUDE.md and AGENTS.md (when AGENTS.md is imported via @) follow Claude Code’s directory hierarchy rules:

• CLAUDE.md files in ancestor directories are loaded at startup
• CLAUDE.md files in subdirectories load on demand when Claude reads files there

If you have:

monorepo/
├── CLAUDE.md       # Loaded at startup
├── AGENTS.md       # Imported by CLAUDE.md via @AGENTS.md
└── packages/
    └── auth/
        ├── CLAUDE.md  # Loaded when Claude reads files in packages/auth/
        └── AGENTS.md  # NOT automatically read by Claude Code

The packages/auth/CLAUDE.md should explicitly import packages/auth/AGENTS.md if needed:

# packages/auth/CLAUDE.md

@AGENTS.md

## Auth-Specific Claude Code Rules

- Always use `bcrypt.hash` not `crypto.scrypt` in this directory
- Run `npm run test:auth` before edits

The claudeMdExcludes Setting

In monorepos with multiple teams, you can exclude specific CLAUDE.md files using claudeMdExcludes:

{
  "claudeMdExcludes": [
    "**/other-team/CLAUDE.md",
    "/home/user/monorepo/legacy/.claude/rules/**"
  ]
}

This doesn’t affect AGENTS.md (since Claude Code doesn’t read AGENTS.md directly), but if other teams’ CLAUDE.md import their AGENTS.md, excluding the parent CLAUDE.md effectively excludes their AGENTS.md too.

Migration Strategies

From AGENTS.md-only to Claude Code-compatible

# Option A: Symlink (Unix only, no Claude-specific extensions)
ln -s AGENTS.md CLAUDE.md

# Option B: Import (cross-platform, allows extensions)
echo "@AGENTS.md" > CLAUDE.md
# Add Claude-specific rules below

From CLAUDE.md-only to multi-agent compatible

# Move shared content to AGENTS.md
mv CLAUDE.md AGENTS.md

# Create new CLAUDE.md that imports AGENTS.md
echo "@AGENTS.md" > CLAUDE.md

# Add Claude-specific rules below the import line

Splitting an existing CLAUDE.md into AGENTS.md + Claude-specific extensions

# Original CLAUDE.md
## Project Architecture
[shared content]

## Coding Standards
[shared content]

## Claude Code Hooks
[Claude-specific]

## Subagent Permissions
[Claude-specific]

Becomes:

# AGENTS.md (shared with Codex, Cursor, etc.)
## Project Architecture
[shared content]

## Coding Standards
[shared content]

# CLAUDE.md (Claude Code-specific)
@AGENTS.md

## Claude Code Hooks
[Claude-specific]

## Subagent Permissions
[Claude-specific]

Edge Cases

What if AGENTS.md uses headers/syntax Claude doesn’t expect?

AGENTS.md spec doesn’t restrict markdown syntax, and Claude Code reads markdown flexibly. As long as the content is valid markdown, Claude will load it. The only practical issue is token consumption — overly long AGENTS.md files reduce adherence. Keep both files under 200 lines total when possible.

Can AGENTS.md import other files using @-syntax?

The @import syntax is a Claude-specific extension. AGENTS.md as imported by CLAUDE.md can use @import because Claude Code expands those imports recursively. But if Codex or Cursor read AGENTS.md directly, they will likely treat @import as literal text.

For maximum cross-tool compatibility, avoid @import in AGENTS.md and keep all imports in CLAUDE.md.

What about CLAUDE.local.md and AGENTS.local.md?

CLAUDE.local.md is a Claude-specific extension for personal preferences (gitignored). There’s no AGENTS.local.md in the standard spec. Use CLAUDE.local.md for Claude-specific personal preferences, or extend Claude Code’s loading hierarchy with ~/.claude/CLAUDE.md for user-level rules.

Comparison Table: AGENTS.md Support Across Tools

Claude Code is the only major agent that requires an explicit bridge file. This is by design to preserve CLAUDE.md’s specialized features.

Related Articles

• AGENTS.md vs CLAUDE.md: What’s the Difference and When to Use Each
• AGENTS.md and GitHub Copilot: Integration Guide
• AGENTS.md for OpenAI Codex: Complete Setup Guide
• Caveman.MD: The Complete 2026 Guide to AGENTS.md Token Compression
• Claude Code Plugins: The Complete 2026 Reference

FAQ

Does Claude Code support AGENTS.md natively?

No. Claude Code reads CLAUDE.md, not AGENTS.md. To use AGENTS.md content in Claude Code, import it into CLAUDE.md with @AGENTS.md syntax, or create a symlink (ln -s AGENTS.md CLAUDE.md on Unix).

Why doesn’t Claude Code read AGENTS.md directly?

Anthropic’s design preserves CLAUDE.md as the entrypoint to maintain backward compatibility, support Claude-specific features (auto memory, path-scoped rules, claudeMdExcludes), and use Claude Code’s hierarchical loading semantics that differ from AGENTS.md’s flat discovery.

What does /init do when AGENTS.md exists?

/init reads AGENTS.md, plus .cursorrules and .windsurfrules if present, and generates a CLAUDE.md that synthesizes the relevant parts. With CLAUDE_CODE_NEW_INIT=1, an interactive flow guides splitting shared vs Claude-specific content.

Can I use a symlink on Windows?

Yes, but it requires Administrator privileges or Developer Mode. For cross-platform teams, use @AGENTS.md import instead — it works identically on all OSes.

What’s the maximum @import depth?

5 hops. AGENTS.md can itself import other files via @, and so on, but the chain caps at 5.

Should AGENTS.md use @import syntax?

Not for cross-tool compatibility. Codex and Cursor will likely treat @import as literal text. Keep all imports in CLAUDE.md, and let CLAUDE.md import AGENTS.md (which itself contains no @import).

Does claudeMdExcludes affect AGENTS.md?

Not directly, but if AGENTS.md is imported by a CLAUDE.md that gets excluded, the entire chain (including AGENTS.md) is skipped.

What if my AGENTS.md is in a subdirectory?

Subdirectory CLAUDE.md files load on demand. Each subdirectory CLAUDE.md should explicitly import its sibling AGENTS.md if needed: @AGENTS.md.