Project Rules

You ask the AI to create an API endpoint. It generates Express-style code when your project uses Hono. It puts the route handler in src/routes/ when your convention is src/api/. It uses var instead of const. It names the file userController.ts when your team uses kebab-case. None of these are hard problems, but fixing them every single time is death by a thousand cuts. Project rules solve this permanently: you write the instruction once, and the AI follows it on every interaction from that point forward.

What You’ll Walk Away With

• A .cursor/rules/ directory with actionable rules that immediately improve AI output quality
• Understanding of the four rule types (Always, Auto-attached, Agent-decided, Manual) and when to use each
• Ready-to-use rule templates for code style, architecture, and testing
• A workflow for iterating on rules as your team discovers new patterns

How Rules Work in Cursor

Rules are markdown files in .cursor/rules/ that get injected into the AI’s context automatically. Think of them as persistent system prompts — instructions that apply without you having to type them every time.

Cursor supports .md and .mdc file extensions. The .mdc format adds frontmatter for controlling when rules apply.

.cursor/rules/
  code-style.mdc        # Applied to every interaction
  react-patterns.mdc    # Applied when editing React files
  api-conventions.mdc   # Applied when editing API routes
  legacy-handling.md    # Applied only when manually referenced

The Four Rule Types

Type	Frontmatter	When It Applies
Always Apply	alwaysApply: true	Every chat, every file, every time
Auto-attached	globs: ["src/components/**/*.tsx"]	When the agent touches files matching the pattern
Agent-decided	alwaysApply: false + description	When the agent determines it is relevant based on the description
Manual	alwaysApply: false, no globs	Only when you type @rule-name in chat

Creating Your First Rules

Step 1: Create the Rules Directory

The .cursor/rules/ directory should exist at your project root. Cursor auto-creates it when you use the “New Cursor Rule” command, but you can also create it manually:

mkdir -p .cursor/rules

Step 2: Start with an Always-Apply Rule

This is the most important rule you will write. It covers universal standards that should never be violated.

Copy-paste: core project rule template

Create .cursor/rules/core.mdc with this content:

---
description: Core project standards that apply to all code
alwaysApply: true
---

# Project: [Your Project Name]

## Tech Stack
- Runtime: Node.js 20 with TypeScript 5.x (strict mode)
- Framework: [Your framework, e.g., Next.js 15 App Router]
- Database: [Your DB, e.g., PostgreSQL with Drizzle ORM]
- Testing: Vitest for unit tests, Playwright for e2e
- Styling: Tailwind CSS

## Code Conventions
- Use const by default, let only when reassignment is needed, never var
- Prefer async/await over .then() chains
- Use named exports, not default exports
- Error handling: always use typed errors, never throw raw strings
- File naming: kebab-case for files, PascalCase for components

## Architecture
- API routes go in src/api/
- Business logic lives in src/services/
- Database queries go in src/db/
- Shared types go in src/types/
- Reuse existing patterns -- check for similar implementations before creating new ones

## What NOT to Do
- Do not install new dependencies without asking first
- Do not modify configuration files (.env, tsconfig, package.json) without explicit request
- Do not remove existing tests
- Do not use any as a type -- use unknown and narrow appropriately

Step 3: Add File-Pattern Rules

These rules activate only when the agent works on matching files.

React Components

---
description: React component standards
globs: ["src/components/**/*.tsx", "src/app/**/*.tsx"]
---

# React Component Rules

- Use functional components with explicit TypeScript props interface
- Extract complex logic into custom hooks in the same directory
- Keep components under 150 lines -- split into sub-components if larger
- Use CSS modules or Tailwind utility classes, never inline styles
- Include aria-labels for interactive elements

## Component Template
Refer to @src/components/Button.tsx as the canonical example
for prop typing, error boundaries, and test structure.

API Routes

---
description: API route patterns
globs: ["src/api/**/*.ts", "src/pages/api/**/*.ts"]
---

# API Route Standards

- Validate all inputs with Zod schemas
- Return consistent response shape: { success, data?, error? }
- Include rate limiting on write endpoints
- Log all errors with structured context (requestId, userId, endpoint)
- Never expose internal error details to clients

## Error Response Format
```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email format is invalid"
  }
}
```

Database

---
description: Database and ORM conventions
globs: ["src/db/**/*.ts", "drizzle/**/*", "prisma/**/*"]
---

# Database Rules

