Master Cursor Custom Rules to Align Gen AI with Your Code

Learn how to use Cursor Custom Rules to guide AI-assisted coding. Explore project rules, .mdc files, setup steps, practical use cases, and best practices.

Editor’s Note: This article was originally written by Ajinkya Vinayak Palaskar, Software Engineer III, and published in May 2025. It was revised and updated by Harrini in October 2026 to reflect the latest Cursor Custom Rules features, rule formats, configuration options, and AI-assisted development practices. The technical content was reviewed by Ajinkya Vinayak Palaskar, Software Engineer III.

Generative AI tools like Cursor are changing the way developers write code, but let’s be honest, the default AI behavior doesn’t always match how you or your team builds software. Whether it’s naming conventions, project structure, or the way you wire up API calls, out-of-the-box AI can feel like working with a junior dev who doesn’t quite get the vibe yet.

That’s where Cursor’s Custom Rules come in. Instead of adapting your codebase to fit AI’s suggestions, you can flip the script and make AI generate code that follows your standards, your structure, and your expectations.

In this blog, we’ll dive into what Cursor’s rules are, how they work, and how you can use them to bring structure, consistency, and actual team alignment to your AI-powered workflow. Just real, dev-focused examples that help you go from “AI that kind of helps” to “AI that codes like your best junior dev (who doesn’t forget lint rules).”

Understanding Cursor’s Custom Rules

At its core, Cursor’s Custom Rules feature gives developers a way to shape the behavior of the AI assistant so it actually respects your coding preferences. It’s not just about giving it tips; it’s about creating structured, repeatable rules that get applied every time you prompt it in certain files or folders.

Cursor supports two types of rules:

1. Project Rules: These are project-specific rules stored in .cursor/rules/ and committed to version control. They apply to everyone working in the repo, super useful for enforcing team-wide patterns, boilerplate structures, or naming conventions.
2. User Rules: These live locally and are scoped only to your Cursor environment. Think of them as your personal tweaks or power-ups for one-off or experimental cases. Cursor stores them in your user settings directory.

To sum it up: Project rules = team alignment. User rules = personal productivity boosts.

How Do These Rules Actually Work?

Cursor rules define instructions that guide an agent when it works on a project. Depending on how a rule is configured, it can be applied automatically based on the task, to specific files, or manually when selected.

Rules can include:

• Description: Explains what the rule is for.
• File patterns: Define which files the rule targets when using file-specific rules.
• Instructions: Tell an agent how to work with the code.
• File references: Add project context with references such as @src/lib/validators.ts.

Cursor supports four application modes: Always Apply, Apply Intelligently, Apply to Specific Files, and Apply Manually. This lets teams choose whether an instruction should be active everywhere, selected based on relevance, tied to particular files, or triggered explicitly.

One important distinction is that cursor rules guide the agent. They do not automatically apply to every AI feature in Cursor, such as tab completion or inline edit. Rules should therefore complement tests, linting, type checking, CI, and code review rather than replace them.

So instead of writing the same prompt over and over again, like "Please generate a Zod schema and name everything in camelCase," you just write the rule once, and Cursor applies it automatically in the right places.

What About AGENTS.md?

Cursor also supports AGENTS.md for project-level instructions. It can be useful when a project needs straightforward guidance without the more granular scoping available through .cursor/rules/*.mdc. For file-specific or manually triggered instructions, project rules provide more control.

Setting Up Custom Rules in Cursor

Now that we know what rules are and why they matter, let’s get into how to actually set them up. The cursor makes this surprisingly smooth. You don’t need any weird config voodoo, just a well-structured JSON file, a clear prompt, and you’re good to go.

The easiest way to get started is to use the built-in command:

To create a rule, open Customize → Rules → Add Rule in Cursor. Developers can also use /create-rule in Agent to create a rule from the current conversation. The command palette remains another way to access rule creation, with shortcuts varying by operating system.

This will prompt you for a name for the rule and create a markdown file at this location:

.cursor/rules/your-new-rule.mdc
Here’s what a full rule looks like:

description: Enforce Zod schemas in service layer
globs: ["src/services/**/*.ts"]
alwaysApply: true
referencedFiles: ["src/lib/validators.ts"]

When working in service files, always use Zod to validate inputs and outputs. Follow the existing pattern from validators.ts. Don't skip validation unless explicitly told to.

Let’s break this down:

