Home / AGENTS.md vs CLAUDE.md vs Cursor rules

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

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.

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:

@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):

---
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.

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.

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