Claude Code vs Cursor: How Each One Decides What Your Agent Knows

The honest answer to "Claude Code vs Cursor" is that the model is not the differentiator any more — the context layer is. Both tools read instruction files from your repository before they touch your code, and they load them differently: Claude Code walks the directory tree and concatenates every CLAUDE.md it finds, while Cursor evaluates .mdc rule files that each declare their own activation mode. If your agent keeps ignoring a convention, that difference is usually why.

I maintain a tool in this space, so I'll declare the bias up front: ContextZero is a VS Code extension I built specifically because I got tired of tracking which agent reads which file in which order. What follows is the mechanics, not a verdict.

The core difference in one paragraph

Claude Code's model is hierarchical concatenation: everything discovered along the path from filesystem root down to your working directory gets loaded, in order, with the most specific file read last. Cursor's model is conditional activation: rules sit in .cursor/rules as .mdc files, and each one declares whether it applies always, when a file pattern matches, when the agent decides it is relevant, or only when you @-mention it.

Concatenation is predictable and expensive. Activation is cheap and occasionally surprising. Neither is wrong; they fail in opposite directions.

Where instructions live

Both tools do org-wide instructions, and both let an administrator make them non-negotiable. Cursor's Team Rules are written in the dashboard, apply "across all repositories and projects for that team," and carry an Enforce this rule toggle that stops a member disabling them in Customize. Precedence there is Team Rules → Project Rules → User Rules, merged, with the earlier source winning a conflict. Claude Code's equivalent is a managed-policy CLAUDE.md or a claudeMd entry in managed settings. If you were expecting one of these tools to be "the enterprise one," neither is.

Two rows in that table cause most of the real-world confusion.

AGENTS.md is where the tools actually diverge

Cursor reads AGENTS.md natively, and it reads nested ones: an AGENTS.md in any subdirectory applies automatically when the agent works with files in that directory, combined with parent directories, with more specific instructions winning.

Claude Code does not read AGENTS.md. Its docs say so plainly and give you the workaround — a CLAUDE.md that imports it:

@AGENTS.md
 
## Claude Code
 
Use plan mode for changes under `src/billing/`.

A symlink works too, if you don't need Claude-specific content on top:

ln -s AGENTS.md CLAUDE.md

On Windows a symlink needs Administrator rights or Developer Mode, so the @AGENTS.md import is the portable choice. This is my standing recommendation for any repo where people use both tools: keep the shared truth in AGENTS.md, and let CLAUDE.md be a thin wrapper plus whatever is genuinely Claude-specific.

Path scoping works in both, with different syntax

Claude Code scopes a rule with YAML frontmatter in .claude/rules/:

---
paths:
  - "src/api/**/*.ts"
---
 
# API Development Rules
 
- All API endpoints must include input validation
- Use the standard error response format

A rule without a paths field loads unconditionally. With one, it only enters context when Claude reads a matching file. Cursor's equivalent is the "Apply to Specific Files" rule type with a glob pattern, configured in the .mdc file's metadata.

The practical difference is the default. Claude Code's default is "always loaded" — you opt into scoping. Cursor gives you four modes up front and nudges you to pick. If you have ever wondered why a long CLAUDE.md stops being followed, this is the mechanism: Claude Code's docs recommend keeping each file under 200 lines because "longer files consume more context and reduce adherence."

Loading behaviour, and why it matters

Claude Code loads CLAUDE.md and CLAUDE.local.md files from the directory hierarchy above your working directory in full at launch. Files in subdirectories load on demand, when Claude reads a file in that directory. Within a directory, CLAUDE.local.md is appended after CLAUDE.md, so your personal notes are the last thing read at that level.

That has a consequence people hit after /compact: the project-root CLAUDE.md is re-read from disk and re-injected, but nested CLAUDE.md files and paths:-scoped rules are not. They reload the next time Claude touches a matching file. So an instruction that "disappeared" mid-session was probably nested or path-scoped, not lost.

Cursor's nested AGENTS.md behaves similarly in spirit — combined with parents, specific wins — but it is activation-driven rather than launch-time.

Monorepos expose the difference fastest

In a monorepo, Claude Code's walk-up behaviour means another team's CLAUDE.md two directories up lands in your context whether it is relevant or not. The escape hatch is a claudeMdExcludes glob list in settings:

{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

Cursor sidesteps this by default, because a rule that isn't activated isn't loaded. The trade is that you get less certainty about what was in context on any given turn.

MCP: same protocol, different registration

Both tools speak the Model Context Protocol, and both support stdio and streamable HTTP. The server you write works in both without modification — I walk through building one in How to build an MCP server.

Registration differs:

• Claude Code is CLI-first. claude mcp add --transport http notion https://mcp.notion.com/mcp, with --scope local | project | user deciding whether it lands in ~/.claude.json or a committed .mcp.json. claude mcp list then reports a live health status per server.
• Cursor is file-first. Write the entry into .cursor/mcp.json for the project or ~/.cursor/mcp.json for everywhere.

Claude Code additionally supports WebSocket servers for push-style connections, configured through claude mcp add-json, which Cursor's docs don't cover. And Claude Code's SSE transport is explicitly deprecated in favour of HTTP — if you're picking a transport for a new remote server today, pick streamable HTTP.

Which one should you use?

Use Cursor if you want conditional context with minimal upkeep and you live in the editor. The four activation modes mean a large rule library stays cheap, and native nested AGENTS.md support makes it the lower-friction choice in a polyglot monorepo.

Use Claude Code if you want the context that loaded to be predictable and inspectable. The hierarchy is explicit and /context tells you exactly which memory files are in play, so "why did it ignore that rule" is a question you can answer by looking rather than by guessing at an activation decision.

I used to put "hooks" in that column, and that was wrong. Both tools now ship a hook layer, and both treat it the same way: instruction files are context the model may or may not honour, hooks are code that runs whether it wants to or not. Cursor's live in <project>/.cursor/hooks.json or ~/.cursor/hooks.json and, in its own words, "let you observe, control, and extend the agent loop using custom scripts" — preToolUse, beforeShellExecution and beforeMCPExecution return allow, deny or ask, which is exactly what Claude Code's PreToolUse does. If your requirement is "the agent must never run this command," either tool covers it today.

Where they still differ is surface area, not existence:

• Reach. Cursor's events cover the agent loop plus Tab completions. Claude Code's reach further into the session itself — TaskCompleted, PermissionRequest, ConfigChange — so policies about how the session runs, not just which tools fire, have somewhere to live.
• Handler types. Cursor spawns scripts that talk JSON over stdio. Claude Code will also call an HTTP endpoint or an already-connected MCP tool.
• Scoping. Both layer configuration Enterprise → Team → Project → User, so neither is the "personal only" option any more.

That is a real difference, but it is a narrower one than a feature-comparison table would suggest, and it is not the thing most teams should decide on. Pick on the context model.

In practice a lot of repos end up with both tools in use, which is why the useful advice here is structural rather than a pick:

1. Put the shared, tool-agnostic truth in AGENTS.md.
2. Import it from CLAUDE.md with @AGENTS.md; add Claude-specific notes below the import.
3. Scope anything that only matters for part of the tree — paths: frontmatter in Claude Code, "Apply to Specific Files" in Cursor.
4. Keep each always-loaded file short. Under 200 lines is Claude Code's own guidance and it is a good bar for Cursor too.
5. Register MCP servers at project scope so the config is version-controlled, not in someone's home directory.

Do that and you stop maintaining two sources of truth, which is the actual cost of the comparison — not the model behind either tool.