Cursor Rules in 2026: Stop Architectural Drift in Big Repos

Your AI coding agent just shipped a fifth way to fetch a user. Three services go through the repository layer, one calls Prisma directly because the agent assumed it was installed, and the newest file imports a helper from a folder nobody owns. Nothing failed a test. The diff looked fine. The architecture quietly bent, and nobody signed off on it.

That is the real failure mode of AI-assisted work on a complex repository. Not dramatic hallucinations about APIs that do not exist, though those happen too. It is drift: hundreds of plausible small edits that each ignore how your project decided to do things. Cursor's rules system is the primary lever for stopping that drift, and it changed shape enough over the past year that a lot of advice you will find online now points at the wrong file.

The .cursorrules file in your project root is a legacy artifact. If you are optimizing context for a serious codebase in 2026, you want Project Rules in .cursor/rules, written like internal documentation rather than a magic prompt. Here is how the current system works, which rule patterns genuinely prevent drift, and where rules run out of power. Cursor's official rules documentation covers the mechanics in full.

How rules work in Cursor's current architecture

At the model level, the mechanism is simple. Cursor has no memory between sessions, so when a rule applies, its text is included at the start of the model's context for that request. That is the entire trick: rules are persistent instructions injected into the prompt. It is also why vague rules produce vague behavior, and why the discipline here is the same as context engineering anywhere else.

Cursor currently supports four types of rules:

• Project Rules live in .cursor/rules in your repository and are version-controlled with the code. They are .mdc files, meaning markdown plus a small frontmatter block, and they are where almost all of your effort should go.
• User Rules are global to your Cursor account and apply across every project. Good for personal style preferences, the wrong home for anything repo-specific.
• Team Rules are managed from the Cursor dashboard on Team and Enterprise plans and sync automatically to every member. They can be enforced so nobody quietly switches them off, and when rules conflict, precedence runs Team over Project over User.
• AGENTS.md is a plain markdown file in the project root, following a convention that is spreading across coding agents. No frontmatter, no scoping, just instructions, and Cursor picks it up automatically. It is the right choice for simple projects; when you need conditional or glob-scoped rules, .cursor/rules is the stronger tool.

One trap catches people constantly: a plain .md file dropped into .cursor/rules is ignored. The rules system requires the .mdc extension because it reads frontmatter to decide when the rule applies. Developers add api-guidelines.md, see no change in behavior, and blame the model.

Anatomy of a rule: four application modes

Every project rule is markdown with up to three frontmatter fields: description, globs, and alwaysApply. How you set them determines when the rule loads, which Cursor presents as four modes:

Choose deliberately. An always-apply rule rides along in every conversation, which makes it expensive: it spends tokens and attention on every single request. Glob-scoped rules are the workhorse on large repos because they fire only when the agent is actually touching relevant files. A few patterns worth copying:

• src/**/*.tsx matches every component anywhere under src/
• *.ts matches TypeScript files at the repo root only
• docs/**/*.md, docs/**/*.mdx scopes docs conventions, with comma-separated patterns
• tailwind.config.* matches any extension of that filename

A scope limitation worth knowing before you rely on a rule: rules apply to Agent and Chat only. Tab completion, Inline Edit, and Bugbot PR reviews do not see them. If the guardrail is important, do not assume autocomplete is protected by it.

Rule patterns that actually prevent drift

Cursor's own best-practice guidance is sensible: keep each rule under 500 lines, split large rules into focused files, reference real files with @filename so the agent can verify instead of guessing, and start small, adding a rule when the same mistake appears more than once. The principle underneath: write rules like clear internal docs for a competent new engineer, because that is what the model is.

Three patterns do most of the drift-prevention work.

Pattern 1: hard boundaries, always applied. For rules that define your architecture, create one always-apply rule with boundaries and, crucially, pointers to where the right thing lives:

---
alwaysApply: true
---
- All database access goes through files in src/db/repositories/. Read the closest existing repository before writing a new one.
- Never add a dependency without asking. Check package.json before assuming a library exists.
- Do not create new files in src/utils. Put helpers in the module that owns them.
- When unsure how something is implemented, read the source before proposing changes.

A prohibition alone is weak. "Never call the database directly" leaves the agent to invent an alternative. Pair every "never" with the sanctioned path and the rule becomes executable.

Pattern 2: conventions scoped by glob. Framework-specific and test conventions belong in glob-scoped rules so they load only when relevant:

