AGENTS.md vs CLAUDE.md: Which File Should You Use?

If you're weighing AGENTS.md vs CLAUDE.md, here's the short answer: use CLAUDE.md if your team works exclusively in Claude Code, and use AGENTS.md as your source of truth if people run different AI coding tools against the same repo. CLAUDE.md unlocks Claude Code's deepest features — file imports, the global-plus-project hierarchy, per-directory context — while AGENTS.md is the cross-vendor convention read by Codex CLI, Cursor, Zed, and a growing list of other agents.

The better news: this isn't really an either/or decision. A one-line import or a symlink lets a single file serve both audiences, so the practical question is which file owns the content and which one points at it. This post walks through what each file does, the state of AGENTS.md Claude Code support, the interop patterns that work today, and how to migrate in either direction.

AGENTS.md vs CLAUDE.md: the quick answer

Pick based on who — and what — reads your repo:

• Everyone uses Claude Code. Write a CLAUDE.md and stop there. You get @file imports, a personal ~/.claude/CLAUDE.md layered under the project file, and nested per-directory files for monorepos. No other format gives you that combination in Claude Code.
• Your team mixes tools. Make AGENTS.md the canonical file and add a one-line CLAUDE.md that imports it (pattern below). Codex CLI, Cursor, and friends read AGENTS.md natively; Claude Code users lose nothing.
• You maintain an open-source project. Use AGENTS.md. You can't control which agent a contributor runs, and AGENTS.md is the closest thing the ecosystem has to a neutral standard.
• You already have both and they've drifted. Pick one as canonical — usually AGENTS.md — merge the content, and turn the other into a pointer. Two context files giving agents conflicting instructions is worse than having neither.

Whatever you choose, the content matters more than the filename. Both files are plain Markdown, and the advice in our CLAUDE.md guide — explicit tech stack, build commands, conventions, hard boundaries — applies to either one verbatim.

What each file is and which tools read it

CLAUDE.md is Claude Code's native context file. When Claude Code starts a session it loads ~/.claude/CLAUDE.md (your personal preferences), the project-root CLAUDE.md, and any CLAUDE.md files in directories it works in, merging them with project-level instructions taking precedence. It also supports an import syntax — @path/to/file — that pulls other files into context, which is the feature that makes the interop patterns below so clean.

AGENTS.md started as a convention for OpenAI's Codex agents and grew into a cross-vendor standard: one predictable filename any coding agent can look for, instead of every vendor inventing its own. Codex CLI reads it at the repo root and in nested directories (closest file wins), Cursor picks it up alongside its own rules system, and tools like Zed and GitHub Copilot's coding agent have joined the list. If you want the full adoption picture and authoring conventions, see the complete AGENTS.md guide.

Here's how the two compare head to head:

The structural similarity is the point: both are freeform Markdown with no required frontmatter, so content moves between them with a rename. The differences are all about who reads the file and what extra machinery surrounds it.

Does Claude Code read AGENTS.md?

This is the question that decides most setups, so let's be precise. Claude Code was built around CLAUDE.md, and that's the filename its context loading looks for out of the box. If your repo contains only an AGENTS.md, you should not count on every Claude Code installation picking it up automatically the way Codex CLI or Cursor would.

AGENTS.md Claude Code support has been one of the most requested interop features precisely because the rest of the ecosystem converged on the other filename. But in practice this gap costs you almost nothing, because Claude Code's import syntax gives you an explicit, version-controlled bridge that works on every version:

# CLAUDE.md
@AGENTS.md

That two-line CLAUDE.md tells Claude Code to load AGENTS.md into context, byte for byte. It's boring, it's greppable, and it never surprises anyone during code review. The reverse direction — a tool that reads AGENTS.md but not CLAUDE.md — has no import mechanism to lean on, which is exactly why multi-tool repos should make AGENTS.md the file that holds the real content.

Symlinks and imports: making both work at once

There are two established patterns for serving both filenames from one source of truth. Both assume AGENTS.md is canonical.

Pattern 1: the import shim. Keep your instructions in AGENTS.md and check in a minimal CLAUDE.md that imports it:

# CLAUDE.md
@AGENTS.md

<!-- Claude Code-specific additions go below -->
- Use the /commit workflow defined in .claude/commands/

The killer feature here is the comment line: you can append Claude-specific instructions after the import without polluting the shared file. Codex CLI users never see your Claude Code slash-command notes; Claude Code users get everything.

Pattern 2: the symlink.

ln -s AGENTS.md CLAUDE.md
git add CLAUDE.md
git commit -m "Symlink CLAUDE.md to AGENTS.md"

Git stores symlinks natively, so teammates get the link on checkout. The two files can never drift because there's only one file. The trade-offs: Windows checkouts need core.symlinks enabled (and Developer Mode or admin rights), some CI containers and zip-based downloads flatten symlinks into plain text files, and you lose the ability to add tool-specific extras.

