agents.md vs CLAUDE.md vs .cursorrules: Which AI Coding File to Use

If you've used Cursor, Claude Code, or an agentic coding tool lately, you've probably run into three files: CLAUDE.md, .cursorrules, and agents.md. They all do the same broad job—tell an AI coding agent how your project works—but they're read by different tools, in different ways. This guide breaks down what each one is, when to reach for which, and how they fit together on a real codebase.
The three files in one line each
CLAUDE.md is Anthropic's instruction file, read by Claude Code. .cursorrules (and its newer .cursor/rules form) is Cursor's. agents.md is an emerging, tool-agnostic standard that several agents are converging on. Same goal, different audiences.
What is CLAUDE.md?
CLAUDE.md is a Markdown file Claude Code reads automatically when it starts working in your repo. It's where you put the context the agent can't infer: how to run the build, your testing conventions, architectural rules, and the things you'd otherwise repeat in every prompt. Claude loads it as durable context, so you explain your project once instead of every session.
Keep it concrete. 'Run npm run check before committing' beats 'follow our quality standards.' The more specific the instruction, the less the agent guesses.
What is .cursorrules?
.cursorrules is Cursor's equivalent—a file at the project root that shapes how Cursor's AI behaves. It covers the same ground as CLAUDE.md: coding style, frameworks in use, patterns to follow, things to avoid. Cursor has since introduced a .cursor/rules directory for multiple scoped rule files, but the single .cursorrules file still works and is widely used.
What is agents.md?
agents.md is the newest of the three and the most ambitious: a single, tool-agnostic instruction file that any agent can read, rather than one file per vendor. The idea is simple—your project's rules shouldn't be locked to one tool. As more agents adopt it, agents.md becomes the portable layer, and the vendor-specific files become thin pointers to it.
How they interact across tools
On a real codebase you'll often have more than one. A team using both Claude Code and Cursor might keep a CLAUDE.md and a .cursorrules that say largely the same thing. That duplication is the problem agents.md is trying to solve. The pragmatic pattern today: write your rules once, then mirror the essentials into each tool's file so every agent—whoever's driving—starts from the same context.
When to use which
Use CLAUDE.md if your team codes with Claude Code. Use .cursorrules (or .cursor/rules) if you're in Cursor. Adopt agents.md if you want a portable, future-facing source of truth—especially across a mixed toolchain or multiple agents. In practice, many teams maintain agents.md as the canonical file and keep slim CLAUDE.md and .cursorrules files that defer to it.
AGENTS.md vs CLAUDE.md vs .cursorrules at a glance
If you just want the short version, here is how the three line up on the axes that decide which you reach for: who reads the file, and when it earns its place in your repo.
CLAUDE.md is read by Claude Code. Reach for it when Claude Code is your primary agent, and keep your build commands, test conventions, and architecture rules there.
.cursorrules (and the newer .cursor/rules directory) is read by Cursor. Reach for it when Cursor is your main editor; it shapes Cursor's coding style and the patterns it follows.
agents.md is read by any agent that adopts the standard. Reach for it when you run a mixed toolchain or want one portable source of truth that is not tied to a single vendor.
Can you use all three?
Yes—and on mixed teams you probably should. The risk is drift: three files that slowly disagree. The fix is to treat one as canonical and generate the others from it, so a single change propagates everywhere instead of being copy-pasted by hand.
How to generate them automatically
Writing and syncing these files by hand gets old fast. Keeborg generates CLAUDE.md, .cursorrules, and agents.md from a single spec, so all three stay consistent as your project changes. If you want the deeper comparison of just the two originals, see our CLAUDE.md vs .cursorrules guide.
Frequently Asked Questions
Is agents.md replacing CLAUDE.md and .cursorrules?
Not yet. agents.md is gaining adoption as a portable standard, but CLAUDE.md and .cursorrules are still what Claude Code and Cursor read natively. For now, most teams run agents.md alongside them rather than instead of them.
Do I need all three files?
Only for the tools you use. A Claude Code shop needs CLAUDE.md; a Cursor shop needs .cursorrules. Add agents.md when you want one portable source of truth across tools.
What goes in these files?
Project context the agent can't infer: build and test commands, framework choices, coding conventions, architectural rules, and anything you find yourself repeating in prompts.
Where do these files live?
At the repository root, so the agent finds them automatically when it opens your project.
Does Cursor read agents.md?
Not by default today. Cursor reads .cursorrules and the .cursor/rules directory; whether it picks up agents.md depends on Cursor adopting the standard. If you keep an agents.md, mirror its essentials into .cursorrules so Cursor still gets your rules.
agents.md vs CLAUDE.md — which should I use?
Use CLAUDE.md if Claude Code is your main agent and you want the file it reads natively. Use agents.md if you want a portable file that is not tied to one vendor. On a mixed team, many keep agents.md as the source of truth and a thin CLAUDE.md that points to it. If you would rather not write it by hand, you can generate a CLAUDE.md from your project in seconds.
Is agents.md an official standard?
It is an emerging, community-driven convention rather than a formal spec owned by one vendor. Adoption is growing across agents, which is the whole point: the more tools read it, the more useful a single agents.md becomes. Until support is universal, keep the tool-specific files as a fallback.
However you split it, the principle is the same: give the agent clear, specific instructions once, and stop re-explaining your project on every prompt.
One rule, three files: a quick example
Say your rule is: always run the test suite before committing. In CLAUDE.md you'd write a short, imperative line under a Commands or Workflow heading—'Run npm test before every commit; do not commit failing code.' In .cursorrules you'd phrase the same instruction so Cursor's agent follows it. In agents.md you'd write it once as the canonical rule and let the tool-specific files point back to it. The wording barely changes; what changes is which agent reads it. That's the whole reason the duplication problem exists—and why a single source of truth is worth the small upfront effort.
Common mistakes to avoid
Three traps catch most teams. First, writing vague rules the agent can't act on—'be consistent' tells it nothing. Second, letting the files drift until CLAUDE.md and .cursorrules quietly contradict each other. Third, dumping your entire wiki into the file; keep it to what the agent needs to act on, not everything a human might want to read. Short, specific, and in sync beats long and stale every time.
You know the theory.
Now install the system.
The Dev System is a complete spec-driven development methodology you install in 30 seconds. 10 skills, a 95/100 quality gate, a continuity protocol, and a security audit — personalised to your framework, deploy target, and preferences.
CLAUDE.md ← Your rules
skills/
session-continuity/ ← Never lose context
multi-agent-qa/ ← 95/100 quality gate
security-audit/ ← Blocks bad deploys
seo-aeo-pass/ ← Every public page
research-and-plan/ ← Before any code
nextjs-scaffold/ ← Your framework
vercel-deploy/ ← Your deploy target
resend-email/ ← Your email provider
post-launch/ ← Monitoring + care
templates/
project-CLAUDE.md ← Per-project setup
continuity/ ← decisions, changelog,
session-logReady to build your next project?
Generate 8 AI-agent-ready specification documents from a plain English description in under 90 seconds.
Get Started Free