All guides

Cursor guide

How to write a .cursorrules file

A .cursorrules file tells the Cursor AI editor exactly how to behave in your project - build commands, coding conventions, database schemas, and style choices. Here is the best way to write, structure, and maintain one without it drifting out of date.

Last reviewed: July 2026

What is a .cursorrules file?

A .cursorrules file is a project-level configuration file placed at the root of your workspace. Cursor automatically reads this file to inject system-level instructions into every chat, edit (Cmd+K / Ctrl+K), and Composer session.

It acts as the 'source of truth' for the editor's AI, ensuring it adheres to your preferred coding standards, framework versions, and project structures instead of guessing based on general training data.

The ideal structure for a .cursorrules file

A well-structured .cursorrules file is split into logical sections so the model can parse and follow the rules efficiently. We recommend organizing your instructions under these four pillars:

  • System & Tech Stack: List framework versions (e.g. Next.js 16, React 19) and library dependencies so the AI doesn't write deprecated APIs.
  • Coding Standards: Detail import style preferences (e.g. absolute imports, type imports), state management guidelines, and design system rules.
  • Directory Structure: Map where components, API routes, database schemas, hooks, and tests reside to prevent the AI from creating misplaced files.
  • Verification & Run Commands: Provide exact CLI commands to build, test, and lint. This helps Cursor's terminal agent run tests and fix compilation errors autonomously.

The danger of custom instruction drift

While a .cursorrules file is incredibly powerful, it suffers from a common pitfall: documentation drift. When you upgrade dependencies, refactor folder structures, or add new database tables, the static rules file stays the same.

Over time, the .cursorrules file begins to contradict the actual codebase. When the AI reads outdated rules, it hallucinates legacy patterns, leading to broken imports, compilation errors, and slower developer velocity. Committing to keeping these rules manually sync'd is a chore most fast-moving teams fail to sustain.

Transitioning to a dynamic MCP server

For large codebases, a single static .cursorrules file becomes bloated, eating up the AI's finite context window. The modern approach is to transition from static rules files to a live Model Context Protocol (MCP) server.

Instead of sending a massive text file on every prompt, an MCP server lets Cursor query the codebase's rules and metadata dynamically on demand. This keeps prompts clean, saves token costs, and ensures the AI always has the latest source-of-truth context.

How-to

How to set up a .cursorrules file

  1. 1

    Create the file

    Create a blank text file named `.cursorrules` directly at the root of your project or monorepo workspace.

  2. 2

    Add project instructions

    Write out your tech stack versions, import preferences, directory mapping, and build/test commands using clear, structured Markdown.

  3. 3

    Test with Cursor

    Open Cursor, start a chat or edit prompt, and verify that the AI is referencing the rules from your `.cursorrules` file.

Keep rules in sync automatically

Instead of maintaining static rules files by hand, let Moxie Docs manage your codebase context. Moxie indexes your repository, generates conventions automatically, and exposes them to Cursor via a built-in MCP server - ensuring your AI agent always writes code aligned with your latest conventions without manual updates.

See the Moxie Docs MCP serverCompare plans

FAQ

Frequently asked questions

Quick answers to the questions developers ask about How to write a .cursorrules file.

Keep reading

Related guides

Get started

Give your agents real codebase context.

Connect a repository and Moxie Docs generates living documentation and serves it to your agents over MCP. 14-day free trial, no charge today.

Connect GitHubView pricing