AGENTS.md vs CLAUDE.md: Which Should Your Team Use?

You added a CLAUDE.md. Your teammate added an AGENTS.md. A third repo has both, plus a .cursorrules nobody remembers writing — and none of them agree on how the project actually builds.

Both files are the right instinct: write your conventions down so the AI stops guessing. But they solve the problem at the wrong altitude. They live per-repo, per-tool, and per-developer — which means at team scale they drift out of sync the moment more than one person edits them. This post is a fair comparison of the two files, and then the reframe: the fix isn't picking a file, it's putting a shared source of truth above both.

What is CLAUDE.md and what is it good at?

CLAUDE.md is a plain-Markdown file that Claude Code reads automatically as memory. Drop it at your repo root (or in ~/.claude/ for user-global rules, or a subdirectory for path-scoped rules) and Claude loads it into context at the start of every session. No config, no flag.

It is genuinely good at what it does. The loading model is hierarchical: a project-level CLAUDE.md, a user-level one in your home directory, and nested files deeper in the tree that apply only when you're working in that subtree. It supports @path/to/file imports, so you can pull in other files instead of pasting their contents. It's the single cleanest way to tell Claude Code "run pnpm test, not npm test," "we use Drizzle, not Prisma," "never touch the generated migration files."

If your team standardises on Claude Code and nothing else, CLAUDE.md is a strong local answer. The catch is in that sentence: Claude Code and nothing else. The file is named after one vendor's tool for a reason — it is Anthropic-specific, and no other agent reads it by default.

What is AGENTS.md and what does it solve?

AGENTS.md is the same idea, minus the vendor lock. It's an open, tool-agnostic standard: a plain-Markdown file at your repo root that any compliant coding agent reads for build steps, test commands, conventions, and gotchas. Think of it as a README written for machines instead of humans — the human README stays prose and marketing; AGENTS.md holds the precise, executable-adjacent instructions an agent needs.

The reason it matters is reach. AGENTS.md is read natively by a large and growing set of tools — OpenAI Codex, Cursor, GitHub Copilot's agent mode, Gemini CLI, Aider, Cline, Continue, Zed, Windsurf, Jules, Goose, Factory, and 20-plus others. One file, one format, many agents. That's the whole pitch, and it's a good one: if your team uses more than one AI tool — and most teams now do — a single AGENTS.md beats maintaining a different rules file per tool.

So the honest scorecard so far: CLAUDE.md is the deeper integration for one tool; AGENTS.md is the broader integration across many. Neither is wrong. Both are the correct instinct — capture your conventions as code-adjacent, version-controlled text.

AGENTS.md vs CLAUDE.md: the real differences

Here's the comparison you can quote:

	CLAUDE.md	AGENTS.md
Origin	Anthropic, specific to Claude Code	Open standard, stewarded across the ecosystem
Who reads it	Claude Code only	20+ agents: Codex, Cursor, Copilot, Gemini CLI, Aider, Cline, Zed, and more
Format	Plain Markdown	Plain Markdown
Location	Repo root, ~/.claude/, or nested dirs	Repo root (nested files supported)
Loading	Automatic in Claude Code, hierarchical merge	Automatic in compliant agents
Imports	Yes — @path syntax	Convention-based; varies by tool
Cross-tool	No — other agents ignore it	Yes — that's the point

The single most important interoperability fact: Claude Code does not read AGENTS.md by default, and there is no automatic fallback. If a repo ships only AGENTS.md, Claude Code loads nothing on its own.

There's a widely used bridge for this. Because CLAUDE.md supports imports, teams write a one-line CLAUDE.md that pulls the open standard in:

@AGENTS.md

Now Claude Code reads your AGENTS.md content via the import, and every other agent reads AGENTS.md directly. One source, two entry points. It's the cleanest per-repo reconciliation available today — and it's worth doing.

But notice what just happened. You now maintain a canonical file plus a shim that points at it, in every repository, and you're trusting every developer to set up that shim correctly. That's the seam where things start to tear.

Why do both still break at team scale?

Name the enemy: convention drift.

A single file in a single repo, edited by one person, stays correct. Multiply it. Ten repos, eight engineers, four AI tools. Now the same convention — "we moved off npm to pnpm" — needs to land in ten AGENTS.md files, some CLAUDE.md imports, and whatever .cursorrules or .github/copilot-instructions.md predate the standard. Somebody updates three of them. The other seven keep telling agents to run npm install, and the agents, dutifully, do.

