AGENTS.md vs. CLAUDE.md: What Claude Code Actually Reads (And the Workaround for Both)

If you use Claude Code alongside any other AI tool - Cursor, Windsurf, Codex, Devin - you’ve probably run into this: you carefully write a CLAUDE.md for your project, then realize your other agent tools don’t read it. Or you adopt AGENTS.md because it’s becoming a standard, and discover Claude Code ignores it entirely.

This is the current state of agent configuration files. Two competing standards, one major tool that doesn’t support the emerging one, and no clean resolution in sight.

Here’s what’s actually going on, and what to do about it.

The Two Standards

AGENTS.md was released by OpenAI in August 2025 as a cross-tool standard - a markdown file that lives in your project root and gives AI agents project-specific instructions. The framing was deliberately ecosystem-agnostic: any agent, any tool, one file.

It got real institutional backing fast. The Linux Foundation’s Agentic AI Foundation (AAIF) accepted AGENTS.md alongside MCP and Goose as an inaugural project in December 2025. Over 60,000 open source projects have adopted it. When something gets Linux Foundation backing this quickly, it’s not going away.

CLAUDE.md is Anthropic’s version of the same concept. It’s been part of Claude Code since the beginning. It’s what Claude Code actually reads, and it works well - but it’s Claude-specific.

The problem is that these two files serve the same purpose but have different designs and different tooling support.

How They’re Actually Different

AGENTS.md has a defined spec. There are named sections that tools can parse programmatically:

• agent_instructions - behavioral rules for the agent
• tools - what tools are available and how to use them
• constraints - explicit hard limits on what the agent can do

This structure matters because it lets tools extract and apply specific sections rather than processing the whole document as prose.

CLAUDE.md is freeform. Anthropic gives you guidelines on what to include, but there’s no enforced schema. This is actually fine for Claude Code because Claude reads and interprets the whole file as natural language. The lack of structure is a feature in that context - you can write exactly what you mean without conforming to a schema.

The tradeoff: CLAUDE.md is more expressive and easier to write. AGENTS.md is more interoperable and machine-parseable.

Why Claude Code Doesn’t Read AGENTS.md

GitHub issue #6235, requesting AGENTS.md support in Claude Code, has accumulated thousands of upvotes. Anthropic confirmed in May 2026 that AGENTS.md support is “not planned for now.”

The reasoning hasn’t been stated publicly, but the logic isn’t hard to reconstruct. Claude Code already has a working configuration file. CLAUDE.md is freeform, which suits Claude’s natural language understanding. Supporting AGENTS.md would require either parsing the structured spec (adding complexity) or treating it as prose (defeating the spec’s purpose). There’s also no obvious incentive for Anthropic to make Claude Code more interchangeable with OpenAI’s tooling.

This isn’t going to change on a short timeline. Plan around it.

The Duplicate Work Problem

A JetBrains 2025 survey found that 61% of teams using Claude Code alongside other tools report duplicate configuration work, averaging 5.3 hours/month lost maintaining both files. That’s not a trivial number - it compounds across a team and across projects.

The frustrating part is that the content is often nearly identical. Your constraints, your coding conventions, your project structure notes - all of it lives in two files that you have to keep in sync manually.

There are two practical workarounds.

Workaround 1: Symlink (Unix/Mac Only)

ln -s AGENTS.md CLAUDE.md

This makes CLAUDE.md a symlink pointing to AGENTS.md. Claude Code reads CLAUDE.md and gets the AGENTS.md content. Other tools read AGENTS.md directly. One source of truth.

The catches: this breaks on Windows (symlinks work differently and often require elevated permissions). It also means Claude Code gets the full structured AGENTS.md including section headers like ## agent_instructions, which Claude will interpret as prose - that’s fine, but it’s slightly noisy. And if AGENTS.md uses sections that are genuinely incompatible with how you want Claude to behave, you’re stuck.

For a Unix-only team where you want full convergence, this is the cleanest solution.

Workaround 2: CLAUDE.md Import

Keep AGENTS.md as your primary file with the full spec. Write a minimal CLAUDE.md that imports it:

# CLAUDE.md

See @AGENTS.md for base rules.

## Claude-specific overrides

[anything that's Claude Code-specific goes here]

The @AGENTS.md syntax is Claude Code’s native file import. Claude will read AGENTS.md as part of processing CLAUDE.md. You maintain one canonical file for behavioral rules and use CLAUDE.md only for Claude-specific additions or overrides.

This is the approach I use. It gives you the cleanest separation: AGENTS.md is your project’s authoritative configuration, CLAUDE.md is a thin wrapper that handles Claude-specific nuances without duplicating anything.

When to Maintain Both Properly

If your team uses multiple AI tools and the configuration genuinely needs to differ between them, you have to maintain both files. Some real cases where they diverge:

• Claude Code can use MCP tools that other agents can’t, so the tools section of AGENTS.md may not apply to Claude the same way
• Behavioral constraints written for stateless API-based agents may need different phrasing for Claude Code’s session-based context
• AGENTS.md constraints sections sometimes use syntax that’s meant for programmatic enforcement, not prose interpretation

In these cases, the import approach still helps - CLAUDE.md imports AGENTS.md for the shared rules, then adds Claude-specific overrides inline.

When to Just Use CLAUDE.md

If Claude Code is your only AI coding tool, AGENTS.md is overhead. Don’t adopt a standard you don’t need. Write a good CLAUDE.md, keep it current, and ignore AGENTS.md until either:

1. You add another agent tool to your stack
2. Claude Code adds native AGENTS.md support (possible but not imminent)
3. Your open source project starts getting contributors who use other tools and expect AGENTS.md to be present

The 60,000 open source projects that have adopted AGENTS.md are a real signal. For projects with external contributors, having AGENTS.md is becoming a reasonable expectation - similar to how a CONTRIBUTING.md is expected. For private codebases with a homogeneous tooling stack, it’s optional.

What to Actually Do Today

If you’re running Claude Code only: write a good CLAUDE.md. Include your tech stack, conventions that deviate from framework defaults, which files are off-limits, and explicit negative examples of things Claude tends to do wrong in your codebase. Don’t worry about AGENTS.md yet.

If you’re running a mixed tooling stack: write AGENTS.md as your primary file, then create a CLAUDE.md that imports it with @AGENTS.md and adds any Claude-specific overrides. Commit both files. Done.

If you’re maintaining an open source project: add AGENTS.md. Your Claude Code sessions will use the symlink or import approach. Contributors using other tools will have the configuration they expect. The 5 minutes it takes to set up is worth it.

The fragmentation here is real and annoying. It’s also solvable at the project level with two files and a one-line import. Until Claude Code ships AGENTS.md support, this is the practical path forward.