AGENTS.md vs CLAUDE.md vs .cursor/rules: which file does your AI agent read?

Different AI coding tools look for different instruction files. If you only keep rules in one tool's format, the others guess. If you copy the same wall of text into every format, the copies drift. This guide maps what each file is for, and a setup that stays maintainable.

The short answer

• AGENTS.md is the cross-tool open convention. OpenAI Codex, Cursor, and many other agents read it as plain Markdown project instructions.
• CLAUDE.md is Claude Code's project memory file. It can pull in other files with @path syntax (for example @AGENTS.md).
• Cursor project rules live in .cursor/rules/*.mdc with YAML frontmatter (description, globs, alwaysApply). The legacy single-file .cursorrules format is deprecated; prefer .mdc rules.
• Windsurf stores Cascade rules as Markdown under .windsurf/rules/.

Comparison

File	Who reads it	Shape	Best for
AGENTS.md	Codex, Cursor, and other AGENTS.md-aware tools	Plain Markdown at the repo root (and optionally nested)	Shared source of truth: stack, commands, hard rules, definition of done
CLAUDE.md	Claude Code	Markdown; can import other files with @path	Claude-specific notes on top of shared AGENTS.md
.cursor/rules/*.mdc	Cursor	Markdown + frontmatter (description, globs, alwaysApply)	Path-scoped rules that load only when matching files are in context
.cursorrules (legacy)	Older Cursor setups	Single root file, no frontmatter	Migrate away; use .mdc rules or AGENTS.md
.windsurf/rules/	Windsurf Cascade	Markdown files with activation modes (always / glob / manual)	Same ideas as Cursor rules, in Windsurf's layout

What each file is for

AGENTS.md

AGENTS.md is a simple open format: a README for agents. Put durable project guidance here: how to build and test, folder layout, conventions, and the never-do list. Keep it short enough that tools will follow it. Codex discovers project AGENTS.md files along the path from the repo root to your working directory; closer files can refine broader ones. Copy-paste starter: Codex AGENTS.md template.

CLAUDE.md

Claude Code loads CLAUDE.md at the start of a session. Use @path/to/file anywhere in that file to import more Markdown. Relative paths resolve from the file that contains the import. A common pattern is a one-line import of shared rules, then a few Claude-only notes:

CLAUDE.mdcopy

@AGENTS.md

# Claude Code notes
- Prefer the project package scripts over ad-hoc commands.
- Before touching auth, payments, or migrations: write a short plan and wait for go.

For a fuller template, see the free CLAUDE.md guide.

Cursor .cursor/rules/*.mdc

Each rule is an .mdc file under .cursor/rules/. Frontmatter controls when it loads:

• alwaysApply: true — included in every chat.
• globs with alwaysApply: false — attached when matching files are in context.
• description without globs — Cursor can pull the rule in when it looks relevant.
• Neither description nor globs — manual via @rule-name.

Plain .md files in that folder are ignored by the rules system (no frontmatter). Prefer small scoped rules over one giant file. Example RLS rule (also free on GitHub as nextjs-supabase-rls.mdc):

.cursor/rules/30-database-rls.mdccopy

---
description: Migrations and row-level security
globs: supabase/**
alwaysApply: false
---
- For each new table: enable RLS + policies in the same migration.
- Policies use (select auth.uid()); separate policies per command.
- Never disable RLS to "make it work". Fix the policy instead.

More Next.js + Supabase detail: Cursor rules for Next.js + Supabase. For a Python backend skeleton (venv, pytest, type hints), see Cursor rules for Python.

Windsurf .windsurf/rules/

Cascade reads Markdown rules from .windsurf/rules/, with activation similar in spirit to Cursor (always on, glob, or manual). Keep those files thin and mirror the ideas already in AGENTS.md. See Windsurf rules.

Recommended setup: one source of truth

1. Write AGENTS.md first. Stack, commands, hard rules, workflow, definition of done.
2. Add a thin CLAUDE.md that starts with @AGENTS.md, then only Claude-specific notes.
3. Add scoped Cursor rules for paths that need extra precision (auth, RLS, Stripe, env). Do not paste the entire AGENTS.md into every .mdc.
4. If you use Windsurf, port the same scoped ideas into .windsurf/rules/ without inventing a third full copy of the essay.
5. Delete or migrate .cursorrules so you are not maintaining a legacy file Agent mode may ignore.

When a rule misbehaves, fix it in the source of truth (AGENTS.md or the one scoped rule), not in three places.

layout sketchcopy

repo/
  AGENTS.md                 # shared source of truth
  CLAUDE.md                 # @AGENTS.md + Claude-only notes
  .cursor/rules/
    00-core.mdc             # alwaysApply: true (short)
    30-database-rls.mdc     # globs: supabase/**
    40-stripe.mdc           # globs: app/api/stripe/**
  .windsurf/rules/          # optional mirror for Cascade
    database-rls.md

Free files you can drop in today

• nextjs-supabase-rls.mdc — Cursor rule for Supabase RLS
• agent-guardrails.md — guardrail snippets for AGENTS.md or system prompts
• agents-md-game-modding.md — AGENTS.md template for mods and small game tools
• godot-jam-timeline.md — 48-hour jam timeline for agents

FAQ

Do I need AGENTS.md, CLAUDE.md, and .cursor/rules all at once?

Only if you use more than one tool. Shared rules live in AGENTS.md. Claude Code gets a thin CLAUDE.md with @AGENTS.md. Cursor gets scoped .mdc files when you need path-based loading. Do not duplicate the essay.

Is .cursorrules still supported?

It is legacy. Prefer .cursor/rules/*.mdc with frontmatter, and migrate remaining content into those files or into AGENTS.md.

Can Claude Code read AGENTS.md?

Its native file is CLAUDE.md. Import shared rules with @AGENTS.md so you maintain one copy. Imports are expanded when the session starts.

What goes in AGENTS.md vs a Cursor rule?

AGENTS.md: stack, commands, never-dos, done criteria. Cursor .mdc: path-scoped guidance via globs so auth, migrations, or webhooks only load when those files are in context.

Where do Windsurf rules live?

Under .windsurf/rules/ as Markdown. Keep them aligned with AGENTS.md rather than inventing a separate doctrine.

Want the whole drawer?

Skip the setup. The Claude Code Kit ($24) ships a fill-in CLAUDE.md, 6 least-privilege subagents, 10 slash commands, settings.json permissions and 4 tested hooks. The Vibe Starter Rules Pack ($19) ships a ready AGENTS.md + CLAUDE.md pair, 8 scoped .cursor/rules, 12 slash-command prompts and launch checklists for Next.js + Supabase + Stripe.

Buy Claude Code Kit · $24
Buy Vibe Starter · $19
See all 5 kits

Not ready for a full pack? Start with One-File Agent Rules ($9), one universal AGENTS.md for any stack, or get the free Starter AGENTS.md by email.

Launch week: 30% off any kit with code LAUNCH at Stripe checkout, through Oct 28, 2026. 14-day refund.

---

Originally published at agentkitdrawer.com.