This is context collapse: the moment your written-down truth stops matching reality, and no single place is authoritative, so nobody can tell which copy is right. It compounds into AI amnesia — every new repo, every new laptop, every new hire starts from a blank or stale file, and the hard-won knowledge ("the staging DB is on a different port," "never run the registry GC against prod tags") has to be rediscovered or re-pasted by hand.

The files aren't the problem. The altitude is. AGENTS.md and CLAUDE.md are per-repo, per-clone artifacts. They were designed to configure one agent in one checkout — and they do that well. They were never designed to be one team's shared brain across many repos and many tools. Asking them to be that is asking a config file to do an infrastructure job.

What actually fixes it: a shared context layer above the file

The fix isn't a better file. It's moving the source of truth up a level — out of each repo and into a team-owned layer that every AI tool reads from.

This is the category we call ContextOps: managing your team's AI context as shared infrastructure rather than as per-developer config files. The same shift ops teams already made for secrets, environment config, and feature flags — stop copying them into every checkout, centralise them, and let each environment pull the current version — applied to the instructions your AI tools depend on.

Contextium is that layer. Your conventions, architecture notes, gotchas, and standards live once in a workspace your whole team shares. Every agent — Claude, Cursor, Copilot, and any MCP-connected tool — inherits the same source of truth. Update it once; every tool, every repo, every teammate sees the change on their next session. The tagline is the whole design: your whole team's AI, one shared context.

Crucially, this doesn't make you throw away AGENTS.md or CLAUDE.md. It makes them thin. The repo-level file holds what's genuinely repo-specific; the shared layer holds everything that's true across the team. The stuff that used to drift is now maintained in one place by definition.

How does the shared-layer approach work?

The mechanism is MCP — the Model Context Protocol, the open standard for connecting AI tools to external context and tools. Any MCP-compatible client can query a server for the context it needs, on demand, at the moment it needs it.

Contextium runs as that MCP server for your team's context. The flow is straightforward:

1. Write once. Conventions, standards, and project knowledge live in a workspace-scoped library — not in a file on one person's disk.
2. Every tool connects via MCP. Claude Code, Cursor, Copilot's MCP support, and anything else that speaks the protocol point at the same workspace.
3. Agents pull the current version. When an agent starts work, it reads live context from the workspace — not a cached, hand-copied file that may be weeks stale.
4. Update once, propagate everywhere. Change a convention in the workspace and the next session of every connected tool reflects it. No ten-file sweep. No shim to forget.

Because context is workspace-scoped, it also respects team boundaries. New hires inherit the accumulated knowledge on day one instead of starting from a blank CLAUDE.md. That's the end of AI amnesia: the team's context outlives any single repo, laptop, or tool choice.

We build Contextium using Contextium. Our own conventions — how we deploy, which registry prod actually pulls from, the gotchas that have bitten us — live in one workspace, and every agent any of us runs inherits them. When we changed a deploy rule, we changed it once, and nobody's assistant kept recommending the old path the next morning.

A worked example: change one convention

Say your team switches package managers: npm → pnpm. Nothing exotic — this happens constantly.

The per-file way. You open every repo. You edit each AGENTS.md. You check which repos have a CLAUDE.md import shim and which reference npm directly. You hunt down the legacy .cursorrules and copilot-instructions.md from before you adopted the standard. You push a commit to each. You hope every teammate pulls. Miss one repo, and for weeks an agent confidently runs npm install in it, fails, and a developer burns twenty minutes figuring out why the AI "suddenly broke." That miss is convention drift — it's not a rare failure, it's the default outcome of manual fan-out.

The shared-workspace way. You edit one entry in the workspace: "Package manager: pnpm. Never use npm." Save. Every connected agent, in every repo, reads the new instruction on its next session. There is no second copy to fall out of sync, because there is no second copy.

That's the difference altitude makes. The per-file approach asks N people to keep M files consistent forever. The shared-layer approach makes consistency the default, because there's exactly one thing to be consistent with.

Both files are the right first move. If your team has outgrown copy-pasting the same instructions into every repo and every tool, put the source of truth where it belongs: one shared layer above the files.

For more on getting this right, read why CLAUDE.md breaks down, our roundup of the best AI memory tools in 2026, and how to give Claude Code persistent context that survives across sessions.