AGENTS.md vs CLAUDE.md vs Cursor Rules: Agent Config Done Right

HumanLayer ran Claude Code on a 1M-token context window and then deliberately went back to a smaller one, citing "dramatically degraded" instruction adherence at full context, according to their March 2026 write-up. The same team's guide to writing a good CLAUDE.md puts a number on the ceiling: frontier LLMs reliably follow roughly 150 to 200 instructions, and Claude Code's system prompt already burns about 50 of them.

That leaves you maybe 100 to 150 instructions of real budget. Every line of your AGENTS.md, CLAUDE.md, and .cursor/rules files spends from that budget, every single turn.

So agent configuration is not documentation. It's a control plane with a hard resource constraint, and the three dominant formats spend that budget very differently.

Here's the one-line answer to the core question: AGENTS.md is the vendor-neutral standard every major agent reads, CLAUDE.md is Claude Code's native memory file with enforceable permissions in settings.json, and .cursor/rules/*.mdc gives Cursor glob-scoped rule activation. They are complementary layers, not competitors.

TL;DR: Author AGENTS.md as your canonical agent config and keep CLAUDE.md and .cursor/rules as thin adapters that re-export it with tool-specific features. Enforce the three-tier permission model (allow / ask / deny) in.claude/settings.json, not in prose. And push durable state into files likefeature_list.jsonandclaude-progress.txt, because chat history is the most expensive and least reliable place to store anything.

Key takeaways

• AGENTS.md became a Linux Foundation-hosted standard under the Agentic AI Foundation, with implementations across Codex, Copilot, Cursor, Devin, and others.
• Only Claude Code and Cursor enforce permissions first-party. AGENTS.md prose is advisory unless the consuming tool backs it with a runtime hook.
• The instruction-count ceiling (~150-200, per HumanLayer) makes a short root file plus imports the only sane architecture.
• Chroma's context-rot study of 18 frontier models across 194,480 API calls showed uniform degradation as input grows. Long context doesn't save a bloated config.
• The "canonical AGENTS.md plus thin adapters" pattern is the mid-2026 default for teams running more than one agent.

Who owns what: the three formats at a glance

AGENTS.md describes itself as "a README for agents." It was donated to the Agentic AI Foundation by OpenAI in late 2025 alongside MCP, and the spec is deliberately minimal: free-form Markdown, any directory level, closest file wins. Codex, GitLab Duo, and Devin all document first-party support.

CLAUDE.md is Anthropic's auto-loaded memory file. The docs are blunt about the budget problem: "Memory files are loaded into context at the start of every conversation. Keep them focused: link to detail files rather than inlining."

Cursor rules are the most structured of the three. Each.mdcfile carries YAML frontmatter (description,globs,alwaysApply) and gets injected when its activation condition fires.

How does the three-tier permission model actually work?

The pattern is the same everywhere: an agent shouldn't pester you for safe, reversible actions, should pause for risky ones, and should never run blacklisted ones. The three formats implement it with wildly different teeth.

Claude Code: the most expressive model

Claude Code's permissions live in .claude/settings.json, not in CLAUDE.md itself. Rules useTool(specifier)patterns with prefix matching, soBash(npm run:*)permitsnpm run testbut notnpm install:

{
  "permissions": {
    "allow": ["Bash(pnpm test:*)", "Edit(./src/**)"],
    "ask":   ["Bash(git push:*)", "Bash(rm:*)"],
    "deny":  ["Bash(sudo:*)", "Read(./.env)", "Read(./secrets/**)"]
  }
}

This is the only format of the three where "never read .env" is enforced by the harness rather than requested of the model. That distinction is everything. A model under context pressure will eventually ignore a prose rule. It cannot ignore a denied tool call.

Cursor: precision through activation modes

Cursor inverts the model. Instead of one global allow/ask/deny list, each rule activates independently:alwaysApply: trueinjects on every chat,globs:injects when matching files are touched, manual rules load only when attached, and agent-requested rules load on demand, per the Cursor docs. A per-rule ask/never toggle covers edit semantics for the globbed files.

The cost is sprawl. A 30-rule project means 30.mdcfiles, and stale globs fail silently: the rule simply never loads, and nobody notices until the agent violates it.

AGENTS.md: portable but toothless

AGENTS.md defines no permission fields at all. You write "never runrm -rf" as prose and hope the consuming tool's own enforcement layer agrees. Maximum portability, minimum enforcement.

That's not a flaw, exactly. It's a deliberate scoping decision. But it means AGENTS.md alone is insufficient for any project where the agent has shell access.

Context window management: why your config is rotting

Chroma's context-rot research tested 18 frontier models across 194,480 API calls and found performance degrades non-uniformly as input length grows, even on tasks the model handles perfectly at short lengths. "LLMs are typically presumed to process context uniformly," the study notes. "In practice, this assumption does not hold."

Combine that with the instruction ceiling and you get the core engineering rule of agent configuration: the root file must be small, and everything else must load lazily.

HumanLayer keeps their root CLAUDE.md under 60 lines, roughly 1k tokens. Anthropic's best-practices guidance says the same thing: keep the memory file focused, point to detail via@import, and put toolchain versions (Node, package manager, Python) up front so the agent uses the right tools on turn one.

Each format gives you a lazy-loading primitive. Use it.

Cursor's glob-gated rules are the cleanest version of this. Atesting.mdcscoped totests/**costs zero tokens until the agent touches a test file. Claude Code's sub-agents go further: each runs "in its own context window with its own system prompt," so a database-migration specialist never pays for your frontend conventions.

Why files beat chat history

Anthropic's harness engineering post and the autonomous-coding quickstart converge on a pattern: wrap long-running work in a deterministic loop of a feature list, a progress log, a test gate, and a review gate, each backed by a file or script the agent must use.

Two artifacts carry the state.feature_list.jsonis a JSON task graph withid,priority,status, andacceptancefields; the agent reads it on session start and picks the highest-priority pending item.claude-progress.txtis an append-only log, one line per work session, so a fresh agent can read the last 50 lines and know what's in progress and what's blocked without re-deriving it from anything.

The reasoning is structural, not aesthetic. Chat history doesn't survive a session restart or a model switch, isn't version-controlled, can't be shared across parallel agents, and grows unbounded in token cost. A file is bounded, queryable, and diffable. This is also why permissions belong in settings.json rather than in a chat message asking nicely.

The same logic produces the script trio seen across community harnesses like everything-claude-code:init.shmakes the environment reproducible,test-all.shmakes correctness a single checkable gate, andreview.shmakes merging safe. None is mandated by Anthropic, but all three exist because "remember to run typecheck" is exactly the kind of instruction that falls out of a rotted context.

The pattern that wins: canonical AGENTS.md, thin adapters

The mid-2026 consensus, visible in the AgentLint pattern and three-way comparisons, is to stop choosing.

Author AGENTS.md as the single canonical document: stack versions, build commands, testing rules, code style, and boundaries, in plain Markdown every tool can read. Then write two thin adapters.

Your CLAUDE.md becomes mostly a pointer: "Read./AGENTS.mdfirst. It is the canonical source," followed only by Claude-specific machinery (session-start steps, the settings.json reference, sub-agent locations). Your.cursor/rules/directory holds a couple of.mdcfiles that re-state the canonical content with Cursor-native globs.

Duplication is the obvious objection, and the answer is to duplicate pointers, not content. The one place where duplication is genuinely correct: testing rules. State the prose rule once in AGENTS.md ("run the suite before declaring work complete") and back it with a mechanicalBash(pnpm test:*)allow-rule in settings.json so the agent never even prompts for it.

What this means for you

Three moves, in priority order.

First, audit your root file's instruction count. If your CLAUDE.md or AGENTS.md is pushing past 60-ish lines of actual directives, you're spending adherence budget on instructions the model will drop. Cut, then move detail behind@import, nested files, or glob-gated rules.

Second, move every "never" out of prose and into enforcement. Anything currently phrased as "please don't" in Markdown belongs inpermissions.deny(Claude Code) or a never-toggled rule (Cursor). Prose boundaries in AGENTS.md are fine as documentation, but treat them as comments, not controls.

Third, externalize state before your next long-running task. Afeature_list.jsonand an append-only progress log cost twenty minutes to set up and eliminate the single worst failure mode of multi-session agent work: the fresh session that confidently re-does, or undoes, yesterday's work.

The teams getting the most out of coding agents in 2026 aren't the ones with the cleverest prompts. They're the ones who treat configuration as infrastructure: small, enforced, layered, and version-controlled.

Sources

• AGENTS.md official site
• How Claude remembers your project, Claude Code docs
• Configure permissions, Claude Code docs
• Best practices for Claude Code
• Create custom subagents, Claude Code docs
• Rules, Cursor docs
• Custom instructions with AGENTS.md, OpenAI Codex
• Effective harnesses for long-running agents, Anthropic
• Context Rot, Chroma Research
• Long-Context Isn't the Answer, HumanLayer
• Writing a good CLAUDE.md, HumanLayer
• Agentic AI Foundation
• anthropics/claude-quickstarts, GitHub
• How Claude Code works in large codebases, Claude blog
• Using CLAUDE.md and Cursor Rules Together, AgentLint