AGENTS.md vs CLAUDE.md: Differences and How to Use Both

AGENTS.md and CLAUDE.md do the same job: a markdown file at the project root that gives an AI coding agent the project context it can't work out from the code. The difference is who reads them. AGENTS.md is the shared format most agents read, and CLAUDE.md is the one Claude Code was built around.

You rarely need two copies. Below: what each file is, which tools read which today, and the import that keeps one source of truth.

AGENTS.md vs CLAUDE.md: what's the difference?

AGENTS.md is a vendor-neutral open standard for project instructions; CLAUDE.md is Claude Code's richer, Claude-only version of the same idea. Both are plain Markdown files with no required fields, so the same file can often serve both. They differ in reach and in features.

What is AGENTS.md?

AGENTS.md is "a README for agents": one predictable place, next to the docs written for human developers, where any coding agent finds the setup commands, code style and testing rules. According to agents.md, it's used by more than 60,000 open-source projects, and its homepage lists over 20 supporting tools, from OpenAI's Codex and Google's Jules to Cursor, Aider, Zed, Warp, Devin and the GitHub Copilot coding agent. OpenAI contributed it to the Linux Foundation's Agentic AI Foundation as a founding project in December 2025, alongside Anthropic's Model Context Protocol (Linux Foundation, 2025).

In a monorepo you put one AGENTS.md file in each package root, and AI coding agents read the nearest one, so the closest file takes precedence. A typical file looks like this:

# AGENTS.md

Invoice service for a B2B billing app: TypeScript, Node 22, pnpm workspaces.

## Setup commands
- Install deps: `pnpm install`
- Start the dev server: `pnpm dev`
- Run tests: `pnpm test`

## Code style
- TypeScript strict mode
- Single quotes, no semicolons
- Follow the TypeScript rules in `tsconfig.base.json`; don't loosen them per package
- Money is stored in integer cents; never use floats for amounts

## Testing instructions
- Run `pnpm test --filter <package_name>` for the package you changed
- Fix any test or type errors until the whole suite is green
- Add or update tests for the code you change

## PR instructions
- Title format: [<package_name>] <Title>
- Run `pnpm lint` and `pnpm test` before committing

Each agent adds its own rules on top, so check its documentation. Codex, for example, also reads a global file from ~/.codex, prefers an AGENTS.override.md where one exists, concatenates files from the repo root down to your working directory, and stops adding them at 32 KiB by default (OpenAI Codex docs).

What is a CLAUDE.md file?

CLAUDE.md is the instruction file Claude Code loads at the start of every session, with more structure than AGENTS.md offers. It comes in four scopes (managed policy, user, project and local), and Claude Code loads all of them rather than picking one. It can pull in other files with @path imports, and .claude/rules/ holds path-scoped rules that load only when Claude works on matching files, so they show up only when relevant. Anthropic's guidance is to keep each file under 200 lines, because longer files cost more context and reduce adherence (Claude Code docs).

The full guide to the file, with a complete example, is in CLAUDE.md: What It Is, Best Practices & Examples.

Does Claude Code read AGENTS.md?

Yes. Since v2.1.277, Claude Code reads AGENTS.md as your project instructions when there's no CLAUDE.md or CLAUDE.local.md in your working directory or above it (Claude Code docs). By default it reads one or the other, never both:

Two failure modes catch people out. Adding a personal CLAUDE.local.md to a repo that relies on AGENTS.md makes Claude Code stop reading AGENTS.md for you. And Claude Code doesn't read AGENTS.override.md (a Codex convention), AGENTS.local.md or anything under .agents/. To load both files every time, open /config and set Project instructions to claude-md-and-agents-md. On older versions, or after you disable the built-in plugin that reads AGENTS.md, Claude Code reads CLAUDE.md only.

How do you keep AGENTS.md and CLAUDE.md in sync?

Write the shared instructions once in the AGENTS.md file and let every other file name point at it. Two copies of the same rules drift apart as soon as someone edits only one, and the agent reading the stale copy has no way to tell. There are three ways to set it up, depending on what Claude Code needs beyond the shared rules.

Option 1: AGENTS.md only

If Claude needs nothing the other agents don't, keep only the existing files: AGENTS.md at the project root and one per package. Claude Code v2.1.277 and later reads them directly.

Option 2: a CLAUDE.md that imports AGENTS.md

This is the setup to pick for most teams. The import loads AGENTS.md first, then your Claude-only lines, and it works on every Claude Code version:

@AGENTS.md

