Custom Instructions with Cursor Rules

One of Cursor's most powerful but underused features is its rules system. Rather than re-explaining your coding preferences in every chat, you can write them down once and have the AI follow them automatically. The result is an AI collaborator that seems to know your codebase, because you taught it how.

In this lesson, you will learn what Cursor Rules are, the different kinds of rules, how to write them, and how to keep them useful as a project grows.

What You'll Learn

• What Cursor Rules are and how they reach the AI
• Project Rules in .cursor/rules/ and their four application types
• How to write .mdc rule files with frontmatter
• AGENTS.md as a simple, cross-tool alternative (including nested files)
• User Rules and Team Rules, and which rules win when they conflict
• Writing effective rules with concrete examples
• When and how to update your rules as a project evolves

---

What Are Cursor Rules?

Cursor Rules are instruction files that tell Cursor's AI how to behave in your project. Think of them as a persistent system prompt: guidelines the AI reads before it works, so you never have to repeat yourself.

Without rules, each chat starts fresh. The AI does not know whether your project uses TypeScript strict mode, whether you prefer async/await over promise chains, or whether every function needs error handling. With rules, that context is always there.

Rules are applied to the AI features that use a language model in chat and editing:

• Agent (the side panel, Cmd+I or Cmd+L) follows your rules when it plans, writes code, and runs commands
• Ask and Plan modes use your rules when answering questions and drafting plans
• Inline edit (Cmd+K) respects your style and conventions

Tab completion uses Cursor's own specialized model and learns mostly from the code around your cursor, so do not count on rules to steer it.

A Simple Example

Say you always want functional React components with TypeScript. Without rules, the AI might generate a class component, or skip type annotations. With a short rule:

Always use functional React components with TypeScript.
Never use class components.
All component props must have explicit TypeScript interfaces.

Every response that touches components will follow this pattern from then on.

---

The Kinds of Rules

Cursor supports several places to put instructions. Each one fits a different need.

Kind	Where it lives	Scope	Shared?
Project Rules	.cursor/rules/*.mdc in your repo	This project	Yes, via version control
AGENTS.md	Markdown file at the project root or in subfolders	This project (or folder)	Yes, via version control
User Rules	Cursor Settings → Rules	All your projects	No, personal
Team Rules	Cursor team dashboard (Team and Enterprise plans)	Everyone on the team	Yes, managed centrally

---

Project Rules

Project Rules live in a .cursor/rules/ folder in your repository. Because they are committed to version control, every team member who uses Cursor gets the same AI behavior automatically.

my-project/
├── .cursor/
│   └── rules/
│       ├── general.mdc      ← general coding standards
│       ├── react.mdc        ← React-specific rules
│       ├── api.mdc          ← API route conventions
│       └── testing.mdc      ← testing conventions
├── src/
└── package.json

Each file uses the .mdc extension: Markdown with a small frontmatter block at the top that controls when the rule applies.

Rule File Format

---
description: React component conventions for UI files
globs: src/components/**/*.tsx, src/app/**/*.tsx
alwaysApply: false
---

# React Component Rules

- Use functional components with TypeScript
- Define prop types as named interfaces above each component
- Use the shadcn/ui component library for UI primitives

The three frontmatter fields are:

• description: a short summary of what the rule covers. The agent reads it to decide whether the rule is relevant.
• globs: file path patterns. The rule attaches when files matching these patterns are in play.
• alwaysApply: when true, the rule is included in every request, regardless of files or description.

You can create a rule by hand or from the rules section of Cursor's settings, which writes the file and frontmatter for you.

The Four Application Types

How you fill in the frontmatter decides how a rule is applied. Cursor groups this into four types:

Type	How it applies	Typical frontmatter	Good for
Always Apply	Included in every request	alwaysApply: true	Core language and style standards
Apply to Specific Files	Included when files match the globs	globs set, alwaysApply: false	React rules for *.tsx, test rules for *.test.ts
Apply Intelligently	The agent decides based on the description	description set, no globs, alwaysApply: false	Topic rules like "database migrations"
Manual	Only when you @-mention the rule in chat	No description, no globs, alwaysApply: false	Rare checklists, release steps, special templates

A practical approach: keep one or two small Always Apply rules for essentials, use file-specific rules for framework conventions, and save Manual rules for occasional workflows. Every Always Apply rule takes up context in every request, so keep those short.

Organizing Rules by Concern

A well-organized .cursor/rules/ folder might look like this:

.cursor/rules/
├── general.mdc          # Always Apply: language, style, error handling
├── react.mdc            # Specific Files: *.tsx
├── api.mdc              # Specific Files: src/api/**
├── tests.mdc            # Specific Files: *.test.ts, *.spec.ts
├── database.mdc         # Apply Intelligently: "schema changes and migrations"
└── release.mdc          # Manual: @-mention when cutting a release

This keeps each rule focused and avoids loading irrelevant guidance into every request.

---

AGENTS.md: The Simple Option

If you do not need frontmatter or application types, you can use an AGENTS.md file instead. It is plain Markdown placed at the root of your project:

my-project/
├── AGENTS.md           ← instructions for the whole project
├── src/
│   └── api/
│       └── AGENTS.md   ← extra instructions for src/api and below
└── package.json

AGENTS.md has two nice properties:

• Nesting. You can put an AGENTS.md in a subfolder. It applies to that folder and its children, which suits monorepos where each package has its own conventions.
• Portability. AGENTS.md is a cross-tool convention. Other AI coding agents read the same file or similar ones, so one set of instructions can serve your whole toolchain.

Use AGENTS.md when you want something quick and readable. Switch to Project Rules when you need rules that apply only to certain file types or only when relevant.

---

User Rules and Team Rules

User Rules

