cursorcursorrulesai-codingguideconfiguration

The Complete Guide to .cursorrules: Configuring Cursor AI for Your Project

Master .cursorrules for Cursor IDE. Examples, templates, and tips for configuring Cursor AI to work perfectly with your codebase.

Hel Rabelo-2026-02-09-10 min read

What is .cursorrules?

.cursorrules is Cursor IDE's project-level configuration file for its AI assistant. When you place a .cursorrules file at the root of your project, Cursor reads it before every AI interaction and uses it to tailor its suggestions, code generation, and refactoring to your specific codebase.

If you have used Cursor without a .cursorrules file, you have been leaving performance on the table. The difference between a Cursor session with and without project-specific rules is dramatic. With the right .cursorrules, Cursor generates code that matches your patterns, follows your conventions, and avoids your known pitfalls.

Where .cursorrules Goes

Place it at the root of your repository, next to your package.json or pyproject.toml. The filename is exactly .cursorrules with no extension. Cursor detects it automatically.

The file uses plain text or markdown formatting. There is no special syntax -- just write your instructions in natural language.

Writing Effective Rules

Code Style Preferences

Tell Cursor exactly how you write code. Be specific about patterns that vary between projects or teams.

Examples:

  • Use functional components with arrow functions, not function declarations
  • Prefer const over let; never use var
  • Use single quotes for strings in TypeScript, double quotes in JSX
  • Destructure props in function parameters: ({ name, age }: Props) not (props: Props)
  • Always type function return values explicitly

    • Framework-Specific Instructions

    If you use a framework with multiple valid patterns, tell Cursor which ones you prefer.

    Next.js examples:

  • Use the App Router, not Pages Router
  • Fetch data in server components using async/await, not useEffect
  • Use next/image for all images, never raw img tags
  • Route handlers go in app/api/[route]/route.ts
  • Use loading.tsx and error.tsx for route-level loading/error states

    • React examples:

  • Use Zustand for global state, not Redux or Context
  • Custom hooks live in src/hooks/ and are prefixed with use
  • Component files export one component each
  • Use React.memo only when profiling shows a performance issue

    • Testing Conventions

    Specify your testing approach so Cursor writes tests that match your existing suite.

    Examples:

  • Use Vitest with React Testing Library
  • Test files live next to their source files: Component.tsx and Component.test.tsx
  • Use describe/it blocks, not test()
  • Mock external dependencies with vi.mock(), not manual mocks
  • Assert user-visible behavior, not implementation details

    • File Organization Rules

    Help Cursor put new files in the right places.

    Examples:

  • Components: src/components/[feature]/ComponentName.tsx
  • Hooks: src/hooks/useHookName.ts
  • Utils: src/lib/[category].ts
  • Types: src/types/[domain].ts
  • API routes: src/app/api/[resource]/route.ts

    • .cursorrules vs CLAUDE.md

    Both files serve the same fundamental purpose: giving your AI coding assistant project-specific context. But they have important differences.

    Format

  • .cursorrules: Plain text or markdown. No formal structure required.
  • CLAUDE.md: Standard markdown. Supports a hierarchy of files at different directory levels.

    • Hierarchy

  • .cursorrules: Single file per project. No inheritance or layering.
  • CLAUDE.md: 5-layer hierarchy from global to per-directory. Child files inherit from parents.

    • Token Awareness

  • .cursorrules: No built-in token counting. You cannot easily see how much context your rules consume.
  • CLAUDE.md: Claude Code shows context usage. TokenCentric can count tokens with the official Anthropic tokenizer.

    • Team Sharing

    Both are plain text files that can be checked into version control. Both become shared team resources when committed to the repo.

    Which to Use

    If you use Cursor, write a .cursorrules. If you use Claude Code, write a CLAUDE.md. If you use both, write both. The content will be similar, but each tool reads only its own file.

    If maintaining multiple files sounds tedious, that is because it is. This is where [TokenCentric](https://tokencentric.app) becomes useful. It shows all your AI config files across all projects in one dashboard, so you can keep them in sync without manually hunting through directories.

    Best .cursorrules Examples

    React / Next.js

  • You are working on a Next.js 14 App Router project with TypeScript and Tailwind CSS.
  • Use server components by default. Only add "use client" when the component needs interactivity, hooks, or browser APIs.
  • Fetch data in server components using async/await. Use React Query in client components for data that needs caching or mutation.
  • Use Tailwind CSS for all styling. Do not create CSS modules or styled-components.
  • Components use PascalCase filenames. Utilities use camelCase.
  • Always handle loading and error states in data-fetching components.
  • Prefer named exports over default exports.

    • Python

  • This is a Python 3.12 project using FastAPI and SQLAlchemy.
  • Use type hints on all function signatures.
  • Use Pydantic v2 models for request/response validation.
  • Database models live in src/models/. API routes live in src/routes/.
  • Use async/await for all database operations.
  • Tests use pytest with pytest-asyncio. Fixtures live in conftest.py.
  • Format code with Black. Sort imports with isort.

    • Go

  • This is a Go 1.22 project using the standard library and SQLC.
  • Follow the standard Go project layout: cmd/, internal/, pkg/.
  • Use interfaces for dependency injection. Define interfaces where they are consumed, not where they are implemented.
  • Error handling: return errors, do not panic. Wrap errors with fmt.Errorf and %w.
  • Tests live next to source files: handler.go and handler_test.go.
  • Use table-driven tests for functions with multiple input/output cases.

    • TypeScript Monorepo

  • This is a Turborepo monorepo with apps in apps/ and shared packages in packages/.
  • Shared types come from @repo/types. Shared UI components from @repo/ui.
  • Each app has its own tsconfig.json extending the root tsconfig.base.json.
  • Use workspace dependencies: "@repo/ui": "workspace:*" in package.json.
  • Run commands from the root: turbo run build, turbo run test.
  • Internal packages use exports field in package.json for clean imports.

    • Common Pitfalls

    Being Too Generic

    "Write clean, maintainable code" tells Cursor nothing it does not already try to do. Be specific about what "clean" means in your project.

    Contradicting Yourself

    If your rules say "use functional components" in one place and show a class component example elsewhere, Cursor will be confused. Audit your rules for consistency.

    Ignoring Token Limits

    Cursor has context limits just like any AI. A massive .cursorrules file eats into the space available for your prompts and code. Keep it focused.

    Not Updating

    When you refactor your project structure, upgrade frameworks, or change conventions, update your .cursorrules. Stale rules cause stale output.

    Managing .cursorrules Across Projects

    If you work on multiple projects, managing .cursorrules files becomes a chore. Each project needs its own rules. Each set of rules needs periodic updates. If you also maintain CLAUDE.md files for Claude Code and copilot-instructions.md for GitHub Copilot, the number of files multiplies quickly.

    [TokenCentric](https://tokencentric.app) was built to solve this exact problem. It scans your development directories, finds every AI config file, and presents them in a unified dashboard. You can edit any file with a Monaco editor (the same one VS Code uses), see real-time token counts, and start new files from built-in templates.

    It is free, open source, and works on macOS and Windows. If you are managing more than a couple of .cursorrules files, it pays for itself in the time you save finding and editing them.

    Conclusion

    A well-crafted .cursorrules file makes Cursor significantly more useful. It transforms generic AI suggestions into code that fits your project's specific patterns and conventions.

    Start with the basics: your tech stack, coding conventions, file organization, and testing approach. Be specific, be concise, and keep it updated. If you manage multiple projects, [TokenCentric](https://tokencentric.app) can help you keep everything in sync.

    Ready to try TokenCentric?

    Free, open-source AI config file manager for your projects.

    Download TokenCentric
    Previous

    AI Coding Assistant Config Files Compared: CLAUDE.md vs .cursorrules vs copilot-instructions.md

    Next

    How to Write an Effective CLAUDE.md File: The Complete Guide