What are .cursorrules and .cursorignore? (steering Cursor)

What it actually is

These are two different files that both fall under “telling Cursor how to behave,” which is why people lump them together.

.cursorrules used to be a single file at your project root where you wrote instructions for Cursor’s AI: which framework you use, how you like things named, what to never touch. It was Cursor’s version of CLAUDE.md. That format is legacy now: Cursor’s current documentation doesn’t mention .cursorrules at all. The supported way to steer the agent today is Project Rules, separate .mdc files living inside a .cursor/rules folder, each with its own scope.

.cursorignore does something else entirely. It tells Cursor which files and folders to keep out of what the AI can see, search, and pull in through @-mentions. Think of it as the same idea as .gitignore, but instead of keeping files out of your version history, it keeps them out of the AI’s context.

A way to hold both in your head at once: Project Rules (what used to be .cursorrules) is the induction binder you’d hand a new hire, here’s how we build things here. .cursorignore is the “staff only” sign on a door, this room isn’t part of the tour.

Why your AI just did this

If you pasted an old .cursorrules file into a new Cursor project and Agent mode seems to ignore half of it, that’s a real, widely reported behavior: .cursorrules gets deprioritized because Cursor moved on to Project Rules. If your agent instead created a .cursor/rules folder with .mdc files, each starting with a small block of description, globs, and alwaysApply, that’s it following the current structure: one rule can apply only to files matching *.tsx, another to every request, another only when you @-mention it by name.

If your agent added lines to .cursorignore, it’s usually keeping something out of context: a huge dist folder wasting tokens, a folder of client data, files you don’t want it editing. Worth knowing up front: .cursorignore is best-effort, not a lock. Cursor’s own docs say the terminal and MCP tools Agent uses can still reach files listed there, so it isn’t where you hide a real secret.

When you’ll run into it

• A tutorial or forum post says “just add a .cursorrules file”, but your rules don’t seem to apply once you’re in Agent mode.
• You inherit a project with a .cursor/rules folder full of .mdc files and don’t recognize what alwaysApply: true or a globs line is doing.
• You expect .cursorignore to hide your .env file or API keys from the AI entirely, but a terminal command or an MCP tool call still reaches them.
• node_modules, lockfiles, and media files never show up in AI context even though you never wrote a .cursorignore, because Cursor excludes common folders like that by default.
• You want files left out of search results but still usable by the AI when it needs them; that’s .cursorindexingignore, a narrower, separate file, not .cursorignore.

What to check

• If you’re starting fresh, write your instructions as .mdc files in .cursor/rules, not a single .cursorrules file
• Give each rule file a description, and a globs pattern if it should only fire on certain files; reserve alwaysApply: true for rules that truly belong in every request
• Don’t rely on .cursorignore to protect real secrets; keep those in environment variables and out of the repo entirely
• Check what .gitignore already excludes; Cursor respects it automatically, so .cursorignore only needs to cover AI-specific exclusions on top of that
• If a file still leaks into context despite .cursorignore, check whether a parent folder is what’s actually listed; you can’t re-include one file inside an already-excluded folder

Say it like a dev

Instead of: “put our coding rules in that old file” Say: “let’s write Project Rules as .mdc files in .cursor/rules, that’s the supported format now”

Instead of: “hide this folder from the AI completely” Say: “add it to .cursorignore, but that’s best-effort, not a hard boundary”

Instead of: “why isn’t Cursor following my instructions anymore” Say: “is this still sitting in the old .cursorrules file? Agent mode doesn’t reliably read that anymore”