Cursor rule

1---
2description: Meta-rule for creating effective Cursor IDE rules with best practices, patterns, and examples
3tags: [meta, cursor, documentation, best-practices]
4---
5 
6# Creating Cursor Rules - Meta Rule
7 
8## Overview
9 
10This is a meta-rule for creating effective `.cursor/rules` files. Apply these principles when writing or improving Cursor IDE rules for your project.
11 
12## When to Use
13 
14**Use when:**
15- Starting a new project and setting up `.cursor/rules`
16- Improving existing project rules
17- Converting skills or guidelines to Cursor format
18- Team needs consistent coding standards
19 
20**Don't use for:**
21- Claude Code skills (those go in `.claude/skills/`)
22- One-time instructions (just ask directly)
23- User-specific preferences (those go in global settings)
24 
25## Core Principles
26 
27### 1. Be Specific and Actionable
28 
29```markdown
30# ❌ BAD - Vague
31Write clean code with good practices.
32 
33# ✅ GOOD - Specific
34Use functional components with TypeScript.
35Define prop types with interfaces, not inline types.
36Extract hooks when logic exceeds 10 lines.
37```
38 
39### 2. Focus on Decisions, Not Basics
40 
41```markdown
42# ❌ BAD - Obvious
43Use semicolons in JavaScript.
44Indent with 2 spaces.
45 
46# ✅ GOOD - Decision guidance
47Choose Zustand for global state, React Context for component trees.
48Use Zod for runtime validation at API boundaries only.
49Prefer server components except for: forms, client-only APIs, animations.
50```
51 
52### 3. Organize by Concern
53 
54```markdown
55# ✅ GOOD Structure
56 
57## Tech Stack
58- Next.js 14 with App Router
59- TypeScript strict mode
60- Tailwind CSS for styling
61 
62## Code Style
63- Functional components only
64- Named exports (no default exports)
65- Co-locate tests with source files
66 
67## Patterns
68- Use React Server Components by default
69- Client components: mark with "use client" directive
70- Error handling: try/catch + toast notification
71 
72## Project Conventions
73- API routes in app/api/
74- Components in components/ (flat structure)
75- Types in types/ (shared), components/*/types.ts (local)
76```
77 
78## Rule Anatomy
79 
80### MDC Format and Metadata
81 
82Cursor rules are written in **MDC (.mdc)** format, which supports YAML frontmatter metadata and markdown content. The metadata controls how and when rules are applied.
83 
84### Required YAML Frontmatter
85 
86Every Cursor rule MUST start with YAML frontmatter between `---` markers:
87 
88```yaml
89---
90description: Brief description of when and how to use this rule
91globs: ["**/*.ts", "**/*.tsx"]
92alwaysApply: false
93---
94```
95 
96### Frontmatter Properties
97 
98| Property | Type | Required | Description |
99|----------|------|----------|-------------|
100| `description` | string | **Yes** | Brief description of the rule's purpose. Used by AI to decide relevance. Never use placeholders like `---` or empty strings. |
101| `globs` | array | No | File patterns that trigger auto-attachment (e.g., `["**/*.ts"]`). Leave empty or omit if not using Auto Attached type. |
102| `alwaysApply` | boolean | No | If `true`, rule is always included in context. If `false` or omitted, behavior depends on Rule Type. |
103 
104### Rule Types
105 
106Control how rules are applied using the **type dropdown** in Cursor:
107 
108| Rule Type | Description | When to Use |
109|-----------|-------------|-------------|
110| **Always** | Always included in model context | Core project conventions, tech stack, universal patterns that apply everywhere |
111| **Auto Attached** | Included when files matching `globs` pattern are referenced | File-type specific rules (e.g., React components, API routes, test files) |
112| **Agent Requested** | Available to AI, which decides whether to include it based on `description` | Contextual patterns, specialized workflows, optional conventions |
113| **Manual** | Only included when explicitly mentioned using `@ruleName` | Rarely-used patterns, experimental conventions, legacy documentation |
114 
115### Examples by Rule Type
116 
117**Always Rule** (Core conventions):
118```yaml
119---
120description: TypeScript and code style conventions for the entire project
121alwaysApply: true
122---
123```
124 
125**Auto Attached Rule** (File pattern-specific):
126```yaml
127---
128description: React component patterns and conventions
129globs: ["**/components/**/*.tsx", "**/app/**/*.tsx"]
130alwaysApply: false
131---
132```
133 
134**Agent Requested Rule** (Contextual):
135```yaml
136---
137description: RPC service boilerplate and patterns for creating new RPC endpoints
138globs: []
139alwaysApply: false
140---
141```
142 
143**Manual Rule** (Explicit invocation):
144```yaml
145---
146description: Legacy API migration patterns (deprecated, use for reference only)
147globs: []
148alwaysApply: false
149---
150```
151 
152### Best Practices for Frontmatter
153 
1541. **Description is mandatory** - AI uses this to determine relevance. Be specific:
155   - ❌ Bad: `Backend code`
156   - ✅ Good: `Fastify API route patterns, error handling, and validation using Zod`
157 
1582. **Use globs strategically** - Auto-attach to relevant file types:
159   - React components: `["**/*.tsx", "**/*.jsx"]`
160   - API routes: `["**/api/**/*.ts", "**/routes/**/*.ts"]`
161   - Tests: `["**/*.test.ts", "**/*.spec.ts"]`
162 
1633. **Avoid always applying everything** - Use `alwaysApply: true` sparingly:
164   - ✅ Good for: Tech stack, core conventions, project structure
165   - ❌ Bad for: Framework-specific patterns, specialized workflows
166 
1674. **Make Agent Requested rules discoverable** - Write descriptions that help AI understand when to use:
168   - Include keywords: "boilerplate", "template", "pattern for X"
169   - Mention specific use cases: "when creating new API routes"
170 
171### Additional Optional Fields
172 
173While the core properties above control rule behavior, you may also include:
174 
175**title:** (Optional)
176- Clear, concise name for the rule
177- Example: `Creating Cursor Rules`, `TypeScript Type Safety`
178 
179**tags:** (Optional)
180- Array of relevant tags for organization
181- Use lowercase, kebab-case
182- Example: `[meta, cursor, documentation, best-practices]`
183 
184**source:** (Optional)
185- Where the rule originated from
186- Example: `claude-code-skill`, `custom`, `community`
187 
188**IMPORTANT:** The `description` field is MANDATORY for all cursor rules. When converting skills to cursor rules or creating new rules, always include a valid description. Never use placeholders like `---` or empty strings.
189 
190## Required Sections
191 
192### Tech Stack Declaration
193 
194```markdown
195## Tech Stack
196- Framework: Next.js 14
197- Language: TypeScript 5.x (strict mode)
198- Styling: Tailwind CSS 3.x
199- State: Zustand
200- Database: PostgreSQL + Prisma
201- Testing: Vitest + Playwright
202```
203 
204**Why:** Prevents AI from suggesting wrong tools/patterns.
205 
206### Code Style Guidelines
207 
208```markdown
209## Code Style
210- **Components**: Functional with TypeScript
211- **Props**: Interface definitions, destructure in params
212- **Hooks**: Extract when logic > 10 lines
213- **Exports**: Named exports only (no default)
214- **File naming**: kebab-case.tsx
215```
216 
217### Common Patterns
218 
219```markdown
220## Patterns
221 
222### Error Handling
223```typescript
224try {
225  const result = await operation();
226  toast.success('Operation completed');
227  return result;
228} catch (error) {
229  const message = error instanceof Error ? error.message : 'Unknown error';
230  toast.error(message);
231  throw error; // Re-throw for caller to handle
232}
233```
234 
235### API Route Structure
236```typescript
237// app/api/users/route.ts
238export async function GET(request: Request) {
239  try {
240    // 1. Parse/validate input
241    // 2. Check auth/permissions
242    // 3. Perform operation
243    // 4. Return Response
244  } catch (error) {
245    return new Response(JSON.stringify({ error: 'Message' }), {
246      status: 500
247    });
248  }
249}
250```
251```
252 
253### What NOT to Include
254 
255```markdown
256# ❌ AVOID - Too obvious
257- Write readable code
258- Use meaningful variable names
259- Add comments when necessary
260- Follow best practices
261 
262# ❌ AVOID - Too restrictive
263- Never use any third-party libraries
264- Always write everything from scratch
265- Every function must be under 5 lines
266 
267# ❌ AVOID - Language-agnostic advice
268- Use design patterns
269- Think before you code
270- Test your code
271```
272 
273## Structure Template
274 
275```markdown
276# Project Name - Cursor Rules
277 
278## Tech Stack
279[List all major technologies]
280 
281## Code Style
282[Specific style decisions]
283 
284## Project Structure
285[Directory organization]
286 
287## Patterns
288[Common patterns with code examples]
289 
290### Pattern Name
291[Description]
292```code example```
293 
294## Conventions
295[Project-specific conventions]
296 
297## Common Tasks
298[Frequent operations with snippets]
299 
300### Task Name
301```
302step 1
303step 2
304```
305 
306## Anti-Patterns
307[What to avoid and why]
308 
309## Testing
310[Testing approach and patterns]
311```
312 
313## Example Sections
314 
315### Tech Stack Section
316 
317```markdown
318## Tech Stack
319 
320**Framework:** Next.js 14 (App Router)
321**Language:** TypeScript 5.x (strict mode enabled)
322**Styling:** Tailwind CSS 3.x with custom design system
323**State:** Zustand for global, React Context for component trees
324**Forms:** React Hook Form + Zod validation
325**Database:** PostgreSQL with Prisma ORM
326**Testing:** Vitest (unit), Playwright (E2E)
327**Deployment:** Vercel
328 
329**Key Dependencies:**
330- `@tanstack/react-query` for server state
331- `date-fns` for date manipulation (not moment.js)
332- `clsx` + `tailwind-merge` for conditional classes
333```
334 
335### Patterns Section with Code
336 
337```markdown
338## Patterns
339 
340### Server Component Data Fetching
341 
342```typescript
343// app/users/page.tsx
344import { prisma } from '@/lib/prisma';
345 
346export default async function UsersPage() {
347  // Fetch directly in server component
348  const users = await prisma.user.findMany({
349    select: {
350      id: true,
351      name: true,
352      email: true
353    }
354  });
355 
356  return <UserList users={users} />;
357}
358```
359 
360### Client Component with State
361 
362```typescript
363'use client';
364 
365import { useState } from 'react';
366import { toast } from 'sonner';
367 
368interface FormProps {
369  onSubmit: (data: FormData) => Promise<void>;
370}
371 
372export function Form({ onSubmit }: FormProps) {
373  const [loading, setLoading] = useState(false);
374 
375  async function handleSubmit(e: React.FormEvent) {
376    e.preventDefault();
377    setLoading(true);
378 
379    try {
380      await onSubmit(new FormData(e.target as HTMLFormElement));
381      toast.success('Saved successfully');
382    } catch (error) {
383      const message = error instanceof Error ? error.message : 'Failed to save';
384      toast.error(message);
385    } finally {
386      setLoading(false);
387    }
388  }
389 
390  return (
391    <form onSubmit={handleSubmit}>
392      {/* form fields */}
393      <button disabled={loading}>
394        {loading ? 'Saving...' : 'Save'}
395      </button>
396    </form>
397  );
398}
399```
400```
401 
402### Anti-Patterns Section
403 
404```markdown
405## Anti-Patterns
406
407### ❌ Don't: Default Exports
408```typescript
409// ❌ BAD
410export default function Button() { }
411 
412// ✅ GOOD
413export function Button() { }
414```
415 
416**Why:** Named exports are more refactor-friendly and enable better tree-shaking.
417 
418### ❌ Don't: Inline Type Definitions
419```typescript
420// ❌ BAD
421function UserCard({ user }: { user: { name: string; email: string } }) { }
422 
423// ✅ GOOD
424interface User {
425  name: string;
426  email: string;
427}
428 
429function UserCard({ user }: { user: User }) { }
430```
431 
432**Why:** Reusability and discoverability.
433 
434### ❌ Don't: Client Components for Static Content
435```typescript
436// ❌ BAD
437'use client';
438export function StaticContent() {
439  return <div>Static text</div>;
440}
441 
442// ✅ GOOD - Server component by default
443export function StaticContent() {
444  return <div>Static text</div>;
445}
446```
447 
448**Why:** Server components are faster and reduce bundle size.
449```
450 
451## Common Tasks
452 
453Include shortcuts for frequent operations:
454 
455```markdown
456## Common Tasks
457
458### Adding a New API Route
459
4601. Create `app/api/[route]/route.ts`
4612. Define HTTP method exports (GET, POST, etc.)
4623. Validate input with Zod schema
4634. Use try/catch for error handling
4645. Return `Response` object
465
466```typescript
467import { z } from 'zod';
468 
469const schema = z.object({
470  name: z.string().min(1)
471});
472 
473export async function POST(request: Request) {
474  try {
475    const body = await request.json();
476    const data = schema.parse(body);
477 
478    // Process...
479 
480    return Response.json({ success: true });
481  } catch (error) {
482    if (error instanceof z.ZodError) {
483      return Response.json(
484        { error: error.errors },
485        { status: 400 }
486      );
487    }
488    return Response.json(
489      { error: 'Internal error' },
490      { status: 500 }
491    );
492  }
493}
494```
495 
496### Adding a New Component
497 
4981. Create `components/component-name.tsx`
4992. Define props interface
5003. Export as named export
5014. Co-locate test if complex logic
502 
503```typescript
504// components/user-card.tsx
505interface UserCardProps {
506  name: string;
507  email: string;
508  onEdit?: () => void;
509}
510 
511export function UserCard({ name, email, onEdit }: UserCardProps) {
512  return (
513    <div className="rounded-lg border p-4">
514      <h3 className="font-semibold">{name}</h3>
515      <p className="text-sm text-gray-600">{email}</p>
516      {onEdit && (
517        <button onClick={onEdit}>Edit</button>
518      )}
519    </div>
520  );
521}
522```
523```
524 
525## Best Practices
526 
527### Keep Rules Under 500 Lines
528 
529- Split large rules into multiple, composable files
530- Each rule file should focus on one domain or concern
531- Reference other rule files when needed (e.g., "See `backend-api.mdc` for API patterns")
532- **Why:** Large files become unmanageable and harder for AI to process effectively
533 
534### Split Into Composable Rules
535 
536Break down by concern rather than creating one monolithic file:
537 
538```
539.cursor/rules/
540  ├── tech-stack.mdc          # Core technologies
541  ├── typescript-patterns.mdc # Language-specific patterns
542  ├── api-conventions.mdc     # API route standards
543  ├── component-patterns.mdc  # React/UI patterns
544  └── testing-standards.mdc   # Testing approaches
545```
546 
547**Why:** Easier to maintain, update, and reuse across similar projects.
548 
549### Provide Concrete Examples or Referenced Files
550 
551Instead of vague guidance, always include:
552- Complete, runnable code examples
553- References to actual project files: `See components/auth/LoginForm.tsx for example`
554- Links to internal docs or design system
555- Specific file paths and line numbers when relevant
556 
557**❌ BAD - Vague:**
558```markdown
559Use proper error handling in API routes.
560```
561 
562**✅ GOOD - Concrete:**
563```markdown
564API routes must use try/catch with typed errors. Example:
565```typescript
566// app/api/users/route.ts (lines 10-25)
567export async function POST(request: Request) {
568  try {
569    const data = await request.json();
570    return Response.json({ success: true });
571  } catch (error) {
572    return handleApiError(error); // See lib/errors.ts
573  }
574}
575```
576See `app/api/products/route.ts` for complete implementation.
577```
578 
579### Avoid Vague Guidance - Write Rules Like Clear Internal Docs
580 
581Rules should read like technical documentation, not casual advice:
582- Be precise and unambiguous
583- Include the "why" behind decisions
584- Document exceptions to rules
585- Reference architecture decisions
586- Link to related rules or documentation
587 
588**Think:** "Could a new engineer understand this without asking questions?"
589 
590### Reuse Rules When Repeating Prompts in Chat
591 
592If you find yourself giving the same instructions repeatedly in chat:
5931. Document that pattern in `.cursor/rules/`
5942. Include the specific guidance you keep repeating
5953. Add examples of correct implementation
5964. Update existing rule files rather than creating new ones
597 
598**Common scenarios to capture:**
599- "Always use X pattern for Y"
600- "Don't forget to Z when doing W"
601- Corrections you make frequently
602- Patterns specific to your team/codebase
603 
604### Keep It Scannable
605 
606- Use headers and sections
607- Bold important terms
608- Code examples for clarity
609- Tables for comparisons
610- Add table of contents for files over 200 lines
611 
612### Update Regularly
613 
614- Review monthly or after major changes
615- Remove outdated patterns
616- Add new patterns as they emerge
617- Keep examples current
618- Archive deprecated rules rather than deleting (for reference)
619 
620### Test with AI
621 
622Ask AI to:
6231. "Create a new API route following our conventions"
6242. "Add error handling to this component"
6253. "Refactor this to match our patterns"
626 
627Verify it follows your rules correctly.
628 
629## Real-World Example
630 
631See the PRPM registry `.cursor/rules` for a complete example:
632- Clear tech stack declaration
633- Specific TypeScript patterns
634- Fastify-specific conventions
635- Error handling standards
636- API route patterns
637 
638## Checklist for New Cursor Rules
639 
640**YAML Frontmatter:**
641- [ ] Title field present and descriptive
642- [ ] Description field present (MANDATORY - never empty or `---`)
643- [ ] Tags array includes relevant categories
644- [ ] Optional fields (ruleType, alwaysApply, source) added if applicable
645 
646**Project Context:**
647- [ ] Tech stack clearly defined
648- [ ] Version numbers specified
649- [ ] Key dependencies listed
650 
651**Code Style:**
652- [ ] Component style specified (functional/class)
653- [ ] Export style (named/default)
654- [ ] File naming convention
655- [ ] Specific to project (not generic)
656 
657**Patterns:**
658- [ ] At least 3 code examples
659- [ ] Cover most common tasks
660- [ ] Include error handling pattern
661- [ ] Show project-specific conventions
662 
663**Organization:**
664- [ ] Logical section headers
665- [ ] Scannable (not wall of text)
666- [ ] Examples are complete and runnable
667- [ ] Anti-patterns included
668 
669**Testing:**
670- [ ] Tested with AI assistant
671- [ ] AI follows conventions correctly
672- [ ] Updated after catching mistakes
673 
674---
675 
676**Remember:** Cursor rules are living documents. Update them as your project evolves and patterns emerge.
677 
678```