Which to pick? The import shim is the safer default — it behaves identically on every platform and leaves room for per-tool additions. Use the symlink when you want drift to be structurally impossible and everyone develops on macOS or Linux. In a monorepo, both patterns nest: put an AGENTS.md in each package directory and shim or link a CLAUDE.md next to it, and both Claude Code and Codex CLI will apply the closest file to wherever they're working.

AGENTS.md vs .cursorrules and the wider format landscape

The AGENTS.md vs cursorrules question comes up constantly from Cursor users, and the answer has two layers. The legacy single-file .cursorrules is deprecated — Cursor's current system is .cursor/rules/*.mdc files with frontmatter controlling glob-scoped and always-on attachment. Cursor also reads a root AGENTS.md as plain, always-applied instructions. So the real comparison is: AGENTS.md gives you portability across tools, while .mdc rules give you Cursor-only superpowers like attaching a rule solely to *.tsx files. Many teams use both — AGENTS.md for shared baseline conventions, .cursor/rules/ for scoped, Cursor-specific behavior. Our Cursor rules guide covers the .mdc format in depth.

Zoom out and the landscape of AI agent context files gets crowded fast:

• CLAUDE.md — Claude Code
• AGENTS.md — Codex CLI, Cursor, Zed, Copilot's coding agent, and others
• .cursor/rules/*.mdc — Cursor's scoped rules
• GEMINI.md — Gemini CLI's default (its context filename is configurable, so it can be pointed at AGENTS.md)
• .windsurf/rules/ — Windsurf
• .clinerules — Cline
• .github/copilot-instructions.md — GitHub Copilot
• CONVENTIONS.md — Aider's conventional home for style rules

Maintaining that many near-identical files by hand is the actual problem — the filename debate is a symptom. We've written about the fragmentation problem across tools before, and it's why localskills.sh exists: you publish an instruction set once as a versioned skill, and the CLI writes each tool-native format on install — .cursor/rules (.mdc) for Cursor, .claude/skills/ for Claude Code, .windsurf/rules/ for Windsurf, and so on — with one command targeting several tools at once:

localskills install acme/typescript-conventions --target cursor claude windsurf

AGENTS.md vs CLAUDE.md: migration paths in both directions

Both migrations are cheap because the formats are both plain Markdown. Here's each direction, step by step.

Moving from CLAUDE.md to AGENTS.md

Do this when new teammates or tools show up that read AGENTS.md.

1. Rename the file:

   git mv CLAUDE.md AGENTS.md

2. Inline anything Claude-specific. @file imports are Claude Code syntax — other tools will read them as literal text. Either paste the imported content into AGENTS.md or replace the import with a plain Markdown link and accept that only humans will follow it.

3. Recreate CLAUDE.md as a shim using the import pattern above, and move any Claude Code-only instructions (slash commands, hooks, subagent notes) below the import line.

4. Verify in each tool. Start a session in Claude Code and in your other agents and ask each one what conventions it sees. Thirty seconds of checking beats a week of subtly ignored rules.

Moving from AGENTS.md to CLAUDE.md

Do this when your team has consolidated on Claude Code and you want its native features.

1. Copy the content across:

   cp AGENTS.md CLAUDE.md

2. Restructure for Claude Code's strengths. Split a long file into focused pieces — keep the core conventions in CLAUDE.md and move task-specific material into .claude/skills/, importing what should always load with @ references.

3. Keep AGENTS.md as a courtesy. Leave it in place (or symlink it to CLAUDE.md) so occasional Codex CLI or Cursor users — and open-source contributors — still get context instead of silence.

When one repo isn't the whole story

Migration scripts fix one repository. If you're maintaining the same conventions across ten repos and four tools, filename shims stop scaling — that's the point where teams move shared instructions into a registry with versioning, rollback, and access control, and generate the per-tool files instead of hand-editing them. That's exactly the workflow the localskills docs cover.

FAQ

Can AGENTS.md and CLAUDE.md coexist in one repo?

Yes, and in multi-tool repos they should — as one content file plus one pointer. Keep the real instructions in AGENTS.md, make CLAUDE.md a two-line import shim (or symlink), and you'll never merge conflicting edits to parallel files.

Which file should an open-source project choose?

AGENTS.md. You can't dictate contributors' tooling, and AGENTS.md has the broadest native support. Add the CLAUDE.md shim so Claude Code contributors are covered too.

Do the files use different syntax?

No. Both are plain Markdown with no required structure. The only syntax that doesn't transfer is Claude Code's @file import, which other tools treat as ordinary text — flatten imports before relying on AGENTS.md alone.

Is .cursorrules the same kind of file?

Historically yes — a root-level instructions file — but it's the legacy format. Cursor now favors .cursor/rules/*.mdc for scoped rules and reads AGENTS.md for baseline instructions, so new projects shouldn't create a .cursorrules at all.

---

One instruction set, every tool: publish your conventions once on localskills.sh and install them as CLAUDE.md-style skills, Cursor rules, or Windsurf rules from a single source of truth.

npm install -g @localskills/cli
localskills login
localskills publish