AgentdexBlog · · Agentdex Editorial
Cursor Rules: How to Write Rules That Actually Work (2026)
Cursor (Agentdex profile) rules are saved instructions-stored as .mdc files in .cursor/rules-that tell Cursor AI how to generate code the way you actually want it. Get them right and your AI assistant follows your coding standards, handles errors properly, and stops making the same mistakes. Get them wrong (or skip them) and you're manually fixing the same output every session.
Key Takeaways
According to the Cursor docs, Cursor supports four kinds of rules: Project rules (.mdc files in .cursor/rules/), User rules, Team rules, and AGENTS.md. Project rules are the main way to share conventions with a repo.
Good rules focus on how to build (patterns, error handling, code style), not what feature to build.
One simple layout we suggest: two small always-on rules, a handful of glob-scoped domain rules, and a couple of manually invoked cross-cutting rules. It's a starting point, not an official Cursor standard.
Keep rules concrete: specify paths, frameworks, naming conventions, and deployment details. Update them whenever the AI makes recurring mistakes.
The older single .cursorrules file is a legacy format. Current Cursor docs focus on .cursor/rules and AGENTS.md, so migrate legacy rules to .mdc files.
What Are Cursor Rules in 2026, Really?
Cursor rules are persistent, reusable context for AI interactions. They're project-level instructions-saved as .mdc files inside .cursor/rules/-that get auto-injected into every Cursor AI prompt so the coding agent follows your coding standards, project structure, and preferred libraries without you repeating yourself.
There are four kinds of rules to understand. "User rules" are preferences you set in Cursor's settings that apply across all your projects. "Project rules" are the .mdc files in your repo's .cursor/rules/ directory, with frontmatter metadata for scoping. "Team rules" are managed by admins in the Cursor dashboard. And AGENTS.md is a plain markdown file of instructions in your project that Cursor also reads. The old single .cursorrules file at your repo root is a legacy format; current docs no longer cover it, so treat it as something to migrate away from.
Why do rules exist at all? Because large language models like the ones powering Cursor and Claude Code (Agentdex profile) have no persistent memory across completions. Rules provide persistent context that acts as a portable brain for your codebase. Without them, every new chat or completion starts from zero knowledge of your conventions.
Better rule files usually mean fewer manual corrections, more consistent architecture, and code that matches the project's existing patterns.
How Do Global Rules, Project Rules, and .cursorrules Compare?
Choosing the right rule type depends on scope. User rules apply globally across all projects in Cursor, while project specific rules live with your repo. Here's how they stack up as of October 2026:
Aspect | User Rules | Project Rules (.mdc) | Legacy .cursorrules |
|---|---|---|---|
Scope & lifetime | All projects, always active | Scoped to project; can be always-on, glob-scoped, or manual | Legacy; migrate to .mdc |
File / location | Cursor settings (not file-based) | .cursor/rules/*.mdc in repo | Single file at project root |
Best for | Personal preferences, universal style guidelines | Team-shared coding standards, stack-specific patterns | Older projects only |
Typical content | Code style, naming conventions, general error handling preferences | Framework rules, folder structure enforcement, testing patterns, security | Mixed bag-often becomes a dumping ground |
Version control & team sharing | Syncs per user account; not version controlled | Fully version controlled using Git; reviewable in PRs | Version controlled but lacks metadata; no globs |
Project rules use the .mdc extension; plain .md files placed in .cursor/rules/ are ignored. The official Cursor docs describe .cursor/rules/ as the place for project rules, and .mdc gives you descriptions, globs, and activation control that a single legacy file can't match.
Team rules enforce coding standards across an organization. They're managed in the Cursor dashboard and apply to team members, taking precedence over project and user rules. For current plan features and pricing, check Cursor's pricing page.
How Should You Structure Project Rules (.cursor/rules) for Real Work?
Project rules enhance AI editor behavior with specific guidance, but structure matters more than volume. A bloated, monolithic always-on rule eats context on every request and dilutes its own instructions.
One layout that works well (our suggestion, not an official Cursor standard):
2 Always-on rules: 01-project-overview.mdc (mission, tech stack, project structure) and 02-global-code-style.mdc (naming conventions, commit standards, universal patterns). Set alwaysApply: true.
A handful of glob-scoped domain rules: for example frontend.react-ts.mdc, backend.api.mdc, and database.mdc, each scoped via globs to the relevant directories.
A couple of optional cross-cutting rules: security checklists, new-feature templates, or migration guides, invoked manually with @ruleName.
Each .mdc rule includes frontmatter (description, globs, alwaysApply) plus a focused body. Cursor's rule types are Always Apply, Apply Intelligently (based on the description), Apply to Specific Files (globs), and Apply Manually (@-mention). Cursor recommends keeping rules under 500 lines; keep always-on rules especially compact and push framework-specific details into glob-scoped files.
What Makes a "Good" Cursor Rule vs a Bad One?
A common failure pattern across tools: vague rules like "write clean, scalable code" change nothing. The AI already tries to write good code. What it needs is your specific definition of good code.
Good rules are focused, actionable, and scoped. They share these traits:
Concrete and testable: "Use early returns; avoid nested conditionals beyond two levels" beats "keep functions simple."
Written as imperatives: "Do X / Don't do Y" format. The cursor agent responds best to direct commands.
Scoped per stack or directory: A react typescript rule shouldn't contain Python linting preferences.
Aligned with existing coding standards: Rules encourage modular, reusable code to minimize duplication and enforce consistent naming conventions for better maintainability.
Explicitly forbidding AI tendencies: "Do not introduce new dependencies without asking." "Do not use enums-use const objects instead." "Avoid prop drilling; use context or state management patterns."
Maintain your rules in git like code: PRs, reviews, and short commit messages. When you write rules this way, you create a complete guide your AI assistant can actually follow.
How Do You Capture Code Style, Code Quality, and Error Handling in Rules?
This section is your checklist for turning actual coding standards into enforceable Cursor rules.
Code style matters. Encode naming conventions (isLoading, hasError), directory naming (auth/login-form.tsx), and lint preferences. For typescript development, enforce strict configuration. Cursor rules emphasize consistent naming conventions across projects, so spell them out: PascalCase for functional components, camelCase for functions, UPPER_SNAKE for constants. Include commit message standards (Conventional Commits).
Code quality expectations. Define what code organization looks like: small pure functions, functional programming over heavy OOP where the language allows, DRY and SOLID principles. Rules that enforce type safety, such as "Use TypeScript for all code; prefer interfaces over types," are concrete enough to follow.
Error handling is where rules pay for themselves. Error handling is prioritized with early returns in functions. Handle errors early using guard clauses for readability. Specify typed error objects with code, message, and details fields. Define where to log versus where to surface messages to users. Cover edge cases explicitly.
Testing gates. Testing is mandatory, with emphasis on automated tests. Ensure all tests pass before merging code changes. State this in your always-on rules so the AI never skips verification.
Database-specific rules deserve their own .mdc file. For backend work, a database rule can encode things like: use parameterized queries only, never build SQL by string concatenation, keep migrations backward compatible, and prefer set-based operations over row-by-row loops.
That's how specialized a rule file can and should get.
How Do You Use Cursor Rules Across Different Stacks and Tools?
One of the biggest wins is scoping rules by framework or "zone" using glob patterns. This is a powerful way to keep context relevant and prevent the AI from applying React patterns to your Go backend.
Example stack-specific rule files:
frontend.react-ts.mdc - globs: ["frontend/**/*.tsx"] - enforces functional components, react query for data fetching, tailwind css utility classes, optimistic updates patterns
backend.api.mdc - globs: ["backend/**/*.ts"] - REST validation, access control patterns, typed error payloads
database.mdc - globs: ["backend/db/**/*.py"] - ORM patterns, migration safety, parameterized queries
infra.mdc - globs: ["infra/**/*"] - deployment constraints, environment variables, secrets handling
Attach rules to file globs in frontmatter so Cursor only pulls relevant context. This keeps the prompt level lean and the AI focused.
Stack-specific rules are especially valuable for things like browser extensions, Tauri desktop apps, or GPU pipelines where subtle security and performance details matter. Start from templates but trim aggressively. Every line in a rule file should earn its place.
How Do You Actually Create and Maintain Cursor Rule Files?
Here's the hands-on path from blank repo to working project rules in under an hour.
To create rules: In Cursor, type /create-rule in chat or go to Customize > Rules, or manually create .cursor/rules/<name>.mdc with frontmatter. Commit to git. Done.
The legacy path: Older projects may have a single .cursorrules file at the project root. It lacks glob-scoped metadata and tends to become one file trying to do everything, so migrate it.
Maintenance loop: Whenever Cursor misunderstands a pattern, add or adjust a rule. When frameworks change (Next.js 14 → 15, React 18 → 19), run a rules review as part of the upgrade. Well-scoped rules reduce repeated manual editing in code, but only if they stay current.
Migration from legacy: Locate your .cursorrules file, create a new always-on .mdc rule, copy the content in with proper frontmatter, split stack-specific parts into glob-scoped rules, commit, then delete the old file. See the Cursor rules docs for the current format.
Keep rules in your repo so they clone with the project and survive machine failures. Shared rules keep AI assistance aligned across contributors.
How Can Cursor Rules Coordinate Multiple AI Tools (Cursor, Claude Code, etc.)?
Many devs in 2026 bounce between Cursor, Claude Code, web-based assistants, and CLI agents. Consistent behavior across tools is the goal.
Store canonical project rules in .cursor/rules/ and reuse the same text in other tools' instruction files where possible. The parts that transfer well across tools: documented patterns, code style, error handling guidelines, and data validation rules. What's Cursor-specific: .mdc frontmatter, glob behavior, and alwaysApply flags.
A practical pattern is an AGENTS.md file at the root summarizing cross-tool conventions (Cursor reads it, and so do several other agents), with Cursor's .mdc files adding richer scoping for in-editor work. Claude Code reads CLAUDE.md instead; our guide to writing agent rules for Cursor and Claude Code covers both.
Features and model options change fast. Check each tool's official docs for updated support of rule-like configuration as of late 2026.
What Are Advanced Patterns and "Other Rules" Power Users Use?
Once your basics are working, here are patterns to push further.
Cross-cutting rules for security (auth, access control, secrets management), performance budgets, and feature checklists for new endpoints. These work as manual-invoke rules so they don't bloat every session.
Environment-specific patterns: Different mdc files for production versus prototype folders, where strict code quality is relaxed in experimental directories. Use globs like ["experiments/**/*"] to scope.
Niche technologies: Community-shared rules cover everything from DynamoDB single-table design to integration testing for complex microservices. Highly specialized project rules tend to be the most useful, because they encode knowledge the model wouldn't guess.
Build a small internal rules directory where your team curates battle-tested .mdc files for reuse across projects.
How Do You Know If Your Cursor Rules Are Working?
Feedback loops matter. Measuring rule effectiveness is the difference between noisy prompts and a real AI assistant that retains memory of your conventions.
Practical signals to track:
Fewer manual fixes per AI-generated change
Reduced lint/test failures from AI edits
More consistent architecture patterns across PRs
Fewer security or performance regressions traced to AI-generated code
Team rituals that help: Tag rule-related changes in PR descriptions. Run periodic "AI retro" meetings where devs log recurring AI mistakes and convert them into rule updates. Rules provide persistent, reusable context for AI-but only if you iterate on them.
Rules are often the biggest lever devs actually control when generating code with any tool.
How Can You Tell Whether Your Cursor Rules Are Working?
Run a simple before-and-after check on your own project.
Pick a few repeatable tasks (add a small feature, fix a bug, write a test) and run them with and without your tuned rules. Track how many manual fixes you needed, lint and test failures, and whether the output followed your conventions.
For current Cursor features and pricing, go to Cursor's official website.
Want to stay current on AI coding tools and rule patterns? Join the free Model Pulse newsletter at agentdex.app/newsletter for daily model drops and tool news.
FAQ
Do I still need a .cursorrules file if I'm using .cursor/rules .mdc files?
Generally, no. The .cursor/rules/ directory with .mdc files is the current, more flexible approach, and Cursor's docs no longer document the legacy file. Keeping both can cause duplicated or conflicting instructions, so migrate your .cursorrules contents into one or more .mdc files, verify behavior, then delete the old file.
How big is "too big" for a Cursor rule file?
There's no strict public character limit, but monolithic rules spanning thousands of words reduce adherence and eat context. The Cursor documentation recommends keeping rules under 500 lines. Keep always-on files compact and push stack-specific details into glob-scoped rules. If a rule file covers multiple languages or frameworks, split it into smaller, focused .mdc files.
Can I use Cursor Rules for non-code tasks like documentation or marketing copy?
Yes. Cursor's rule system can scope behavior for any file types it opens-including docs, Markdown, or config files. You might create rules for MkDocs-based Kubernetes documentation, API reference style guidelines, or product changelog formatting. The key: keep rules specific. Define tone, structure, and required sections rather than vague instructions like "write clear documentation."
How do Cursor Rules interact with team or org-wide policies?
On Team and Enterprise plans, admins can define team rules in Cursor's dashboard. Per the Cursor docs, precedence is Team rules, then Project rules, then User rules. Align your local .cursor/rules/ files with the policies your security, compliance, or architecture teams define. Note that rules apply to Agent chat, not to Cursor Tab or Inline Edit.
What's the best next step if my rules "aren't working" yet?
Start by pruning. Remove vague or conflicting instructions and keep just two or three core patterns per file. Then run a single real task (adding a feature or fixing a bug) and observe where the AI deviates. Encode those corrections back into the rules. Our Cursor & Claude Code agent rules pack has ready-made templates.
Written by Agentdex Editorial. Agentdex is an independent directory reviewing AI coding tools; we are not affiliated with the companies mentioned. Prices and features are as of October 23, 2026, from official sources linked above. Always confirm on the vendor's site.