User Rules are global. You set them in Cursor Settings → Rules, and they apply to every project you open. They are stored with your Cursor settings, not in any repository.

They are good for personal preferences: how you like explanations written, your preferred comment style, or "always show the full file path when you mention a file."

Team Rules

On Team and Enterprise plans, admins can set Team Rules from the Cursor dashboard. They apply to everyone on the team across projects, which makes them a good home for company-wide standards like security practices or required licenses in file headers.

Which Rules Win?

All applicable rules are combined and sent to the AI together. When they conflict, Cursor's precedence order is:

Team Rules → Project Rules → User Rules

Team Rules come first, then the project's rules, then your personal ones. In practice, keep personal style in User Rules and anything the team must share in Project Rules or Team Rules, so conflicts are rare.

A Note on .cursorrules

Older projects may have a single .cursorrules file at the root. This is a legacy format. If you find one, move its contents into .cursor/rules/ (splitting it into focused files) or into an AGENTS.md file.

---

How Rules Shape AI Behavior

Rules work by being added to the model's context. When you send a request, Cursor includes the applicable rules before your message, and the model treats them as guidance.

This means rules can affect:

• Code style: indentation, quote style, semicolons, line length
• Framework patterns: which hooks to use, how to structure components
• Language features: which TypeScript features to use or avoid
• Architecture decisions: where to put logic, how to organize files
• Error handling: whether to throw, return error objects, or use try/catch
• Documentation: whether to add JSDoc comments and how detailed they should be
• Testing: which test library, how to name tests, what to test
• Agent workflow: which commands to run to test or lint, and what never to touch

Rules are guidance, not hard constraints. If a rule conflicts with what you ask for, you can override it in your message. Rules set defaults; your prompts have the final say.

---

Writing Effective Rules

Good rules are specific, actionable, and clear. Vague rules like "write clean code" do not help, because the AI already tries to do that. Specific rules like "use const instead of let unless reassignment is required" give clear guidance.

Principles for Good Rules

Be concrete, not aspirational. Instead of "write maintainable code," write "extract functions longer than 30 lines into separate named functions."

Say why when it helps. "Prefer Array.map() over for loops for transformations, because this project uses a functional style" is more useful than "use Array.map()."

Include examples where things are unclear. For unusual patterns, a short example prevents misreading.

Keep rules focused. One concern per rule file. Do not mix strict mode, error handling, and component style into one block. Split them.

Keep them short. Long rules eat context. If a rule file grows past a few hundred lines, split it or move rarely needed parts into a Manual rule.

Examples of Effective Rules

Here is a set of rules for a modern TypeScript and React project:

# Language and Types
- Use TypeScript strict mode. Never use `any`. Use `unknown` when the type is truly uncertain.
- Prefer type aliases over interfaces for object shapes. Use interfaces only for extensible public APIs.
- All function parameters and return values must have explicit type annotations.

# React Components
- Use functional components with React hooks. Never use class components.
- All component props must have a named TypeScript type defined directly above the component.
- Extract reusable logic into custom hooks in src/hooks/. Name custom hooks with the `use` prefix.
- Keep components under 150 lines. If longer, split into subcomponents.

# Error Handling
- All async functions must have try/catch blocks or return a Result type.
- Never swallow errors silently. Always log or propagate them.
- Use custom error classes for domain errors in src/errors/.

# API and Data Fetching
- Use React Query for all server state. Do not use useEffect for data fetching.
- API calls go in src/api/. Components should call hooks, not API functions directly.

# Testing
- Use Vitest and React Testing Library. No Enzyme.
- Test files live next to the files they test, named *.test.ts or *.test.tsx.
- Test behavior, not implementation. Do not test internal state.
- After changing code, run `npm test` and fix failures before finishing.

These rules are specific enough to change what the AI generates, while leaving room for judgment where context matters.

---

When to Update Your Rules

Rules are living documentation. They should change as your project changes.

Add rules when you notice repeated corrections

If you keep telling the AI the same thing ("don't forget the loading state," "check for null before accessing this property"), that is a signal to add a rule.

Update rules when the project changes direction

If your team moves from one testing library to another, update the rules right away. Stale rules that point to old patterns can actively confuse the AI.

Review rules when onboarding team members

Rules double as documentation. When a new developer asks "how do we handle errors here?" you can point them to your rules or AGENTS.md. That makes rules worth maintaining carefully.

Remove rules that no longer apply

Outdated rules create noise. If your project no longer uses a pattern or library, delete the rules that mention it. The cleaner your rules, the more reliable the AI.

---

Summary

Cursor Rules let you encode your project's conventions, style, and architecture into instructions the AI reads automatically. Project Rules in .cursor/rules/ give you fine control through frontmatter and four application types: Always Apply, Apply to Specific Files, Apply Intelligently, and Manual. AGENTS.md is a simpler, cross-tool option that also supports nested files. User Rules hold your personal preferences, and Team Rules hold company-wide standards. When rules conflict, Team Rules come first, then Project Rules, then User Rules.

Writing good rules pays off quickly. Once they are in place, you stop correcting the AI and start reviewing its output.

---

Key Takeaways

• Cursor Rules give the AI persistent guidance so you do not repeat yourself in every chat
• Project Rules live in .cursor/rules/ as .mdc files with description, globs, and alwaysApply frontmatter, and are shared through version control
• The four application types are Always Apply, Apply to Specific Files, Apply Intelligently, and Manual (only when @-mentioned)
• AGENTS.md is plain Markdown at the project root or in subfolders, and works across AI tools
• User Rules are personal and global; Team Rules are set by admins for the whole team
• Precedence is Team Rules, then Project Rules, then User Rules
• .cursorrules is a legacy format; migrate it to .cursor/rules/ or AGENTS.md
• Update rules when you see repeated corrections, when the project changes, and remove stale ones