How to Write a .cursorrules File (With Examples)

A .cursorrules file tells Cursor IDE how to write code for your project. Without it, Cursor uses generic patterns that may not match your conventions. With a good .cursorrules file, Cursor follows your coding style, uses your preferred libraries, and avoids anti-patterns specific to your codebase.

This guide covers everything you need to write an effective .cursorrules file, with real examples from production projects.

What is .cursorrules?

.cursorrules is a plain text file that lives in your project root. Cursor IDE reads it automatically and applies the instructions to all AI interactions — inline completions, chat responses, and CMD+K edits. Think of it as a style guide for your AI pair programmer.

What to Include in .cursorrules

A good .cursorrules file covers: Tech stack with versions (be specific — say "React 18 with Next.js 14 App Router" not just "React"), coding conventions (naming patterns, file organisation, import ordering), preferred libraries (which packages to use for common tasks), anti-patterns (what NOT to do), and testing patterns (framework, test structure, what to test).

Example: Next.js Project

Here is a real .cursorrules file for a Next.js 14 SaaS application: Use TypeScript with strict mode. Use Next.js App Router with server components by default. Only add "use client" when the component needs useState, useEffect, or event handlers. Use Tailwind CSS for all styling, never inline styles or CSS modules. Validate all API inputs with Zod schemas. Use next-safe-action for server actions. Put database queries in repository files under lib/db/. Use named exports for components, default exports only for pages. Error handling: throw AppError from lib/errors.ts, never raw Error. Never use the any type.

Example: Python FastAPI Project

For a Python backend: Use Python 3.12 with FastAPI. Type hints are required on all function signatures. Use Pydantic v2 models for all request/response schemas. Database access through SQLAlchemy 2.0 with async sessions. Use dependency injection via FastAPI Depends() for services. All endpoints must have docstrings with summary and description. Tests use pytest with httpx AsyncClient. Never use print() for logging — use structlog.

Common Mistakes

Being too vague: "Use best practices" tells Cursor nothing. Be specific about which practices and where they apply.

Making it too long: Keep .cursorrules under 200 lines. Cursor has limited context — a bloated rules file dilutes the important instructions.

Listing tools without patterns: Saying "We use React" is not useful. Cursor already knows React. Say "Use server components by default. Only use client components when interactivity is required."

Forgetting anti-patterns: "Do not" rules are often more valuable than "do" rules. If your team has been burned by a particular pattern, tell Cursor to avoid it.

.cursorrules vs agents.md vs CLAUDE.md

.cursorrules is for Cursor's inline completions and chat. agents.md is for Cursor's agent mode (multi-step tasks). CLAUDE.md is for Claude Code. If you use multiple AI tools, you will need separate files for each — they do not read each other's instruction files.

Generate .cursorrules Automatically

If you would rather not write .cursorrules from scratch, Keeborg generates it automatically as part of your project's specification suite. Describe your app idea, select your tech stack, and Keeborg produces a .cursorrules file tailored to your specific project alongside CLAUDE.md, .windsurfrules, and copilot-instructions.md. All files are consistent with each other and ready to export to GitHub.