Cursor rules vs CLAUDE.md vs AGENTS.md explained

Your AI coding agent starts every session knowing nothing about your project. Rules files fix that: a short document the agent reads before it touches your code. The trouble is that each tool wants its own file, in its own place, with its own quirks. This is a plain guide to the three you will meet most: Cursor rules, CLAUDE.md and AGENTS.md.

Checked on 27 Oct 2026 against Cursor's rules docs, Claude Code's memory docs and agents.md. These tools change quickly, so confirm details against the current docs before you rely on them.

The short version

• Cursor rules live in .cursor/rules/ as .mdc files. They can be scoped to file patterns. Cursor also reads AGENTS.md.
• CLAUDE.md is what Claude Code reads at the start of a session. It can sit in the repo root, in subfolders, or in your home folder (~/.claude/CLAUDE.md) for personal preferences.
• AGENTS.md is a tool-neutral convention that a growing list of agents read. It is the best default if you switch tools or work in a team.

Cursor rules

Cursor stores project rules as .mdc files in .cursor/rules/. Each file starts with frontmatter (description, globs, alwaysApply) that decides when it loads: always, when a matching file is in context, when the agent judges it relevant from the description, or only when you @-mention it. A plain .md file in that folder is ignored. Cursor's docs suggest keeping each rule under 500 lines.

You may still see a single .cursorrules file in older projects. Cursor's current docs describe .cursor/rules and AGENTS.md and do not cover .cursorrules, so treat it as legacy: move its content into rule files before you depend on it.

Use it when you live in Cursor and want different guidance for different parts of the codebase, such as one rule for API routes and another for React components. There is a worked example in Cursor rules for Next.js and Supabase.

CLAUDE.md

CLAUDE.md is a markdown file Claude Code loads as context. Put project-wide facts in the root file: how to run tests, which commands to avoid, naming conventions, the architecture in a paragraph. Claude Code's docs recommend keeping it under about 200 lines.

One detail matters more than it looks. The docs describe CLAUDE.md as context, not enforced configuration. Claude reads it and usually follows it, but nothing guarantees compliance. If something must never happen, such as reading your .env file, use permission settings or hooks rather than a sentence in the file.

Use it when Claude Code is your main agent.

AGENTS.md

AGENTS.md is a plain markdown file in the repo root, meant to be read by any coding agent. The agents.md site lists tools such as Codex, Cursor, Gemini CLI, Windsurf, Aider, Jules, Zed and Warp as compatible, and says it is stewarded by the Agentic AI Foundation under the Linux Foundation. There are no required fields. In a monorepo the closest file to the code being edited wins, and a direct instruction in chat overrides the file.

Claude Code's position is worth knowing. It can read AGENTS.md directly (from v2.1.277), but only when there is no CLAUDE.md in the working directory or above it. If you have both, Claude reads CLAUDE.md and ignores AGENTS.md unless you import it.

Use it when more than one tool touches the repo, or you want one source of truth that does not lock you in. A copyable starter is in our AGENTS.md example.

Using AGENTS.md and CLAUDE.md together

The simplest way to avoid two files drifting apart is to write the shared rules once in AGENTS.md and have CLAUDE.md import it:

@AGENTS.md

## Claude Code
Only the lines that apply to Claude Code go here.

Claude Code expands the import when it loads the file. You keep one set of project rules and a small Claude-specific section.

Which one should you use?

Situation	Start with
Solo, only Cursor	AGENTS.md for simple rules, or .cursor/rules when you need scoping
Solo, only Claude Code	CLAUDE.md
Several tools, or a team	AGENTS.md, then CLAUDE.md importing it, then tool-specific files only where needed

What belongs in any rules file

1. Stack and versions. "Next.js App Router, TypeScript strict, Supabase" saves the agent from guessing.
2. Commands. How to install, run, test and lint. Agents that can run tests fix their own mistakes.
3. Boundaries. Folders it should not edit, secrets it must never print, migrations it must not run.
4. Conventions. File naming, where components go, how errors are handled.
5. Definition of done. Tests pass, types check, no stray console logs.

Common mistakes

• Writing an essay. Rules compete with your prompt for attention. Short, specific lines beat long explanations.
• Vague advice. "Write clean code" does nothing. "Use server actions for mutations; never call the database from client components" does.
• Letting files drift apart. If you keep three files, generate them from one source or import one from another.
• Never updating them. When the agent makes the same mistake twice, add a line.

Keep one source, write many files

The Vibemast Ship-It Kit does exactly this. Agent rules for Next.js with Supabase, Vite with React, FastAPI and Phaser are written once, and a small generator script outputs the right file for Cursor, Claude Code, Copilot and AGENTS.md-aware tools. If you want to try it on a single stack first, the free mini pack has a Vite and React rule set and the generator. Neither makes an agent follow rules perfectly, so keep the checks in your own tests and CI.

Hoist it. Ship it.

Copy-ready starters: a Cursor rules template, a CLAUDE.md example and 12 AI coding agent rules that work in any of the three files.

Set up all three in one go

1. Download the free mini pack (free, CC BY 4.0).
2. Run node scripts/generate.mjs --stack vite-react --out ../my-app. It writes AGENTS.md, CLAUDE.md, .cursor/rules/*.mdc and .github/copilot-instructions.md from one source.
3. Open AGENTS.md and fill in the project commands, so the agent can run your typecheck, lint and tests.
4. Commit the files. When a rule changes, edit the source and generate again, instead of editing three files by hand.

The free pack ships the Vite and React stack. The Ship-It Kit adds the same generator setup for Next.js with Supabase, FastAPI and Phaser.

Who the paid kit is for, and who it is not for

• Worth it if you build on one of its four stacks (Next.js with Supabase, Vite with React, FastAPI, Phaser) and want tested files and prompts today instead of writing and testing your own.
• Not worth it if you only need one rules file for one project. The free guides and the free mini pack are enough, and you can adapt them yourself.

Related guides

• When your AI agent keeps breaking your code

FAQ

Does Cursor read CLAUDE.md?

Cursor's docs describe project rules and AGENTS.md, so put shared rules in AGENTS.md if you want Cursor to read them.

Can I symlink the files?

You can, and agents.md suggests symlinks when migrating an older file name. An @AGENTS.md import in CLAUDE.md is simpler and works the same on every system.

Which wins if the files disagree?

It depends on the tool, and the agent may follow either. That is the main reason to keep one source of truth.

How long should a rules file be?

Short. Under about 200 lines for CLAUDE.md and under 500 for a Cursor rule, per their docs. Split by topic after that.