AGENTS.md vs CLAUDE.md: which instruction file should you write in 2026?

The quick decision

Write AGENTS.md at the repo root as the cross-tool source of truth for any project where more than one AI coding agent will touch the code. Keep a thin CLAUDE.md whose first line is the import @AGENTS.md, then add only the Claude Code-specific instructions below that import. The two files look identical on disk, so the layering rules are what stop them from drifting apart as the project evolves.

A solo Claude Code project that will never run another agent can ship a CLAUDE.md alone and stop thinking about it. A multi-agent team that has standardized on Cursor, Codex, Copilot, Windsurf, or Amp should ship AGENTS.md as the canonical file and use a thin CLAUDE.md only if some contributors run Claude Code.

What each file actually does

AGENTS.md is a plain-Markdown file at the repo root with no required schema. The agents.md homepage explicitly says there is no prescribed format, so anything you write inside is what the agent reads. The closest AGENTS.md to the file the agent is editing wins, which lets monorepos ship per-package rules without bloating a single root file. AGENTS.md is read natively by Codex CLI, Cursor, GitHub Copilot, Windsurf, Amp, Devin, opencode, and others, which is why it is the closest thing to a vendor-neutral standard for project context.

CLAUDE.md is Anthropic native context file for Claude Code. Claude Code reads a root CLAUDE.md, a personal CLAUDE.local.md that stays out of version control, a global ~/.claude/CLAUDE.md, and a hierarchy of .claude/CLAUDE.md files in subdirectories. The richer feature set is what makes CLAUDE.md worth keeping even on multi-agent repos: it supports @path imports so a single line can pull in AGENTS.md, plus path-scoped rules and managed policy paths that AGENTS.md does not offer on its own.

• AGENTS.md: cross-tool standard, no schema, closest-in-tree wins, read by Codex, Cursor, Copilot, Windsurf, Amp, Devin, opencode, and others.
• CLAUDE.md: Claude Code only, supports @path imports, path-scoped rules, user-level overrides, local files, and managed policy.
• Bridge: a single line @AGENTS.md at the top of CLAUDE.md pulls the cross-tool content into Claude Code at session start.

Why the two files drift if you let them

The first drift shape is duplicating cross-tool rules across both files. Someone keeps an AGENTS.md-style copy inside CLAUDE.md so the project still works if AGENTS.md ever gets renamed, then edits one without the other and ends up with two parallel conventions that disagree. The fix is the @AGENTS.md import: one source of truth, one overlay.

The second drift shape is putting cross-agent rules only in CLAUDE.md. Build commands, test commands, code style, and PR conventions sit in CLAUDE.md, then a contributor opens Cursor and the agent skips every one of them because Cursor does not look at CLAUDE.md. The team notices the day two agents disagree on output style. The fix is to lift cross-agent rules into AGENTS.md and import them from CLAUDE.md.

The third drift shape is the silent symlink failure on Windows checkouts. ln -s AGENTS.md CLAUDE.md works on macOS and Linux. On Windows it can degrade to a plain text file that contains the target path string rather than the imported content, with no warning at write time. The @AGENTS.md import in CLAUDE.md survives every filesystem because it is plain text inside a plain file.

• Duplicate cross-tool rules: the two files agree for one day, then drift.
• Put cross-agent rules only in CLAUDE.md: every non-Claude agent silently ignores them.
• Symlink CLAUDE.md to AGENTS.md on Windows: silent failure mode that produces a nine-byte file.

The two-line layering rule

If Cursor or Codex would need the rule to do its job, it belongs in AGENTS.md. If the rule changes Claude Code behavior in a way the other agents would ignore, it belongs in CLAUDE.md. Apply this test before adding any new line, and the project keeps the two files short enough to actually read.

Examples that belong in AGENTS.md: build commands, test commands, lint invocations, code style, naming conventions, import order, the directories an agent should not touch, the architectural boundaries that apply to every tool, and any gotcha a newcomer always hits regardless of which agent they are running.

Examples that belong in CLAUDE.md: Claude Code plan-mode behavior, sub-agent delegation rules, slash-command overrides, the wiring for Claude Code hooks and skills, and any rule that names a Claude Code feature. If a contributor running Cursor, Codex, or Windsurf reads the rule and has no way to act on it, the rule belongs in CLAUDE.md.

When native AGENTS.md support finally lands in Claude Code

Anthropic filed a feature request for native AGENTS.md support on 21 August 2025 (anthropics/claude-code#6235) and the issue was still open on 7 August 2026. The community workaround is the @AGENTS.md import, which Anthropic documents and which works today. When native support lands, the import line is still useful as a one-line pointer that tells a reader which file carries the canonical instructions.

Until then, every repo that wants both Claude Code and a multi-agent portable context file should keep the import. CLAUDE.md becomes a 20 to 60 line overlay file rather than a 200 line duplicate. The HumanLayer reference target is under 60 lines for the root file, which is the practical ceiling for a thin overlay.

What this article does not publish

No exact adoption count is published here. AGENTS.md is widely cited as adopted by tens of thousands of repositories and the agents.md ecosystem lists around 25 supporting agents, but the underlying count comes from external measurement services that update independently and should be checked at the source.

No benchmark on Cursor or Codex reading speed. Both vendors publish their own performance guidance for instruction-file size; the durable answer is to keep each file under roughly 200 lines and put the essentials near the top so context compaction does not drop them in a long session.

A useful next action

Audit the current project for an existing CLAUDE.md or AGENTS.md. Decide whether the team is single-agent or multi-agent, then write the canonical file for the multi-agent case. Add a thin CLAUDE.md with @AGENTS.md as the first line if any contributor runs Claude Code, and put only the Claude Code-specific rules below the import.

Test by running the same small task across two agents and comparing the outputs. If both follow the same conventions without intervention, the layering is correct. If one ignores a rule, the rule lived in the wrong file.