- All schema changes go through migrations, never manual ALTER statements
- Use transactions for multi-table writes
- Add indexes for columns used in WHERE clauses and JOINs
- Implement soft deletes (deletedAt column) for user-facing data
- Table names: plural snake_case (user_profiles, not UserProfile)
- Column names: snake_case (created_at, not createdAt)

Step 4: Add an Agent-Decided Rule

These rules have a description that the agent reads to decide relevance. Use them for guidelines that only matter in specific contexts.

---
description: Performance optimization guidelines for when the user asks about performance, latency, or speed improvements
alwaysApply: false
---

# Performance Guidelines

When optimizing code:
- Profile before optimizing -- do not guess at bottlenecks
- Prefer algorithmic improvements over micro-optimizations
- Cache expensive computations at the appropriate layer
- Use lazy loading for components not visible on initial render
- Document the performance improvement with before/after metrics

Best Practices for Rules

Keep Rules Focused and Short

The Cursor team recommends keeping rules under 500 lines. In practice, 50-200 lines per rule file works best. One topic per file.

Reference Files Instead of Copying Code

Instead of pasting your entire component template into a rule, point to the canonical example:

## Component Pattern
Follow the structure in @src/components/DataTable.tsx for all new table components.

This keeps rules short and prevents them from going stale when the referenced code changes.

Start Simple, Add Rules When You See Mistakes

Do not try to write every possible rule upfront. Start with the core rule from Step 2, use Cursor for a week, and notice where the AI consistently makes the wrong choice. Each mistake is a signal to add a rule.

Caution

Common rule anti-patterns to avoid:

• Copying entire style guides: The AI already knows common conventions. Only document what is specific to your project.
• Rules that contradict each other: If your core rule says “use named exports” but your React rule says “use default exports for pages,” the AI gets confused.
• Rules about things your linter catches: Do not duplicate ESLint or Prettier rules. The AI runs your linter automatically.
• Vague instructions: “Write clean code” is meaningless. “Keep functions under 30 lines and extract complex conditionals into named variables” is actionable.

Commit Rules to Git

Rules belong in version control. They are team knowledge:

git add .cursor/rules/
git commit -m "Add project rules for AI code generation"

When the AI makes a mistake that a rule should have prevented, update the rule and commit the fix. Over time, your rules become a living document of your team’s conventions.

AGENTS.md: The Simple Alternative

If your project needs minimal rules, Cursor also supports a plain AGENTS.md file in the project root. No frontmatter, no globs — just markdown instructions that always apply.

# Project Instructions

- This is a Next.js 15 App Router project with TypeScript
- Use Drizzle ORM for database queries
- All API routes use Zod validation
- Test with Vitest, run tests with `npm test`

AGENTS.md is good for getting started quickly. Migrate to .cursor/rules/ when you need file-pattern targeting or rule-type control.

Agent Skills: Extending Rules from the Community

Cursor supports Agent Skills — an open standard for importing reusable rules from external sources. These are community-contributed rules that the agent applies when it determines they are relevant.

To enable or disable Agent Skills:

1. Open Cursor Settings then Rules
2. Find the Import Settings section
3. Toggle Agent Skills on or off

You can also import rules directly from GitHub repositories through Cursor Settings then Rules, Commands then Add Rule then Remote Rule.

Copy-paste prompt for generating rules from your codebase

Open Agent mode and paste:

Analyze this codebase and generate Cursor project rules based on the patterns
you find. Create separate .mdc files in .cursor/rules/ for:
1. Core coding conventions (always apply)
2. Frontend component patterns (auto-attach to src/components/)
3. API route standards (auto-attach to src/api/)
4. Testing conventions (auto-attach to test files)

Use the existing code as examples of what to follow. Keep each rule under 100 lines.

When This Breaks

Rules are not being applied: Check that the file is in .cursor/rules/ (not .cursor/rule/ or the project root). Verify the frontmatter syntax — a missing --- delimiter breaks parsing. Hover the context gauge in the prompt input to see which rules are active.

Rules conflict with each other: The agent tries to follow all active rules simultaneously. If you have contradictory instructions, the behavior is unpredictable. Audit your rules for conflicts.

Rules make the AI too rigid: If the AI refuses to do something reasonable because a rule says not to, either make the rule more specific or add an exception. Rules should guide, not handcuff.

Generated rules are too generic: AI-generated rules often start vague. Treat them as a first draft and edit heavily. Replace “follow best practices” with specific, measurable instructions.

What’s Next

PRD Workflow Turn vague feature requests into systematic implementation plans using Cursor's Plan mode and the PRD methodology.