How I transformed my Cursor rules for better AI coding

If you’re using Cursor (and if you’re not, you should be), you’ve probably discovered the magic of .cursor/rules files. But here’s the thing – most of us start with massive, verbose rules that look impressive but quickly become unmaintainable nightmares.

I recently went through a complete overhaul of my Cursor Rules setup for a Next.js project, and the results were so good I had to share. Let me walk you through the transformation and the lessons learned.

The Problem: When Rules Become Rulers

My original rules looked like this typical mess:

1
---
2
description: "typescript-patterns"
3
globs: *.ts,*.tsx
4
---
5

6
# TypeScript Patterns for CVPHOTO
7

8
## Type Safety Requirements
9

10
### Strict Configuration
11
The project uses strict TypeScript configuration via tsconfig.json:
12
- `strict: true` is enabled
13
- Never use `any` type - use `unknown` instead
14
- Always provide explicit types for function parameters...
15

16
[500 more lines of verbose examples and explanations]

Sound familiar? These rules had several problems:

1. Overwhelming verbosity – Nobody wants to read a novel every time they need a quick pattern
2. Stale code examples – Hard-coded snippets that went out of sync with the actual codebase
3. Poor targeting – Basic glob patterns that didn’t leverage Cursor’s smart application
4. Maintenance nightmare – Every code change meant updating multiple rule files

The Solution: Reference-Driven, Context-Aware Rules

Here’s what I transformed that rule into:

1
---
2
alwaysApply: false
3
description: TypeScript patterns and code style conventions
4
globs: ["**/*.{ts,tsx}", "!node_modules/**", "!.next/**"]
5
---
6

7
## TypeScript Patterns & Code Style
8

9
### Type safety
10
- Enable and honor strict mode; do not use `any`. Prefer `unknown` with proper narrowing.
11
- Prefer discriminated unions over enums.
12
- Use `readonly` for immutable properties/arrays.
13
- Add explicit types for function params/returns and exported objects.
14

15
### Control flow & syntax
16
- Use early returns and handle edge cases first.
17
- Use optional chaining (`?.`) and nullish coalescing (`??`) appropriately.
18
- Avoid `await` in return statements.
19

20
### Imports
21
- Order: built-in → external → internal → parent → sibling → index → type
22
- Add blank lines between groups; sort members alphabetically.
23

24
### File organization
25
- Keep files under ~300 lines when possible; split by responsibility.
26
- Centralize shared types in `src/types` or local `types.ts` next to implementations.

Much better, right? But the real magic happens when you combine this with…

The Game Changer: Smart File References

Instead of copying code into rules, I started using Cursor’s mdc: reference system:

1
### Data & actions
2
- Server actions: [src/action/](mdc:src/action/) (auth, user updates, payments)
3
- Supabase clients: [server](mdc:src/utils/supabase/server.ts) (SSR-safe), [client](mdc:src/utils/supabase/client.ts) (browser)
4
- AI workflows: [tune training](mdc:src/app/api/llm/tune/createTune.ts), [prompt generation](mdc:src/app/api/llm/prompt/createPrompt.ts)

This approach has huge benefits:

• Living documentation – Rules always point to current code
• Single source of truth – No more keeping examples in sync
• Context-rich references – AI understands what each file actually does
• Reduced maintenance – Code changes automatically keep rules current

The Architecture: A Layered Approach

I organized my rules into three tiers:

1. Core Layer (Always Applied)

1
# project-structure-and-style.mdc
2
alwaysApply: true

Essential conventions that apply everywhere. Keep this minimal – one rule max.

2. Context Layer (Auto-Applied via Globs)

1
# agents.mdc - Templates for components/APIs
2
globs: ["src/components/**/*.{ts,tsx}", "src/app/api/**/route.ts"]
3

4
# ui-components.mdc - Radix/Tailwind patterns
5
globs: ["src/components/**/*.{ts,tsx}", "src/app/**/page.tsx"]
6

7
# supabase-patterns.mdc - Database operations
8
globs: ["src/action/**/*.ts", "src/utils/supabase/**/*.ts"]

These rules activate automatically based on what files you’re working in. Smart!

3. Reference Layer (Manual Fetch)

1
# development-workflow.mdc
2
alwaysApply: false
3
# No globs - manual reference only

Documentation-heavy rules you fetch when needed.

Pro Tips I Learned Along the Way

1. Use Array-Based Globs

1
# ✅ Good
2
globs: ["src/components/**/*.{ts,tsx}", "!**/*.test.ts"]
3

4
# ❌ Avoid
5
globs: "*.ts,*.tsx"

Array format gives you more control and better exclusion patterns.

2. Add Context to File References

1
# ✅ Better
2
- [src/action/auth.ts](mdc:src/action/auth.ts) (login, logout, session management)
3

4
# ❌ Basic
5
- [src/action/auth.ts](mdc:src/action/auth.ts)

Help the AI understand what each file contains.

3. Create a Rule Selection Guide

I added a README.md to my rules directory that maps common workflows to relevant rules:

1
### When Working On...
2

3
**🎨 UI Components & Pages**
4
- Primary: `agents` (templates & standards)
5
- Secondary: `ui-components` (Radix/Tailwind patterns)
6
- Always: `typescript-patterns` (code style)
7

8
**🔧 API Endpoints**
9
- Primary: `agents` (API templates)
10
- Secondary: `api-integrations` (if Stripe/Astria)
11
- Always: `typescript-patterns` (code style)

4. Template Everything

My agents.mdc rule includes actual templates:

1
// Component template
2
export type ButtonLikeProps = Readonly<{
3
  label: string;
4
  onClick?: (event: MouseEvent<HTMLButtonElement>) => void;
5
  disabled?: boolean;
6
  className?: string;
7
}>;
8

9
export function ButtonLike({ label, onClick, disabled = false }: ButtonLikeProps) {
10
  return (
11
    <button
12
      type="button"
13
      aria-disabled={disabled}
14
      onClick={onClick}
15
      className={`inline-flex items-center...`}
16
    >
17
      {label}
18
    </button>
19
  );
20
}

This gives the AI concrete patterns to follow for new components.

The Results: Night and Day Difference

After the transformation:

• Rules are actually readable – No more 500-line documentation files
• Always current – File references mean rules never go stale
• Context-aware – Right rules activate at the right time
• Maintainable – Changes to one rule file, not scattered examples
• Effective – AI suggestions improved dramatically

Your Turn: The Migration Strategy

If you want to try this approach:

1. Start with one rule – Pick your most verbose rule file
2. Extract the essence – What are the core principles?
3. Replace examples with references – Use mdc: links to actual code
4. Add smart globs – Target specific file patterns
5. Test and iterate – See how the AI responds to your changes

The goal isn’t to document everything – it’s to give the AI just enough context to make smart decisions while keeping your rules maintainable.

The Bottom Line

Good Cursor Rules aren’t about being comprehensive – they’re about being useful. The best rule is one that gives the AI exactly what it needs, when it needs it, without overwhelming the context window.

Your rules should feel like a helpful colleague whispering the right advice at the right moment, not a manual that requires a PhD to understand.

What’s your Cursor Rules setup like? Have you found patterns that work particularly well? I’d love to hear about your experiences in the comments.