Shared context for AI tools
AGENTS.md vs CLAUDE.md vs .cursorrules: the landscape
AGENTS.md vs CLAUDE.md vs .cursorrules: what each context file is, how they differ, and the limit all three share once your team uses more than one tool.
If you give AI tools project context, you have run into the file zoo. Claude Code reads a CLAUDE.md. Cursor reads its rules. A newer convention, AGENTS.md, aims to be read by many tools at once. They cover nearly the same ground, and the differences are smaller than the overlap.
Here is what each one is, how they differ, and the limit all three share that no format fixes.
What each file is
- CLAUDE.md , the file Claude Code reads from a repo: conventions, commands, architecture notes, how to run things. Tool-specific to Claude Code.
- .cursorrules / Cursor Rules , Cursor's equivalent: rules and project context Cursor applies as it works. Tool-specific to Cursor.
- AGENTS.md , a newer, deliberately cross-tool convention, a single file multiple assistants agree to read, so you do not maintain one per tool. Adoption has grown quickly across the ecosystem.
How they differ
| CLAUDE.md | .cursorrules | AGENTS.md | |
|---|---|---|---|
| Read by | Claude Code | Cursor | Multiple tools |
| Scope | Per repo | Per repo | Per repo |
| Cross-tool | No | No | Yes, that's the point |
| Maintained | By hand | By hand | By hand |
The honest read: AGENTS.md is the best of the three precisely because it is cross-tool, so adopt it if your tools support it. It removes the "one file per tool" tax. It does not remove the other two.
The limit all three share
Read the last two rows of that table again. Every one of these files is per-repo and maintained by hand. That is fine for one developer in one repo. It becomes the problem the moment you have a team and more than one repo:
- A convention that applies everywhere has to be copied into every repository.
- A change has to be edited by hand, so the files lag reality.
- Decisions that span repos or live outside code have nowhere to go.
- A new repo and a new hire start from a blank or stale file.
This is the drift we cover in keeping CLAUDE.md and .cursorrules in sync, and keeping a whole team aligned takes more than a file, see the AI coding consistency checklist. AGENTS.md helps with the cross-tool axis but not the per-repo, hand-maintained one.
What the file format can't do
A flat file is a snapshot. It cannot stay current on its own, it cannot span repos, and it cannot hold the team's decisions and recent activity. For those, the conventions and decisions need to live in one shared source that every tool reads over MCP and that updates as work happens, which is shared context for AI tools. The file then becomes a thin, repo-local pointer rather than the whole story, the pattern in giving Claude Code your whole project context.
The short version
Use AGENTS.md where you can; it beats one file per tool. But a file is still a per-repo snapshot. The team-and-multi-repo problem needs a shared source, not a better file format.
TL;DR
CLAUDE.md (Claude Code), .cursorrules (Cursor), and AGENTS.md (cross-tool) are per-repo context files that overlap heavily; AGENTS.md is the best because it is read by multiple tools. But all three are per-repo and hand-maintained, so across a team and many repos they drift, leave cross-repo decisions homeless, and start new repos blank. A shared context source read over MCP solves what the file format cannot.
Where context files fit, and where a team needs one shared, current source instead.
Related reading
How to keep CLAUDE.md and .cursorrules in sync
Keeping CLAUDE.md and .cursorrules in sync by hand drifts fast. Here is why, and how a shared context source keeps every tool's rules current across a team.
What is shared context for AI tools? (2026 guide)
Shared context for AI tools is the company, project, and decision background every AI reads automatically, so your whole team's tools stop guessing.
How to give Claude Code your whole project context
Give Claude Code your whole project context, not just one repo's CLAUDE.md. Here is how a shared source keeps it current across repos, tools, and teammates.
AI coding consistency across a team: a checklist
A practical checklist for keeping AI coding assistants consistent across a team, so Claude Code and Cursor produce code that fits your standards, not generic defaults.
Frequently asked questions
What is the difference between AGENTS.md, CLAUDE.md, and .cursorrules?
They are all per-repo context files that tell an AI tool how to work in a codebase, but they belong to different tools. CLAUDE.md is read by Claude Code, .cursorrules (and Cursor Rules) by Cursor, and AGENTS.md is a newer cross-tool convention several tools have adopted. They overlap heavily in content; the difference is mostly which tool reads which file.
Should I use AGENTS.md or CLAUDE.md?
If you use one tool, use the file that tool reads. AGENTS.md is worth adopting because it aims to be cross-tool, so more assistants read the same file. But all of these are still per-repo, static, and hand-maintained, so once a team uses several tools across several repos, keeping them in sync becomes the real problem, which a shared context layer solves.