Comparison

CLAUDE.md vs AGENTS.md: which project context file should you use?

CLAUDE.md vs AGENTS.md comes down to one rule: put your real instructions in AGENTS.md, the cross-tool context file that many agent tools already read, and keep CLAUDE.md as a thin Claude Code-specific file that points at it. AGENTS.md travels across whatever agent you run; CLAUDE.md is the richer native format for Claude Code specifically. If you only ever use one agent, either file works on its own — but the moment you switch or run more than one, the cross-tool file is what saves you from maintaining two copies of the same conventions.

Both files do the same job: they give an AI coding agent the project context it needs — build commands, test commands, style rules, "don't touch this directory" — so you don't re-explain your repo every session. The difference is who reads them and how widely they apply. This guide covers what each file is, what belongs in it, how to nest them per directory, and why keeping them short actually matters.

The short answer

Make AGENTS.md your single source of truth. It's a plain-Markdown file at your repo root that's read by many agent tools, so the conventions you write once apply no matter which CLI you reach for. Then keep CLAUDE.md minimal — use it only for things genuinely specific to Claude Code, and have it import AGENTS.md so the shared rules flow through. One canonical file, no drift, and any agent you run picks up the same context.

At a glance:

What AGENTS.md is

AGENTS.md is a cross-tool convention for telling AI coding agents how to work in your repo. Where a README.md explains the project to humans, AGENTS.md explains it to agents: the commands to build and test, the lint rules, the architectural constraints, the things you'd tell a new contributor on day one. It's deliberately minimal — plain Markdown, no required schema, no front matter, no special syntax.

The reason to lead with it is reach. AGENTS.md is read by many agent tools — Codex CLI, Cursor, GitHub Copilot, Aider, and others have adopted it — and Claude Code reads it too. That makes it the closest thing to a vendor-neutral standard for project context. Write your conventions there once and they apply across the tools your team actually uses, which is exactly the situation if anyone runs more than one agent. (For how two of those agents differ in practice, see Claude Code vs Codex CLI and OpenCode vs Claude Code.)

What CLAUDE.md is (and how it relates)

CLAUDE.md is Claude Code's native context file. It does the same core job — hand the agent your build commands, conventions, and guardrails — but it's richer and Claude-specific. Claude Code reads it in layers: a project file checked into the repo, a personal file for your machine, and a global file in your home directory, all composing into the context the agent loads.

The important part for this comparison: CLAUDE.md can reference AGENTS.md. Claude Code supports @path imports, so a single line keeps the two in sync:

# CLAUDE.md
See @AGENTS.md for project conventions, build and test commands.

# Claude-specific notes below
- Prefer plan mode for multi-file refactors.

That @AGENTS.md pulls the shared file into context. Imports are recursive up to a depth of five and are ignored inside code blocks, so you can keep the real content in AGENTS.md and let CLAUDE.md be a thin pointer plus a handful of Claude-only instructions. The alternative — two files with duplicated conventions — is the thing that drifts and bites you three weeks later.

What to put in them

The content rule is the same for both files: command-first and specific. Favor things an agent can't infer by reading the code, and skip anything it can. Good candidates:

• Commands: how to install, build, run tests, lint, and type-check — the exact invocations.
• Conventions: formatting, naming, import order, the patterns your codebase actually follows.
• Boundaries: directories not to touch, generated files, anything destructive to avoid.
• Gotchas: the non-obvious setup steps and the mistakes a newcomer (human or agent) always makes.

A useful discipline: only add a rule the second time you have to correct the agent on the same thing. First-time issues are usually one-offs; repeated ones are conventions worth writing down. This pairs well with the rest of the Claude Code config surface — hooks for automated guardrails, subagents for delegated work, and MCP servers for external tools and data.

Path-scoped and nested files

Both conventions support more than one file. You can drop an AGENTS.md (or CLAUDE.md) into a subdirectory, and agents apply the closest one to the file they're working on. So a monorepo can carry a root file with the shared rules plus per-package files for the specifics — the backend's test command in services/api/AGENTS.md, the web app's in apps/web/AGENTS.md.

The win is relevance and cost: the agent loads the context that matches what it's editing, instead of one giant root file that explains the whole repo on every task. Nest by directory, keep each file scoped to its corner, and let the root hold only what's truly global.

Keep it short (token cost)

Whichever file you use, keep it lean — a common guideline is under roughly 200 lines. Every line is loaded into the agent's context, so each one should earn its place. A bloated context file isn't just wasteful; it dilutes signal, and the agent is likelier to miss the rule that matters among the ones that don't.

There's a subtler reason to be brief: context compaction. In a long session, agents compress earlier context to stay within the window, which means lines near the top of a long file are the ones most at risk of being summarized away. Put the essentials — the must-run commands, the hard "never do this" rules — high and stated plainly, so they survive. If a file is growing past comfortable, that's the signal to split rules into path-scoped files rather than pile them into one.

Frequently asked questions

Where Backgrind fits

If you'd rather not start from a blank file, our free CLAUDE.md generator assembles a clean context file — commands, conventions, guardrails, and the AGENTS.md-plus-pointer pattern — from a short form, entirely in your browser.

The cross-tool case for AGENTS.md is also the case for not locking your context to one vendor — and that's the same stance Backgrind takes about the agent itself. Backgrind is a bring-your-own-CLI overlay: it wraps whatever agent you already run — Claude Code, Codex, OpenCode — in an always-on-top window with ambient notifications, so you're never picking a tool because of where it lives. Your AGENTS.md travels with you across all of them; CLAUDE.md just points at it. Run them side by side, switch freely, and let one short context file drive the lot. See it in the live demo. Newer to the agents themselves? Start with how to install Claude Code or what is OpenCode.