AGENTS.md vs CLAUDE.md: one instructions file for every coding agent

AGENTS.md and CLAUDE.md do the same job: a Markdown file in your repository that a coding agent reads before it starts, with your build commands, conventions and rules. The difference is who reads them. AGENTS.md is an open format that Codex, Cursor, GitHub Copilot and Claude Code read without any setup, and Gemini CLI and Aider read after one line of config. CLAUDE.md is Claude Code's own file. If more than one agent works in your repository, put the shared instructions in AGENTS.md and keep CLAUDE.md, if you need one at all, to the lines only Claude should see.

Writing the file well is the same for both, and our guide to CLAUDE.md and project instructions covers it: what to put in, what to leave out, and why under 200 lines. This article is about the other problem, a repository that 3 different agents open in the same week.

Who reads which file

Every agent below reads its own file. What matters is whether it also reads AGENTS.md, and what it does when it finds several.

Copilot also accepts a single CLAUDE.md or GEMINI.md at the root instead of AGENTS.md, so a repository that only has a CLAUDE.md still gives Copilot its rules.

The one row to read twice is Claude Code's. It does not read AGENTS.md as well as CLAUDE.md. It reads AGENTS.md instead of CLAUDE.md, and only when it finds none of CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the folder you start in or any folder above it. Your personal ~/.claude/CLAUDE.md and .claude/rules/ files do not count, so they load alongside AGENTS.md.

The setup that keeps one source of truth

Put everything every agent needs in AGENTS.md at the root. Then decide whether Claude needs anything the others do not.

If it does not, stop there. Claude Code reads AGENTS.md on its own, and in an interactive session it says so at the start: no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md.

If it does, add a CLAUDE.md that imports the shared file first and adds the Claude-only lines under it:

@AGENTS.md

## Claude Code only
- Use plan mode for any change under `src/billing/`.
- Run `/doctor prompt-audit` after editing this file or AGENTS.md.

The import puts the whole of AGENTS.md into Claude's context with CLAUDE.md, and Claude Code never reads it twice, whichever setting you use. This is also the version that works in sessions where Claude cannot read AGENTS.md directly: a Claude Code older than 2.1.277, or a setup where someone disabled the built-in plugin that reads it.

A symlink (ln -s AGENTS.md CLAUDE.md) works too, and Claude reads the content once. It makes the 2 files identical, though, so there is no room for the Claude-only lines. The import has no such limit.

The same idea for Gemini CLI is a setting rather than a file. In .gemini/settings.json:

{
  "context": {
    "fileName": ["AGENTS.md", "GEMINI.md"]
  }
}

What goes in the shared file

Instructions any agent can act on. Commands, conventions and the mistakes to avoid are the same whichever model reads them:

# Orders service

## Commands
- Install: `pnpm install`
- One test file: `pnpm vitest run src/orders/refund.test.ts`
- Before finishing: `pnpm check` (lint and types) must pass.

## Conventions
- Money is integer cents. Format it with `formatCents()` only.
- Files in `src/gen/` are generated by `pnpm codegen`. Never edit them.

## Code Review Rules
- Flag any refund path that skips `assertRefundable()`.

The last heading is not decoration: Codex's GitHub code review reads a ## Code Review Rules section from the AGENTS.md nearest the changed code. Other agents read it as one more rule, which does no harm.

What stays out of AGENTS.md is anything written for one agent's features: Claude's plan mode, a Cursor rule's globs, a Codex sandbox setting. Another agent cannot act on those lines, and they spend its Context WindowContext WindowEverything a model can see at once while it writes an answer, counted in tokens. When the window is full, something has to be left out. on every task.

The traps when both files exist

A local file switches AGENTS.md off for you. CLAUDE.local.md counts as a CLAUDE.md. Add one to a project that relies on AGENTS.md and Claude stops reading AGENTS.md, for you only, with no error. Either import AGENTS.md from it, or set Project instructions to claude-md-and-agents-md in /config.

The files are read in different orders. Codex reads the files from the repository root down to the folder you start in, once at launch, and a file nearer your folder comes later, so it overrides. Claude Code loads the folders above you at launch and a subfolder's file only when it opens a file there. Copilot gives the nearest AGENTS.md precedence, and Cursor combines a nested file with its parents, the more specific one taking precedence. A rule placed only in services/payments/AGENTS.md reaches Codex only if you start Codex in that folder.

Override files are a Codex feature. AGENTS.override.md replaces AGENTS.md in its folder for Codex, and Claude Code ignores it, as it ignores AGENTS.local.md and anything under .agents/. A team that keeps payments rules in an override file has rules Claude never sees.

Codex stops at 32 KiB. Codex adds files until the combined size reaches 32 KiB by default (project_doc_max_bytes) and drops the rest. A long root file can push a nested file's rules out. Claude Code's docs give the same advice for a different reason, a long file is followed less reliably: keep it short.

The two files drift. Two full copies of the same rules, edited by different people, end up contradicting each other, and Claude, for one, may then pick either line arbitrarily. One shared file and one thin import avoid that.

Instructions, skills and tools: all open formats now

AGENTS.md handles the facts an agent needs in every session. It is not the place for a 20-step release procedure or for access to your database, and since 22 October 2026 all 3 of those layers have the same neutral owner.

OpenAI released AGENTS.md in August 2025 and gave it to the Agentic AI Foundation, a Linux Foundation body, when the foundation launched in December 2025. Anthropic gave the Model Context ProtocolModel Context ProtocolAn open standard for connecting AI applications to tools and data. A system offered once as an MCP server works in any application that speaks MCP. to the same foundation at the same time. On 22 October 2026 Anthropic gave it Agent Skills, the SKILL.md format, with its name, GitHub organization and the agentskills.io domain; engineers from Anthropic, Google, OpenAI and other companies will maintain it as individuals. The foundation now hosts 10 projects.

For a repository, that means 3 files cover what most agents need, none of them owned by one agent maker:

The release procedure moves out of AGENTS.md into a skill, which costs almost nothing until it is used, since only its name and description load at the start. Our guide on writing a SKILL.md for Claude Code covers the format, and MCP vs API, CLI or skills compares what each costs in tokens.

Skills have the same folder problem as instructions. Codex reads repository skills from .agents/skills/, and Claude Code reads them from .claude/skills/. Both follow a symlinked skill folder, so keep the skill once and link it:

mkdir -p .claude/skills
ln -s ../../.agents/skills/release .claude/skills/release

Use only the 6 frontmatter fields of the Agent Skills specification (name, description, license, compatibility, metadata, allowed-tools) in a skill you share. Claude Code accepts more, such as argument-hint, but other tools may not.

Check what each agent loaded

Nothing warns you when an agent skips a file, so ask each one:

• Claude Code: /context lists the memory files it loaded, and /doctor prompt-audit (v2.1.283 or later) checks your CLAUDE.md, CLAUDE.local.md and AGENTS.md files for contradictions and references to files that do not exist.
• Codex: codex --ask-for-approval never "Summarize the current instructions." from the root, and again with --cd into a subfolder, shows which files it joined.
• Gemini CLI: /memory show prints the full text it loaded.
• Cursor and Copilot: ask the agent in chat which instruction files it is using, and check the answer names your AGENTS.md.

If you choose between Claude Code, Cursor and Codex rather than run all 3, our comparison of the three covers the rest of the differences.