AGENTS.md vs Cursor Rules: The Portability Tax You Can’t Ignore

Cursor crossed $2 billion in annualized revenue with over 1 million paying subscribers by February 2026, and it’s now used inside 64% of Fortune 500 companies. That scale means the configuration choices you make today aren’t just about your current workflow—they lock in or lock out your future options. The debate between AGENTS.md and Cursor Rules isn’t a religious war over syntax. It’s a question of whether you’re building on open infrastructure or betting everything on a single vendor’s roadmap, and whether that tradeoff is worth the specific capabilities you gain in return.

The Core Tension: One Standard vs. One Tool

AGENTS.md is the cross-tool open standard read natively by 20+ tools including Cursor, Codex, Copilot, Gemini CLI, Aider, Windsurf, and Zed. It became a Linux Foundation-hosted standard under the Agentic AI Foundation, adopted by 60,000+ repositories as of May 2026. The format is deliberately minimal: plain markdown with no required fields or frontmatter, a 32 KiB default cap on file body, and support for nested subdirectory files that override by concatenation. That simplicity is its superpower and its limitation.

Cursor Rules, by contrast, are Cursor-specific. The legacy .cursorrules file has been replaced by .cursor/rules/*.mdc as Cursor’s current project rules format. The MDC format uses YAML frontmatter with alwaysApply and glob properties for scoped rule activation—features AGENTS.md simply doesn’t have. Cursor prefers .cursorrules over AGENTS.md when both exist in the same repository, and .cursorrules is silently ignored in Cursor’s Agent mode, making .cursor/rules/*.mdc required for agentic workflows.

Here’s what this means in practice: AGENTS.md has no built-in permission model, no glob-scoped activation, no hooks, and no @import syntax in the base specification. Cursor’s format gives you surgical control over when rules fire. AGENTS.md gives you the confidence that any agent dropping into your repo will see the same baseline context.

Feature	AGENTS.md	.cursor/rules/*.mdc
Format	Plain markdown, no frontmatter	Markdown + YAML frontmatter
Tool support	20+ tools natively	Cursor only
Scoped activation	No	alwaysApply + glob patterns
Permission model	None (prose only)	Four activation modes + per-rule controls
Agent mode support	Yes	Required (.cursorrules ignored)
Subdirectory overrides	Concatenation-based	Native glob scoping

The average developer uses 2.3 AI coding tools. If you’re one of them, this table already tells you most of what you need to know.

The Instruction Budget Crisis

Here’s a pattern I’ve observed: the context budgeting problem. Frontier LLMs reliably follow roughly 150 to 200 instructions, and Claude Code’s system prompt already consumes about 50 of that budget. Every line in your config file spends from that scarce reserve. Chroma’s context-rot study of 18 frontier models across 194,480 API calls showed uniform performance degradation as input context grows. Longer isn’t better—it’s worse.

This is where the AGENTS.md vs Cursor Rules decision gets interesting. A single monolithic AGENTS.md file is easier to maintain and achieves higher instruction adherence because it loads deterministically as ambient context. Modular .cursor/rules/*.mdc files or Skills offer scoped activation and reusable workflows, but rely on agent-decided invocation that is unreliable.

Vercel’s internal agent evals found a compressed 8KB AGENTS.md achieved 100% compliance on Next.js 16 API evals, while Claude Code Skills maxed at 79% and were never invoked in 56% of eval cases. That’s not a minor gap. When your build pipeline depends on consistent agent behavior, deterministic loading beats “maybe it’ll fire” every time.

The contrarian take here is that Skills—the supposedly sophisticated modular capability system—are fundamentally less reliable than a single well-structured AGENTS.md file. The industry narrative frames Skills as the evolution of agent configuration, with guides recommending AGENTS.md + Skills as the 2026 best practice for layered architecture. But anecdotal evidence from Vercel’s evals suggests that agent-decided activation fails more often than it succeeds.

The Cost of Context: When More Hurts

Adding more context to agents is assumed to improve performance, but research shows context files can actively harm outcomes. ETH Zurich research found LLM-generated context files reduce task success rates by an average of 3% and increase inference costs by over 20%, while human-written files add only a 4% marginal success gain for up to 19% higher cost. The researchers recommend omitting context files entirely.

This is a brutal finding for teams who’ve been stuffing their AGENTS.md files with comprehensive project overviews, setup commands, code style guides, testing instructions, and PR guidelines. The industry guides recommend exactly this. The science says it backfires.

What actually works? Minimal, non-inferable project details. Things an agent genuinely can’t figure out from reading the code. Custom build commands with non-obvious flags. Internal library conventions that aren’t documented elsewhere. Security boundaries that must be respected. Everything else is noise that degrades performance and inflates your inference bill.

For a deeper dive on writing files that respect LLM instruction budgets, see our guide on how to write an AGENTS.md file for Cursor, Copilot & Codex. The layered configuration model there keeps your context lean without sacrificing cross-tool consistency.

The Portability Tax: What You Give Up for Open Standards

Cross-tool portability via AGENTS.md ensures every agent sees the same baseline context, but sacrifices tool-specific power features. Claude Code’s permission hooks, Cursor’s glob-scoped rule activation, and native @import syntax in CLAUDE.md all vanish when you standardize on AGENTS.md alone.

Tool-specific formats unlock richer native capabilities, but fragment the instruction base and force teams to maintain parallel rule sets against that scarce ~150-instruction budget. It’s a genuine dilemma with no clean answer.

The 2026 best practice for multi-tool teams is a layered architecture with AGENTS.md as the canonical source of truth, supplemented by thin tool-specific adapter files. This isn’t theoretical—it’s the pattern that lets you keep portability without surrendering capability. Your AGENTS.md contains the universal stuff: stack description, build commands, test patterns, security boundaries. Your .cursor/rules/*.mdc files contain only Cursor-specific scoping. Your CLAUDE.md contains only Claude Code-specific permissions and hooks.

Most .cursorrules files port directly to AGENTS.md with minimal changes, as the content format is essentially identical plain Markdown. The migration is mechanical, not creative. Strip Cursor-specific syntax, wrap in a clear top-level heading, add standard sections for test and build commands, and move tool-specific overrides to adapter files.

For Cursor-only teams, the recommended path is migrating from .cursorrules to .cursor/rules/*.mdc to enable scoped, glob-pattern rules and Agent mode compatibility. If you’re in that camp, our Cursor Rules examples: real working configurations covers the four activation types and provides a step-by-step migration path.

The Pricing Reality at Scale

Let’s talk money, because configuration choices have cost consequences. Cursor’s Teams pricing includes Standard at $40/user/month (annual $32/user) and Premium at $120/user/month (annual $96/user), with annual billing saving approximately 20%.

That’s before you factor in inference costs from bloated context files. A 19% cost increase from unnecessary context isn’t trivial at that scale—it compounds monthly.

The open standard doesn’t eliminate these costs, but it prevents lock-in. If Cursor raises prices or changes terms, your AGENTS.md investment transfers to Codex, Copilot, or whatever tool launches next quarter. Your .cursor/rules/*.mdc investment does not.

This is the infrastructure mindset: pay for capabilities, not for the privilege of being trapped. Cursor Dynamically, Cursor’s $2 billion revenue run rate suggests they’re doing something right on product. It doesn’t mean they’ll be the right choice for your team in 2028.

The Verdict: Canonical Source of Truth with Thin Adapters

Teams should adopt AGENTS.md as the canonical source of truth and treat all other config files as thin pointer files. The instruction budget is too scarce to maintain parallel rule sets, and deterministic ambient context loading consistently outperforms agent-invoked modular skills.

The layered architecture looks like this in practice:

1. AGENTS.md at root: Universal, minimal, non-inferable project details. Load this into every tool.
2. .cursor/rules/*.mdc: Only Cursor-specific scoping and activation patterns. Keep it under 50 lines.
3. CLAUDE.md or .claude/: Only permission hooks and Claude Code-specific features. One-line pointer to AGENTS.md plus overrides.
4. Skills/SKILL.md: Reusable workflows, but only if you’ve validated they fire reliably in your specific use case. Default to skepticism.

The contradiction at the heart of this ecosystem is that AGENTS.md is promoted as the universal standard, yet it is technically less capable than tool-specific alternatives. It has no built-in permission model, no glob-scoped activation, no hooks, and no @import syntax. The evidence for adoption is its 60,000+ repository footprint and Linux Foundation governance. The evidence against is every feature comparison table where it comes up short.

Similarly, Skills are positioned as the advanced workflow layer, but empirical evidence shows they underperform simple ambient context. The industry narrative says layer them on top. Vercel’s numbers say think twice.

Your move: audit your current config files against the instruction budget. Count lines. Test whether your Skills actually fire. Measure whether your context file improves outcomes or just makes you feel prepared. The tools that win long-term integrate transparently into existing workflows rather than demanding workflow rewrites—and AGENTS.md, for all its limitations, is the only format that currently does that across the ecosystem.

If you’re managing large projects with complex rule needs, our guide on best Cursor Rules for large projects explores how scoped, composable rule files can cut token costs and improve agent coherence without sacrificing the cross-tool baseline that AGENTS.md provides.