AGENTS.md vs Cursor Project Rules (.mdc): Which to Use and How to Run Both (2026)

Cursor introduced Project Rules in .cursor/rules/*.mdc format as the evolution of .cursorrules, with per-file activation, conditional loading, and better scoping. AGENTS.md arrived from the other direction — a multi-tool open standard that gives you portability across Codex, Copilot, Gemini CLI, and a growing ecosystem. Both live in the same repository and solve overlapping problems.

This is not a “which is better” argument. It is a direct comparison of what each format does well, where each one falls short, and how to structure a project so both work without duplication or conflict.

Format and Syntax Comparison

The most visible difference is the file format.

AGENTS.md is plain Markdown with no frontmatter, no activation metadata, no special syntax. Its structure is entirely convention-based — you use headings to organize sections, and tools parse those headings to apply instructions.

# AGENTS.md

## Commands
- Install: pnpm install
- Test: pnpm test:run
- Lint: pnpm lint

## Code Style
- TypeScript strict mode; no `any`
- Named exports over default exports
- Prefer `const` over `let`

## Boundaries
- Never modify `/migrations/` directly
- Auth middleware lives in `middleware/auth.ts` — do not inline auth logic elsewhere

Cursor Project Rules use .mdc files (Markdown with a YAML frontmatter). The frontmatter drives activation behavior that AGENTS.md does not support natively.

---
description: TypeScript and React conventions for the frontend
globs: ["src/**/*.tsx", "src/**/*.ts"]
alwaysApply: false
---

# Frontend Conventions

Always use TypeScript strict mode. No `any`.
React components are server components by default.
Use shadcn/ui components from `@/components/ui/`.

The frontmatter fields that matter:

This is the key functional difference: Cursor Project Rules support conditional loading based on file context. AGENTS.md is always-on.

Scoping and Activation

AGENTS.md scoping works through file system hierarchy:

• Root AGENTS.md applies to the entire repository
• src/AGENTS.md applies to everything in src/ and below
• src/api/AGENTS.md applies to everything in src/api/
• Nested files inherit from parent files; more specific files override on conflict

There is no dynamic activation — AGENTS.md is loaded based on where Claude (or another tool) is working in the file tree.

Cursor Project Rules scoping works through two mechanisms:

1. globs activation — When you open a file that matches a rule’s glob pattern, Cursor automatically loads that rule. Open src/api/routes/users.ts and rules with globs: ["src/api/**"] load automatically.

2. alwaysApply: true — The rule loads in every session regardless of what files are open.

3. Manual invocation — Even with alwaysApply: false and no matching globs, you can reference a rule directly in a prompt with @rule-name.

This means Cursor Project Rules can be significantly more context-specific than AGENTS.md. You can have a 200-rule project and only load the 15 rules relevant to the file you are editing.

Practical Behavior Comparison

Token Cost Reality Check

This is where the comparison becomes concrete. A project with 30 Cursor Project Rules, each averaging 300 tokens, has 9,000 tokens of rule content total. With glob activation, a session editing src/api/users.ts might load 4 matching rules = 1,200 tokens. A session editing src/components/Button.tsx loads 3 different rules = 900 tokens.

The equivalent in AGENTS.md would require either: a) One large AGENTS.md (9,000 tokens, loaded in every session) b) Multiple AGENTS.md files organized by directory (each session loads root + relevant subdirectory)

For projects with many specialized rules, Cursor’s glob-based activation is genuinely more token-efficient within Cursor. For cross-tool usage, AGENTS.md’s hierarchical structure is your only option.

What Cursor Agent Mode Actually Reads

This is a common source of confusion. Cursor has multiple modes with different configuration loading:

• Chat and Composer modes: Read .cursorrules (deprecated) and .cursor/rules/*.mdc files. Do not read AGENTS.md.
• Agent mode: Reads AGENTS.md and .cursor/rules/*.mdc files. Does not read root .cursorrules.

So if you use Cursor Agent mode and you have only .cursorrules, your rules are silently ignored. If you have only .cursor/rules/, those work in Agent mode. If you have AGENTS.md, that works in Agent mode. You can have both.

The practical recommendation for Cursor-primary teams: use .cursor/rules/*.mdc as your primary system (it works everywhere in Cursor, including Agent mode), and maintain AGENTS.md as the multi-tool foundation for when team members use other tools.

Running Both: The Dual-Stack Setup

Most real teams end up running both formats. Here is a clean separation that avoids duplication:

project-root/
├── AGENTS.md                          # Foundation layer: cross-tool rules
└── .cursor/
    └── rules/
        ├── foundation.mdc             # Mirrors AGENTS.md with alwaysApply: true
        ├── typescript.mdc             # TS rules, globs: ["**/*.ts", "**/*.tsx"]
        ├── api.mdc                    # API rules, globs: ["src/api/**"]
        ├── testing.mdc                # Test rules, globs: ["**/*.test.*", "**/*.spec.*"]
        └── migrations.mdc             # DB rules, globs: ["migrations/**", "src/db/**"]

AGENTS.md holds the universal baseline — commands, architecture overview, hard constraints, tech stack. This is what non-Cursor tools read.

.cursor/rules/*.mdc holds Cursor-specific specialization — context-sensitive rules that activate based on which files are open, rules with rationale and examples that would bloat AGENTS.md, anything Cursor-specific.

The foundation.mdc is a thin wrapper:

---
description: Core project rules (mirrors AGENTS.md)
alwaysApply: true
---

@AGENTS.md

Wait — does Cursor support @AGENTS.md syntax in MDC files? No, not directly. The pragmatic approach is to keep foundation.mdc as a short summary that covers the essentials, and accept a small amount of duplication between it and AGENTS.md.

Or: use a generation script to produce foundation.mdc from AGENTS.md automatically.

#!/bin/bash
# scripts/sync-cursor-rules.sh
# Sync AGENTS.md content into foundation.mdc

cat > .cursor/rules/foundation.mdc << EOF
---
description: Core project rules (auto-generated from AGENTS.md)
alwaysApply: true
---

$(cat AGENTS.md)
EOF
echo "Updated .cursor/rules/foundation.mdc from AGENTS.md"

Add this to a pre-commit hook to keep them in sync.

Converting Between Formats

AGENTS.md section → Cursor MDC file:

# AGENTS.md section (before)
## API Rules
- All endpoints need JWT auth via requireAuth middleware
- Return RFC 7807 error format
- Never hardcode secrets

---
description: API layer rules — authentication, error handling, security
globs: ["src/api/**/*.ts", "src/routes/**/*.ts"]
alwaysApply: false
---

# API Layer Rules

All endpoints require JWT validation via the `requireAuth` middleware in `middleware/auth.ts`.

Return errors in RFC 7807 problem+json format:
\`\`\`ts
{ type: string; title: string; status: number; detail: string; }
\`\`\`

Never hardcode JWT secrets or API keys — use environment variables.

The MDC version is more verbose (it has the frontmatter and richer explanation), but it only loads when editing API files. The AGENTS.md version is terse but always-on.

Cursor MDC file → AGENTS.md section:

Strip the frontmatter and any Cursor-specific syntax. Distill the rule content to the most essential form. Add it under the appropriate AGENTS.md section heading.

Decision Guide

The short version: Cursor MDC files win on depth and context-sensitivity within Cursor. AGENTS.md wins on portability and simplicity. The dual-stack setup costs a small amount of maintenance overhead and gives you both.

Related Articles

• .cursorrules vs .cursor/rules (MDC): Which Format to Use in 2026
• Migrating from .cursorrules to AGENTS.md
• AGENTS.md vs CLAUDE.md: What’s the Difference and When to Use Each