# Claude Code vs Cursor: AGENTS.md, CLAUDE.md and Cursor Rules Compared

> Claude Code now reads AGENTS.md, but only when there is no CLAUDE.md, and a personal CLAUDE.local.md quietly turns that off. How both tools load AGENTS.md, CLAUDE.md and Cursor rules, and how to keep one repo working in both.

By Tahir Nazir · Published 2026-08-09 · Updated 2026-10-12
Canonical: https://www.its-tahir.com/blog/claude-code-vs-cursor-context-management

**Yes, Claude Code reads `AGENTS.md` now. Since version 2.1.277 it loads your `AGENTS.md` when there is no `CLAUDE.md` in your working directory or above it. If a `CLAUDE.md` exists, it reads that instead, and even a personal `CLAUDE.local.md` switches the `AGENTS.md` fallback off. Cursor reads `AGENTS.md` natively, nested files included.**

*Updated 12 October 2026: Claude Code added built-in `AGENTS.md` support in 2.1.277, so the AGENTS.md section below is rewritten. When this post first went up in August, the only way was an import.*

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](/work/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

| | Claude Code | Cursor |
| --- | --- | --- |
| Project instructions | `./CLAUDE.md` or `./.claude/CLAUDE.md` | `.cursor/rules/*.mdc` |
| Personal, all projects | `~/.claude/CLAUDE.md` | User Rules, entered in the settings UI under Customize → Rules — no file on disk |
| Personal, one project | `./CLAUDE.local.md` (gitignored) | no documented equivalent |
| Org-wide | managed policy `CLAUDE.md`, or `claudeMd` in managed settings | Team Rules, authored in the Cursor dashboard (Team and Enterprise plans) |
| Modular split | `.claude/rules/*.md`, discovered recursively | one `.mdc` file per topic |
| Path scoping | `paths:` frontmatter glob list | "Apply to Specific Files" with a pattern |
| AGENTS.md | read when no `CLAUDE.md` exists (v2.1.277+); otherwise import it | read natively, including nested files |
| MCP config | `.mcp.json` / `~/.claude.json`, via `claude mcp add` | `.cursor/mcp.json` / `~/.cursor/mcp.json` |

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.

### Does Claude Code read AGENTS.md?

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 reads it too since **v2.1.277**, but as a fallback, not alongside `CLAUDE.md`. [Anthropic's memory docs](https://code.claude.com/docs/en/memory) spell out what loads by default:

| Your repo has | Claude Code reads |
| --- | --- |
| An `AGENTS.md`, and no `CLAUDE.md` or `CLAUDE.local.md` in your working directory or above it | Your `AGENTS.md` |
| An `AGENTS.md` and a `CLAUDE.md` or `CLAUDE.local.md` | Your `CLAUDE.md` files only |
| A `CLAUDE.md` that imports `AGENTS.md` | Your `CLAUDE.md`, with `AGENTS.md` pulled in by the import |

When the fallback kicks in, an interactive session tells you, with a line like `no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md`. Subdirectory `AGENTS.md` files load as Claude reads files there, as long as that subdirectory has no `CLAUDE.md` of its own. Your `~/.claude/CLAUDE.md`, your organization's managed `CLAUDE.md` and `.claude/rules/` files don't count for the check, and keep loading alongside `AGENTS.md`.

**The trap is `CLAUDE.local.md`.** It counts as a `CLAUDE.md` for that check. So in a team repo that relies on a shared `AGENTS.md`, adding a personal, gitignored `CLAUDE.local.md` for your own notes silently switches off the team's `AGENTS.md`, for you only. Everyone else is fine, which makes it a confusing one to debug.

To load both, open `/config` and set **Project instructions** to `claude-md-and-agents-md`. The options are:

| Value | What loads |
| --- | --- |
| `claude-md-or-agents-md` | `CLAUDE.md` files, or `AGENTS.md` when there's no `CLAUDE.md` (the default) |
| `claude-md-and-agents-md` | Both, each directory's `CLAUDE.md` first, then its `AGENTS.md` |
| `claude-md` | `CLAUDE.md` files only |
| `managed-only` | Only your organization's managed `CLAUDE.md` and auto memory at launch |

You can set the same thing in `~/.claude/settings.json`, or across a company through managed settings. It's ignored in a project's own settings file:

```json
{
  "pluginConfigs": {
    "cc-plugin-agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}
```

Before v2.1.285 the plugin ID was `agents-md@builtin`; later versions read either.

**The import still works, and it's the portable choice.** You get `CLAUDE.md` files only before v2.1.277, if someone disables the built-in plugin with `/plugin`, sometimes in the first session after an upgrade, and, before v2.1.281, in some sessions such as Amazon Bedrock or with telemetry off. A `CLAUDE.md` that imports `AGENTS.md` works in all of those:

```markdown
@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:

```bash
ln -s AGENTS.md CLAUDE.md
```

On Windows a symlink needs Administrator rights or Developer Mode, so the `@AGENTS.md` import is the safer cross-platform choice. An `AGENTS.md` that's already loaded is skipped, so an import plus the `claude-md-and-agents-md` setting won't load it twice.

### Path scoping works in both, with different syntax

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

```markdown
---
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:

```json
{
  "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. A RAG pipeline makes the same trade, choosing what enters context per request, and when it chooses badly you get [retrieval that returns the wrong chunks](/blog/rag-retrieval-returns-the-wrong-chunks).

## 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](/blog/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. If you have nothing Claude-specific, stop there: version 2.1.277+ reads it on its own. If you do, keep a `CLAUDE.md` that starts with `@AGENTS.md` and add the Claude-only notes below. That also covers older versions and anyone with a `CLAUDE.local.md`.
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.

If Claude Code is failing outright rather than ignoring instructions, [Claude Code not working? Every error and its fix](/blog/claude-code-troubleshooting) matches each error message to its fix.

## Sources

- [How Claude remembers your project: AGENTS.md — Claude Code Docs](https://code.claude.com/docs/en/memory)
- [Rules — Cursor Docs](https://cursor.com/docs/rules)
- [Connect Claude Code to tools via MCP](https://code.claude.com/docs/en/mcp)
- [Model Context Protocol — Cursor Docs](https://cursor.com/docs/mcp)
- [Hooks — Claude Code Docs](https://code.claude.com/docs/en/hooks)
- [Hooks — Cursor Docs](https://cursor.com/docs/hooks)