---
globs: src/**/*.test.ts
alwaysApply: false
---
- Use the test harness in tests/setup.ts. Do not import the test framework directly.
- Follow the existing naming pattern: <feature>.test.ts, colocated with the module under test.
- Prefer fixing a flaky test over deleting it. Ask before removing test coverage.

This keeps context lean on a big monorepo. The agent never sees test policy while it is refactoring a build script, and it never guesses your test framework mid-session.

Pattern 3: read-first rules for hallucination control. The cheapest defense against invented APIs is forcing the agent to read before it writes:

---
alwaysApply: true
---
- Before using any imported symbol, open the file that defines it and confirm the signature. If it does not exist, say so. Do not invent it.
- Never edit anything under dist/ or build/. These directories are generated.

Hallucinated imports usually come from the model pattern-matching on a familiar stack instead of reading your code. If you want to understand why models do this even mid-task, the mechanics of AI hallucination are worth a read.

You do not have to hand-write the first draft either. Type /create-rule in the chat, describe the rule in one sentence, and Cursor generates the .mdc file with proper frontmatter and saves it into .cursor/rules. Then treat it like code: review it in a pull request. An agent following a wrong rule is confidently, consistently wrong, and your whole team inherits the mistake.

How have rules changed for an agent-native IDE?

Two shifts changed how much rules matter and how you should write them.

First, the agent gathers its own context now. Cursor 2.0, released at the end of October 2025, introduced Composer, a coding model trained with codebase-wide semantic search, plus a multi-agent interface that runs many agents in parallel, using git worktrees or remote machines so they do not interfere with one another. The consequence: rules that tell the agent where to look matter less, because it is genuinely good at looking. Rules that define what is allowed, what the conventions are, and what must never happen matter more. In a multi-agent session your rules apply across every parallel thread, so vague scope gets amplified across every parallel agent instead of smoothed over in one conversation.

Second, rules became a team and ecosystem surface:

• Team Rules are created, enforced, and audited from the dashboard, so platform decisions no longer depend on every developer copying a file.
• Shared rulesets travel as plugins: package the rules in a repository with a .cursor-plugin/marketplace.json, import it in Customize with From GitHub Repository, and install the plugin. Cursor's docs say rules aren't imported on their own.
• AGENTS.md support keeps your core instructions portable across coding agents rather than locked to one tool, and CLAUDE.md files are always applied for compatibility with projects that also use Claude Code.
• /create-rule lowers the friction of capturing a rule the moment you catch a mistake.

If you are layering more autonomous workflows on top of the agent, the same rule discipline carries over to Cursor automations: every scheduled or triggered run reads the same project rules, so a stale rule goes wrong on a schedule.

And if you still have a legacy .cursorrules file, Cursor's help page says it "is legacy and will be deprecated", so migrate it. The official migration is four steps: create a new rule from the command palette, paste in the old content, set it to Always Apply to match the old behavior, and delete the file from the repo root. Your rules become reviewable, composable, and scoped, which the old single-file format never allowed.

What rules cannot fix

Be honest about the failure surface.

Rules are guidance, not enforcement. They are prompt text. A strong model follows good rules most of the time, but an enforced Team Rule only means a member cannot toggle it off, not that generated code cannot violate it. No rule replaces reviewing a large diff.

Rules do not fix a bad codebase map. If the repository contains four competing data-access patterns, a rule saying "always use the repository layer" describes an architecture that does not exist yet. The agent reads the actual code, notices the dominant pattern, and follows the code over the rule more often than you would like. Clean up the codebase first, or write rules that describe reality plus one step forward.

More always-apply rules is not more control. Every always-on rule spends tokens and attention on every request. Twelve always-apply rules dilute each other; three sharp ones plus scoped rules beat a 600-line manifesto.

Rules have a blast radius. They shape Agent and Chat, nothing else. Autocomplete and inline edits run without them, which matters when you are counting on a rule as a safety net.

When rules matter most

The leverage scales with three things: repository size, team size, and agent autonomy.

For a solo weekend project, a short AGENTS.md is genuinely enough. For a layered monorepo where multiple developers prompt against shared code, a curated .cursor/rules folder is one of the highest-leverage files in the repository, because it turns conventions that lived in one senior engineer's head into version-controlled, always-on context. Rules matter most when agents run long or in parallel and nobody reads every edit, which is precisely when architecture is cheapest to bend. The drift you prevent is invisible by definition. You will never see the five-way repository split that never happened.

Start this week with one always-apply rule of three to five lines that names your sanctioned data-access path, then add a glob-scoped rule each time you catch the same mistake twice.