## Claude Code
- Use plan mode for changes under `src/billing/`
- Run `pnpm typecheck` after every series of edits
- Run `pnpm lint` before you report a task as done
- Path-specific rules live in `.claude/rules/`

Claude Code never loads AGENTS.md twice, whichever setting you use.

Option 3: a symlink

If there's nothing Claude-specific, a symlink works too:

ln -s AGENTS.md CLAUDE.md

Check two constraints first. Claude's Edit and Write tools refuse to write through a symlink, so edits go to AGENTS.md instead. And on Windows, Git checks out a committed symlink as a one-line text file unless core.symlinks is enabled, so a Windows teammate's clone ends up with the path where the instructions should be. If anyone on the team uses Windows, use the import. Either way, run /context in your next session and check that the file appears under Memory files.

Other agents have their own switches. Gemini CLI reads GEMINI.md by default, but setting context.fileName to include "AGENTS.md" in settings.json makes it read AGENTS.md too (Gemini CLI docs). GitHub Copilot reads AGENTS.md files anywhere in the repo, nearest first (GitHub Docs).

Should you use AGENTS.md or CLAUDE.md?

Use AGENTS.md as the source of truth whenever more than one coding agent works in the repo, and CLAUDE.md alone only when the whole team uses Claude Code. In practice:

• Mixed team (Codex, Cursor, Copilot, Claude Code): AGENTS.md, plus a CLAUDE.md with @AGENTS.md if Claude needs extra rules.
• Claude Code only: CLAUDE.md, with .claude/rules/ for path-scoped rules and CLAUDE.local.md for your sandbox settings.
• Monorepo: nested AGENTS.md files, one per package root. Claude Code loads subfolder files only when it works there, so they cost nothing until needed.
• Open-source project: AGENTS.md, since you can't know which agent a contributor runs.

Whichever file wins, keep it short, because agent performance depends more on what's in the file than on its name. A 2026 study of coding agents found that context files, whether generated by an LLM or committed by developers, did not generally improve task success and raised inference cost by more than 20% on average; agents followed the instructions well, but repository overviews didn't help (Gloaguen et al., 2026). Generate a draft with /init if you like, then delete everything the agent could read from the code and keep the non-standard practices it couldn't guess.

Common questions about AGENTS.md

AGENTS.md is an ordinary, committed Markdown file with no required fields, so most questions about it have short answers.

Should AGENTS.md be committed?

Yes. The AGENTS.md file describes the project for everyone who works on it, human developers and agents alike, so it belongs in git next to the README. Personal settings go in files you don't commit: CLAUDE.local.md for Claude Code, a global file for Codex.

Is AGENTS.md a standard?

The AGENTS.md file is an open format for AI agents with no required fields, stewarded by the Agentic AI Foundation under the Linux Foundation. Each tool decides how far to follow it.

What if instructions conflict?

For AGENTS.md, the file closest to the edited code wins and an explicit prompt in chat overrides everything. Claude Code loads its CLAUDE.md scopes together instead of letting one override another, so when two lines contradict each other it may follow either. Delete one.

Will the agent run the test commands in AGENTS.md?

Usually, if you list them. A coding agent tries to run the checks you document, such as pnpm test and pnpm lint, and fix any test or type errors before it finishes. To make a check mandatory in Claude Code, use a hook instead of a sentence.

When is a context file the better choice, and what does it miss?

For project rules, a committed context file is the right tool and nothing replaces it: it's versioned, reviewed and travels with the code. Unabyss doesn't replace AGENTS.md or CLAUDE.md, and if your only problem is keeping two agents on the same build commands, the import above is all you need.

What neither file holds is you: your role, the client you're building for, the decision from last week's planning call. That's personal context, not project context. Pasted into ~/.claude/CLAUDE.md, it reaches only Claude Code on one machine and goes stale as soon as your week changes; the habits that slow the drift are in how to keep your CLAUDE.md from going stale. In an August 2026 Unabyss benchmark, a hand-written CLAUDE.md reduced follow-ups but barely moved cost, time or quality, while structured context from Unabyss cut cost by 36% and time by 38% (What Structured AI Context Is Worth).

Keep AGENTS.md for the repo. Connect your apps to Unabyss for the context that should follow you into Claude Code, Codex, Cursor and ChatGPT alike.

Related

• CLAUDE.md: What It Is, Best Practices & Examples
• How to Keep Your CLAUDE.md From Going Stale
• What Is an MD File? How to Open It and Why AI Tools Use It