Rules

Cursor Rules Best Practices

What Is .cursor/rules?

A .cursor/rules file in your project root provides persistent instructions that Cursor includes as context in every AI interaction. It shapes all code generation for your project.

Rule Structure Template

# Project Context
[Brief description of the project]

# Tech Stack
[List exact versions]

# Code Style
[Conventions and patterns]

# Architecture
[Key patterns and structure]

# Do NOT
[Anti-patterns to avoid]

The 7 Rules for Writing Good Rules

Rule 1: Be Specific, Not Generic

Rule 2: Include Your Tech Stack with Versions

Tech Stack:
- Next.js 14.1 with App Router (NOT Pages Router)
- TypeScript 5.3 in strict mode
- Tailwind CSS 3.4 (NOT styled-components)
- Prisma 5.8 with PostgreSQL
- Zod for runtime validation

Rule 3: Define File Organization

File Structure:
- Components: src/components/[feature]/[ComponentName].tsx
- Hooks: src/hooks/use[HookName].ts
- Utils: src/lib/[category]/[utilName].ts
- Types: src/types/[domain].ts
- API routes: src/app/api/[resource]/route.ts

Rule 4: Specify What NOT to Do

Negative constraints are often more useful than positive ones:

Do NOT:
- Use default exports (always named exports)
- Use `any` type (use `unknown` with type guards)
- Use `var` (use `const` by default, `let` only when mutation needed)
- Create files longer than 200 lines
- Use inline styles (use Tailwind classes)
- Import from barrel files (import from specific modules)

Rule 5: Include Example Code

Example of correct component style:

export function UserCard({ user }: { user: User }) {
  if (!user) return null;
  
  return (
    <div className="rounded-lg border p-4">
      <h3 className="text-lg font-semibold">{user.name}</h3>
    </div>
  );
}

Rule 6: Keep It Under 500 Lines

Cursor has context limits. Prioritize:

1. Critical conventions (what causes bugs if ignored)
2. Architecture patterns (what causes rework if wrong)
3. Style preferences (what causes review friction)

Rule 7: Update Regularly

Review your .cursor/rules file:

• After every major dependency upgrade
• When team conventions change
• When you notice repeated AI mistakes
• Monthly as a minimum cadence

Project-Specific Rule Templates

React/Next.js Project:

- Use Server Components by default
- Client Components only for: forms, event handlers, browser APIs
- Validate all API inputs with Zod schemas
- Use next/image for all images
- Use next/link for all internal navigation

Python/FastAPI Project:

- Use Pydantic v2 models for all request/response schemas
- Async functions by default for route handlers
- Type hints on all function parameters and returns
- Use dependency injection for database sessions
- Structured logging with structlog

General Backend:

- Every endpoint must validate input before processing
- Database operations wrapped in transactions for writes
- All external API calls must have timeout and retry logic
- Never expose internal error details to clients
- Log all state changes with correlation IDs

Multiple Rules Files (Cursor Project Rules)

Cursor supports directory-specific rules in .cursor/rules/:

.cursor/
  rules/
    frontend.mdc      # Rules for src/app/ and src/components/
    api.mdc           # Rules for src/app/api/
    database.mdc      # Rules for prisma/ and migrations
    testing.mdc       # Rules for __tests__/ and *.test.* files

Each .mdc file can specify a glob pattern for when it activates:

---
description: Frontend component rules
globs: src/components/**/*.tsx, src/app/**/page.tsx
---
[Rules content here]