CLAUDE.MD VS AGENTS.MD

CLAUDE.md is Claude Code's own file; AGENTS.md is the open format most other agents read. If your team uses more than one agent, the answer is both: AGENTS.md as the source, CLAUDE.md as a one-line import.

Zero retention: everything you type stays in this browser. Verify it yourself in DevTools.
Guide

What Is the Difference Between CLAUDE.md and AGENTS.md?

Both are plain Markdown instruction files at the repository root. The difference is who reads them. Last verified 2026-11-13 against the vendor documentation.

CLAUDE.mdAGENTS.md
Primary readerClaude CodeCodex, Cursor, Windsurf, Jules, Zed, Cline and others
Also read byCopilot cloud agent, code review and CLI; ZedCopilot cloud agent, code review, CLI and VS Code chat; Claude Code when no CLAUDE.md exists
ImportsYes, @path, up to 4 hopsNo import syntax in the format
Private variantCLAUDE.local.mdAGENTS.local.md (Windsurf), AGENTS.override.md (Codex)
GovernanceAnthropic product featureOpen format, stewarded by the Agentic AI Foundation

Does Claude Code Read AGENTS.md?

Since v2.1.277, Claude Code can read AGENTS.md, but by default only when there is no CLAUDE.md or CLAUDE.local.md in the working directory or above it. As soon as you add a CLAUDE.md, AGENTS.md is skipped unless you change the Project instructions setting to claude-md-and-agents-md. That default is why a CLAUDE.md that imports AGENTS.md is the most predictable setup.

When Should You Use Only CLAUDE.md?

  • Everyone on the project uses Claude Code and nothing else.
  • You rely on Claude-specific features such as @imports of several files.
  • You have no plans to try another agent.

Even then, naming the shared file AGENTS.md costs nothing and keeps the door open.

When Should AGENTS.md Be the Source?

  • Your team uses two or more agents, for example Claude Code and Cursor, or Codex and Copilot.
  • You want contributors to bring their own agent.
  • You want one file to review in pull requests instead of several copies.

This is the setup 2prompt's generator produces: a full AGENTS.md and thin wrappers that point to it.

How Do You Use Both Without Duplication?

Keep the content in AGENTS.md and make CLAUDE.md a pointer:

# CLAUDE.md

@AGENTS.md

## Claude Code

- The shared project instructions are imported from AGENTS.md on the line above. Edit AGENTS.md, not this file, so every agent stays in sync.
- Put Claude-only preferences below this line. Personal, uncommitted notes belong in CLAUDE.local.md.

Do not also switch Claude Code to claude-md-and-agents-md, or AGENTS.md loads twice. A symlink from CLAUDE.md to AGENTS.md is the other option the Claude Code docs mention, though imports are more portable on Windows.

What Do Teams Get Wrong When Mixing Both Files?

The most common failure is quiet drift. Someone fixes the test command in CLAUDE.md, nobody updates AGENTS.md, and a teammate using Codex keeps running the old command. A second failure is surprise: a project that worked with only AGENTS.md stops sharing it with Claude Code the day someone adds a CLAUDE.md for a personal note.

  • Keep shared content in exactly one file.
  • Put personal notes in CLAUDE.local.md, not a new CLAUDE.md.
  • Review instruction-file changes in pull requests like code.
  • Re-run the linter after every edit to catch contradictions early.

Both problems disappear once AGENTS.md is the only file with shared content and CLAUDE.md is a one-line import.

A quick audit helps: search the repository for every instruction file, list what each contains, and check that only AGENTS.md carries shared rules.

How Do You Migrate From CLAUDE.md to AGENTS.md?

  1. Copy CLAUDE.md to AGENTS.md, or paste it into the CLAUDE.md to AGENTS.md converter.
  2. Remove anything that only makes sense for Claude Code from AGENTS.md and keep it in CLAUDE.md.
  3. Replace the shared content in CLAUDE.md with the @AGENTS.md import.
  4. Move personal preferences into CLAUDE.local.md and add it to .gitignore.
  5. Run the linter on AGENTS.md and fix the findings.

Details on each file: CLAUDE.md format and AGENTS.md format.

Frequently Asked Questions

Should I rename CLAUDE.md to AGENTS.md?

Not quite. Move the shared content to AGENTS.md, then keep a short CLAUDE.md containing @AGENTS.md. With only AGENTS.md, Claude Code reads it, but adding any CLAUDE.md later silently stops that by default.

Will Claude Code load the instructions twice?

Only if you both import AGENTS.md from CLAUDE.md and set the Project instructions option to load CLAUDE.md and AGENTS.md together. Pick one of the two approaches.

Which file does GitHub Copilot read?

Copilot cloud agent, code review and CLI read both AGENTS.md and CLAUDE.md. VS Code chat reads AGENTS.md. Copilot Chat on GitHub.com reads neither and uses copilot-instructions.md.

Is AGENTS.md better than CLAUDE.md?

It is not better written, just more widely read. CLAUDE.md has useful features like imports and a local variant. AGENTS.md reaches more agents, which is why it makes a good single source with CLAUDE.md importing it.

Was this helpful?