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:
- 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.
- 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.mdcHere’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.
