Cursor Rules Advanced Guide: Project-Specific AI Configuration and Team Coding Standards
Why Cursor Rules Are the Most Underused AI Coding Feature
Every developer who uses Cursor has experienced this: you ask it to generate a component, and it produces perfectly valid React code — using class components when your project uses hooks, styled-components when you use Tailwind, and Jest when your test suite runs Vitest. The code works but does not fit your project.
Cursor rules solve this by giving the AI persistent, project-specific context about how your codebase works. A well-configured rules file transforms Cursor from a generic code generator into a tool that understands your tech stack, follows your conventions, and produces code that merges cleanly into your existing patterns.
Despite being one of Cursor’s most powerful features, rules files are underused because most developers either do not know they exist or write overly simple rules that barely scratch the surface. This guide covers advanced configuration techniques for serious development teams.
Rules File Architecture
File Hierarchy and Precedence
Cursor reads rules from multiple locations, with more specific rules taking precedence:
~/.cursorrules # Global: applies to all projects project/.cursorrules # Project root: main project rules project/.cursor/rules # Alternative project rules location project/src/.cursorrules # Directory: overrides for src/ project/src/api/.cursorrules # Subdirectory: API-specific rules
When Cursor generates code in src/api/, it reads all applicable rules files from most general (global) to most specific (src/api/), with later rules overriding earlier ones for conflicting directives.
What Goes Where
Global (~/.cursorrules):
# Personal preferences that apply everywhere - Always use TypeScript strict mode - Prefer named exports over default exports - Use 2-space indentation - Include JSDoc comments on exported functions
Project root (.cursorrules):
# Project-specific stack and conventions - This is a Next.js 14 App Router project - Use Tailwind CSS for all styling - Database: PostgreSQL with Prisma ORM - Testing: Vitest with React Testing Library
Directory-specific (src/api/.cursorrules):
# API layer conventions
- All API routes follow REST conventions
- Use zod for input validation
- Return errors as { error: string, code: string }
- Include rate limiting middleware on all public endpoints
Writing Production-Grade Project Rules
The Rule Template
A comprehensive .cursorrules file addresses seven areas:
# Project: [Name]
## Tech Stack
- Framework: Next.js 14 (App Router)
- Language: TypeScript 5.3+ (strict mode)
- Styling: Tailwind CSS with design tokens from tailwind.config.ts
- State: Zustand for client state, React Query for server state
- Database: PostgreSQL 16 via Prisma 5
- Auth: NextAuth.js v5 with JWT strategy
- Testing: Vitest + React Testing Library + MSW for API mocking
- Package manager: pnpm
## Architecture
- src/app/ — Next.js App Router pages and layouts
- src/components/ — Reusable UI components (shadcn/ui based)
- src/components/ui/ — Base shadcn components (DO NOT modify)
- src/lib/ — Utility functions, shared logic
- src/server/ — Server-only code (actions, services, repositories)
- src/types/ — Shared TypeScript type definitions
- prisma/ — Database schema and migrations
## Coding Conventions
- Use functional components with hooks exclusively
- Prefer named exports: export function MyComponent() {}
- Use "use client" directive only when client interactivity is required
- Default to Server Components in the App Router
- Use absolute imports: @/components/Button (not ../../../components/Button)
- Error handling: use Result pattern from @/lib/result.ts
- Never use `any` type — use `unknown` and narrow with type guards
## Naming Conventions
- Components: PascalCase (UserProfile.tsx)
- Hooks: camelCase with use prefix (useUserProfile.ts)
- Utilities: camelCase (formatCurrency.ts)
- Types/Interfaces: PascalCase with descriptive names (UserProfileProps)
- API routes: kebab-case in URL, camelCase in handler names
- Database: snake_case for table and column names
- Environment variables: UPPER_SNAKE_CASE
## Component Patterns
- Props interface defined above component: interface ButtonProps { ... }
- Destructure props in function signature
- Use forwardRef for components that need ref access
- Composition pattern: compound components for complex UI
- Loading states: use Suspense boundaries with skeleton fallbacks
## Testing Patterns
- Test file location: __tests__/ComponentName.test.tsx
- Use describe/it blocks with arrange-act-assert pattern
- Mock external services with MSW handlers
- Test user behavior, not implementation details
- Minimum: test the happy path and one error case per component
## Dependencies
- DO NOT add new npm packages without explicit instruction
- Prefer existing utilities in src/lib/ before creating new ones
- If a utility exists in lodash, implement it locally (no lodash dependency)
- Approved packages: zod, date-fns, clsx, tailwind-merge
## Git Conventions
- Commit messages: conventional commits (feat:, fix:, refactor:, test:, docs:)
- Branch naming: feature/PROJ-123-short-description
- PR descriptions must include: what changed, why, and how to test
Framework-Specific Rule Examples
Next.js App Router Rules
## Next.js App Router Conventions - page.tsx files export default async functions (Server Components) - layout.tsx files wrap children and provide shared UI - loading.tsx provides Suspense fallback - error.tsx provides error boundary (must be "use client") - Use generateMetadata() for SEO on each page - API routes go in app/api/[resource]/route.ts - Server Actions go in src/server/actions/[domain].ts - Use revalidatePath() for cache invalidation, not revalidateTag() - Middleware in middleware.ts for auth checks and redirects
Django + DRF Rules
## Django Conventions - Apps follow domain-driven structure: apps/users/, apps/orders/ - Models use TimeStampedModel base class from apps/core/models.py - Serializers: one per model + separate request/response serializers - Views: use ViewSets, not function-based views - URLs: router.register() in each app's urls.py - Permissions: custom permission classes in apps/core/permissions.py - Testing: pytest-django, factory_boy for fixtures - Migrations: always review before committing - Settings: split into base.py, development.py, production.py
Spring Boot Rules
## Spring Boot Conventions
- Package structure: controller, service, repository, dto, entity, config
- Controllers: @RestController, return ResponseEntity<>
- Services: @Service with constructor injection (no @Autowired on fields)
- Repositories: extend JpaRepository, custom queries in @Query annotations
- DTOs: Java records for request/response, separate from entities
- Validation: @Valid on request DTOs, custom validators in validation/
- Exception handling: @ControllerAdvice in GlobalExceptionHandler
- Testing: @SpringBootTest for integration, Mockito for unit tests
- Profiles: dev, staging, prod in application-{profile}.yml
Monorepo Rules Management
Per-Package Rules
For monorepos with multiple packages:
# Root .cursorrules ## Monorepo Structure - Package manager: pnpm with workspaces - packages/web — Next.js frontend - packages/api — Express backend - packages/shared — Shared types and utilities - packages/mobile — React Native app ## Cross-Package Rules - Shared types MUST be defined in packages/shared - Never import directly between web and api (use shared) - Each package has its own tsconfig.json extending root - Database types are auto-generated — do not manually edit prisma/generated/
# packages/web/.cursorrules ## Frontend Rules - Next.js 14 App Router conventions - Tailwind CSS for styling - Import shared types from @repo/shared - Use React Query for API calls to the backend - Environment: NEXT_PUBLIC_ prefix for client-accessible vars
# packages/api/.cursorrules
## Backend Rules
- Express with TypeScript
- Prisma ORM for database access
- Import shared types from @repo/shared
- Use zod for request validation
- JWT authentication middleware on all /api/ routes
- Response format: { data: T } or { error: string, code: string }
Rules for AI Behavior Control
Controlling Verbosity
## Response Style - When generating code, include only the code. No explanations unless asked - When explaining code, be concise — focus on the "why", not the "what" - Do not add comments to obvious code (e.g., "// import React") - Add comments only where the logic is non-obvious
Controlling Scope
## Scope Rules - When asked to modify a file, only change what was requested - Do not refactor surrounding code unless explicitly asked - Do not add features beyond what was requested - If you notice a bug while working on something else, mention it but do not fix it unless asked
Controlling Quality
## Quality Gates - Every new function must have a TypeScript return type annotation - Every new component must handle loading and error states - Every new API endpoint must have input validation - Every new database query must have an index strategy comment - Never use string concatenation for SQL queries
Team Adoption Strategy
Rolling Out Rules to a Team
- Start with a draft: one senior engineer writes the initial rules based on existing conventions
- Team review: share the rules file in a PR — everyone comments on accuracy and completeness
- Trial period: use the rules for two weeks without enforcement, collect feedback
- Refine: update rules based on where Cursor output did not match expectations
- Commit: merge the rules file into the repository
- Maintain: update rules when conventions change, review quarterly
Rules as Living Documentation
The .cursorrules file becomes the single source of truth for coding conventions. Unlike CONTRIBUTING.md (which nobody reads), rules are actively enforced by the AI that developers interact with every day. When a convention changes, update the rules file and every team member immediately benefits.
Common Mistakes and Fixes
Mistake 1: Rules Too Vague
Bad: “Write clean code” Good: “Use early returns to reduce nesting. Maximum function length: 30 lines. Extract complex conditions into named boolean variables.”
Mistake 2: Rules Contradict Each Other
Bad: “Use Server Components by default” AND “Always add ‘use client’ to components” Good: “Default to Server Components. Use ‘use client’ only for: event handlers, useState, useEffect, browser APIs.”
Mistake 3: Rules Reference Non-Existent Patterns
Bad: “Follow the BaseService pattern in src/lib/base-service.ts” (file does not exist) Good: “Follow the UserService pattern in src/server/services/user.service.ts” (file exists and is a good example)
Mistake 4: Not Updating Rules After Major Changes
After a framework upgrade, migration, or architectural change, immediately update the rules file. Stale rules are worse than no rules — they teach the AI the wrong patterns.
Frequently Asked Questions
Do .cursorrules files work with Cursor’s free tier?
Yes. Rules files are supported on all Cursor plans including the free tier.
Can I use both .cursorrules and .cursor/rules?
Yes. Both locations are read. If both exist, they are merged with directory-specific rules taking precedence.
How long can a rules file be?
There is no hard limit, but extremely long rules files (10,000+ words) may reduce the context available for actual code. Keep rules concise and focused — 500-2000 words is the practical sweet spot.
Do rules affect Cursor Tab completion?
Yes. Rules influence all AI features in Cursor: Tab completion, inline chat (Cmd+K), chat panel, and Composer.
Can I disable rules temporarily?
You cannot disable rules through the UI. To temporarily bypass rules, rename the file (e.g., .cursorrules.bak) and rename it back when done.
Should I commit .cursorrules to git?
Yes. Committing rules ensures all team members get the same AI behavior. This is one of the primary benefits of project-level rules.