• description: Short explanation of what the rule does
• globs: File patterns where the rule should apply (e.g., **/*.ts)
• alwaysApply: If true, the rule is used without needing manual selection
• referencedFiles: (Optional) Files used as examples or context for better AI responses
• Body: The actual instructions shown to the AI when working in matching files.

To manage rules,

• Open Customize → Rules in Cursor. From there, rules can be added, edited, and managed by scope.
• You’ll see both User Rules and Project Rules
• Toggle, delete, or update them as needed

Now that you have got the structure down, let’s look at how developers can use Cursor Custom Rules to handle real-world problems.

Use Case 1: Enforcing Consistent API Validation with Zod The Problem

Your team uses Zod for request/response validation across all service files, but devs often forget to include schemas or name things consistently.

Rule Example

description: Enforce Zod schemas in service layer
globs: ["src/services/**/*.ts"]
alwaysApply: true
referencedFiles: ["src/lib/zod-templates.ts"]

Always use Zod to validate both request and response payloads. Reuse schema patterns from zod-templates.ts. Do not allow untyped or loosely typed data to go through the service layer.

This makes the AI generate pre-validated, strongly typed service methods every time, no reminders or rework needed.

Use Case 2: Enforcing Consistent File Structure for Features

The Problem

Every new feature in your app should follow a clean structure like index.tsx, hooks.ts, types.ts, and api.ts, but different devs often structure things differently.

Rule Example

description: Enforce file structure for new feature folders
globs: ["src/features/**/index.tsx"]
alwaysApply: true

When generating or modifying a feature in src/features, make sure the folder contains:

• index.tsx as the entrypoint
• hooks.ts for all custom hooks
• types.ts for local types
• api.ts for all API calls

Follow existing naming and organization patterns.

With this rule, when the rule is active in Cursor Agent, it gives the agent consistent instructions for generating or modifying code. It does not automatically govern every AI feature in Cursor.

Use Case 3: Enforcing Unit Test Coverage with Vitest

The Problem\
You're using Vitest, and every utility function should have a corresponding test file. Devs often skip writing them.

Rule Example

description: Ensure utility functions are covered by Vitest
globs: ["src/utils/**/*.ts"]
alwaysApply: true

Whenever a new utility function is created or modified, also create a corresponding .test.ts file using Vitest. Follow the structure and naming conventions used in existing test files.

With this rule in place, AI writes tests along with your utilities, improving test coverage and helping juniors not skip QA steps.

Use Case 4: Auto-Wiring RPC Handlers with tRPC

The Problem

You're using tRPC, and you want every new route to follow a specific handler format with proper input/output typing.

Rule Example

description: Standardize tRPC handler creation
globs: ["src/server/api/**/*.ts"]
alwaysApply: true

When generating new procedures, use z.infer for input/output types. Use the protectedProcedure or publicProcedure wrapper from the existing router setup. Refer to src/server/api/_utils.ts for common logic.

With this, AI consistently generates boilerplate that aligns with your tRPC config without you needing to manually adjust every time.

Best Practices & Tips

Getting started with Custom Rules is easy, but getting them to stick and scale well with your team takes a bit of finesse. Here are some battle-tested tips to help you make the most of them:

Make Rules Iterative, Not Perfect

Don’t try to write the ultimate prompt on Day 1. Start small; even a 1-liner like “Use Zod in all services” can go a long way. Watch how Cursor responds, and improve the rule over time.

Think of rules like code: ship early, refine often.

Be Specific in the Prompt

Don’t just say “use tests"; say “use Vitest and place tests in the tests folder next to the source file." The more specific the language, the more reliable the output.

Use phrasing like "Always start with...”, “Never skip...”, “Follow the pattern from...", etc.

Review Rules as a Team

If you’re on a team, treat your rules like coding conventions. Do quick async reviews, and align on when a rule should apply (alwaysApply: true vs. manual). This helps avoid confusion or overreach from the AI. Tests, linters, type checks, CI pipelines, security checks, and code reviews should enforce requirements that need deterministic validation.

Keep It Human

Don’t over-engineer your prompts. Write it like you’re telling a junior dev sitting next to you. That’s usually the sweet spot.

Final Thoughts

Custom rules in Cursor are low-effort, high-impact. With just a few Markdown files, you can guide AI to follow your team’s coding style, enforce structure, and even auto-suggest best practices, all without writing extra logic or docs.

I have found that whether you’re working solo or on a big team, these rules let you offload the repetitive reminders and keep your codebase clean and consistent.

If you’ve ever wished AI could “just know how we do things around here,” this is how you get there.

FAQs

Are Cursor Custom Rules still supported in 2026?

Yes, Cursor Custom Rules are still supported in 2026. They provide the agent with persistent instructions for coding standards, project patterns, workflows, and other development preferences. Project rules are stored as .mdc files in .cursor/rules/, while user rules apply across projects through Cursor’s customization settings.

How can Cursor Rules reference project files?

Cursor Rules can reference project files with @filename so Agent can use them as additional context. For example, a rule can reference @src/lib/validators.ts when asking an agent to follow an existing validation pattern. This helps keep generated code aligned with established project conventions.

When should we apply a cursor rule?

A cursor rule is useful when an instruction is needed only for certain tasks but should not be tied to specific files. Cursor uses the rule’s description to decide when it is relevant, which makes this approach useful for project patterns, workflows, or domain-specific guidance.