Custom Rules and Templates

Your team has five developers using Cursor. One of them always gets clean, well-structured output. The others get inconsistent results — different naming conventions, different error handling patterns, different file organization. The difference is not prompting skill. The developer with consistent results has a .cursor/rules/ directory with 12 carefully crafted rule files that teach the agent how your team writes code.

Rules are the single most impactful investment you can make in Cursor productivity. They persist across every chat session, apply automatically based on file patterns, and ensure every developer on your team gets the same quality of AI output.

What You’ll Walk Away With

• A framework for deciding what to encode as rules versus what to leave as ad-hoc prompts
• Rule file structure with frontmatter for glob patterns, descriptions, and auto-apply settings
• A starter library of production-tested rules you can adapt to your project
• Techniques for organizing, composing, and maintaining rules at scale

Rule Types and When to Use Each

Cursor supports four rule application modes:

Type	Frontmatter	When Applied	Use For
Always Apply	alwaysApply: true	Every chat session	Core coding standards, file conventions
Apply Intelligently	alwaysApply: false + description	Agent decides based on relevance	Domain-specific patterns, workflow guides
Glob-Scoped	globs: "src/api/**/*.ts"	When matching files are in context	Directory-specific conventions
Manual	No frontmatter or alwaysApply: false without description	When @rule-name is mentioned	Specialized workflows, templates

The Rule Decision Framework

Ask yourself: “Does every single prompt benefit from this information?”

• Yes -> Always Apply (file naming, code style, project structure)
• Only when working in a specific area -> Glob-Scoped (backend conventions, frontend patterns)
• Only for certain types of tasks -> Apply Intelligently (migration guide, API creation steps)
• Rarely, but critical when needed -> Manual (security audit checklist, release process)

Building Your Rules Library

Rule 1: Project Overview (Always Apply)

Every project should have one always-apply rule that gives the agent essential context:

Tip

Copy-paste rule — project overview:

Create .cursor/rules/project-overview.mdc:

---
alwaysApply: true
---

This is a Next.js 14 SaaS application using the App Router.

Tech stack:
- Next.js 14 with App Router and Server Components
- TypeScript with strict mode
- Tailwind CSS for styling
- Drizzle ORM with PostgreSQL
- NextAuth.js for authentication
- Stripe for payments
- Vitest for testing

Key directories:
- src/app/ -- Next.js routes and pages
- src/components/ -- Shared React components
- src/lib/ -- Utility functions and service clients
- src/db/ -- Database schema, migrations, and queries
- src/types/ -- Shared TypeScript types

Use the logger from @src/lib/logger.ts instead of console.log.
Error responses must use the format from @src/lib/errors.ts.

Rule 2: Code Style (Always Apply, Glob-Scoped)

---
globs: "*.ts,*.tsx"
alwaysApply: true
---

TypeScript conventions for this project:
- Use `interface` for object shapes, `type` for unions and intersections
- Prefer `async/await` over `.then()` chains
- Use `unknown` instead of `any`
- Destructure function parameters when there are more than 2
- All exported functions must have JSDoc comments
- Prefer early returns over nested conditionals

Rule 3: Feature Implementation Guide (Agent-Decided)

---
description: Step-by-step guide for implementing a new feature end-to-end
alwaysApply: false
---

When implementing a new feature:

1. Database: Create migration in src/db/migrations/ using Drizzle
2. Types: Add TypeScript types in src/types/
3. API: Create route handler in src/app/api/
4. Service: Add business logic in src/lib/services/
5. UI: Build components in src/components/ and page in src/app/
6. Tests: Write tests adjacent to the source files

Always check for existing patterns before creating new ones.
Reference @src/app/api/users/route.ts as the canonical API example.
Reference @src/components/UserProfile.tsx as the canonical component example.

Rule 4: Testing Conventions (Glob-Scoped)

---
globs: "**/*.test.ts,**/*.test.tsx,**/*.spec.ts"
---

Testing conventions:
- Use Vitest with happy-dom for DOM tests
- Test file lives adjacent to source: foo.ts -> foo.test.ts
- Use descriptive test names: "should return 401 when token is expired"
- Mock external services, never make real HTTP calls in unit tests
- Use factory functions for test data, not inline object literals
- Test error paths, not just happy paths

See @src/lib/services/__tests__/user-service.test.ts for a complete example.

Referencing Files in Rules

Rules can reference other files using @filename syntax. This is far better than copying code into the rule because the reference always points to the current version:

---
description: Create a new API endpoint
alwaysApply: false
---

Follow the pattern in @src/app/api/users/route.ts exactly:
- Same error handling structure
- Same response format
- Same middleware chain
- Same validation approach using Zod schemas from @src/lib/validators/

Do not copy the user-specific logic. Only copy the structural patterns.

Caution

Keep rules under 500 lines. If a rule is getting long, split it into multiple focused rules. A 200-line rule that covers everything about your API is harder for the agent to apply than three 60-line rules covering routes, validation, and error handling separately.

Team Rules (Team and Enterprise Plans)

Team and Enterprise plans support centralized rules managed from the Cursor dashboard. These rules apply across all projects for every team member.

Team Rules are useful for:

• Organization-wide coding standards
• Security policies
• Compliance requirements
• Shared conventions that span multiple repositories

Precedence Order

When rules conflict, they are applied in this order:

1. Team Rules (highest precedence)
2. Project Rules (.cursor/rules/)
3. User Rules (personal preferences)

This means a team admin can enforce standards that individual developers cannot override.

Tip

Copy-paste prompt for generating rules from existing code:

Analyze the patterns in @src/app/api/ and generate a Cursor rule file (.mdc format) that documents:
1. The route handler structure (how handlers are organized)
2. The error handling pattern (how errors are caught and formatted)
3. The validation approach (how request bodies are validated)
4. The response format (how successful responses are structured)

Output the rule as a markdown file with appropriate frontmatter (description, globs for src/app/api/**/*.ts). Keep it under 100 lines.

Importing and Sharing Rules

Remote Rules from GitHub

Import rules directly from GitHub repositories:

1. Open Cursor Settings > Rules, Commands
2. Click + Add Rule next to Project Rules
3. Select Remote Rule (GitHub)
4. Paste the repository URL

Imported rules stay synced with the source repository. Updates to the remote rule are automatically reflected in your project.

Agent Skills Integration

Cursor can load rules from Agent Skills, an open standard for extending AI agents. Enable them in Cursor Settings > Rules > Import Settings > Agent Skills. These are treated as agent-decided rules — Cursor determines when they are relevant based on context.

When This Breaks

Rules are not being applied. Check that the rule file is in .cursor/rules/ with the correct extension (.md or .mdc). For .mdc files, verify the frontmatter syntax. View applied rules by hovering the context gauge in the prompt input.

Rules conflict with each other. Split conflicting rules into more specific glob patterns. A rule for src/api/**/*.ts and a rule for src/frontend/**/*.tsx will never conflict because they target different files.

Rules are too generic to be useful. The number one mistake: writing rules that sound like a style guide without concrete examples. Instead of “use proper error handling,” write “wrap all database calls in try/catch and throw AppError from @src/lib/errors.ts with the appropriate HTTP status code.”

Agent ignores rules. Agent-decided rules (alwaysApply: false with a description) depend on the agent determining relevance. If the rule is not being picked up for relevant tasks, either make it always-apply or add more specific glob patterns.

What’s Next

• Team Collaboration — Share rules across your team and enforce standards
• Large Codebase Strategies — Rules are essential for large project navigation
• Token Management — Rules consume context tokens; optimize for relevance