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

Published October 14, 2026

Every AI coding tool looks for its instructions in a different place, so most repos end up with three files saying slightly different things. Here's how they fit together.

.cursor/rules/*.mdc (Cursor)

Cursor's project rules are Markdown files with YAML frontmatter. The frontmatter has three keys: description, globs and alwaysApply.

---
description: Supabase clients and Row Level Security
globs: src/lib/supabase/**,supabase/**
alwaysApply: false
---
- Every table in public MUST enable RLS...

• alwaysApply: true means the rule is in every request. Use it for core conventions and security.
• globs attach the rule when matching files are in context.
• description only lets the agent pull the rule in when it decides it's relevant.

Splitting rules by area keeps context small, so the agent follows them more reliably.

AGENTS.md (Codex, Copilot, Jules, Windsurf and more)

AGENTS.md is a plain Markdown file at the repo root that a growing list of agents reads automatically. Put commands (install, build, test), project layout, non-negotiable rules and a definition of done in it.

CLAUDE.md (Claude Code)

Claude Code loads CLAUDE.md at startup and supports @path imports. Make it one line, @AGENTS.md, plus any Claude-specific habits. Now you have one source of truth.

A layout that works

AGENTS.md            # source of truth: stack, commands, rules, done criteria
CLAUDE.md            # @AGENTS.md + Claude-specific tips
.cursor/rules/
  00-core.mdc        # alwaysApply
  10-supabase.mdc    # globs: supabase/**, src/lib/supabase/**
  40-security.mdc    # alwaysApply

Write rules agents actually follow

• Use imperatives with concrete names: "use getUser(), never getSession() on the server" beats "handle auth securely."
• Include a definition of done, such as "npm run build passes."
• Show one canonical code example per pattern.
• Test the rules on a fresh project. Rules that don't compile are worse than no rules.

Want this done for you? Pack #1 ships all three, build-tested.