Cursor’s rules file is a plain text file that defines persistent instructions the AI follows across all sessions in a project. Without it, you re-explain your conventions every conversation — your preferred error handling style, the libraries you use, the architecture constraints that should not be violated. With a well-written rules file, the AI generates code that fits your project from the first response. This guide covers what belongs in a rules file, how to structure it, and the patterns that make a real difference to output quality.
What a Rules File Is
In Cursor, a rules file is a .cursorrules file in the root of your project (or configured via Settings → Rules for AI). Its content is injected into the system prompt of every AI interaction in that project. Anything you write there is always present as context for the model — it is always-on background instruction, not something you need to paste into each conversation. Windsurf has an equivalent file called .windsurfrules; GitHub Copilot has custom instructions configurable per repository. The concept is the same across all tools: persistent, project-scoped AI instructions.
Figure 1 — Rules file anatomy: what goes where
Verifying the Rules File Is Being Used
After writing or updating a rules file, it is worth verifying that Cursor is actually reading and applying it. A quick test: ask the AI a question whose answer should differ based on the rules file — “what HTTP library should I use for making requests in this project?” If it answers “httpx” (as specified in your rules file) rather than the default “requests,” the file is being applied. If it answers generically, check that the file is in the correct location (.cursorrules in the project root, or the path configured in settings), that it is not empty, and that Cursor has indexed the project. Occasionally after adding or significantly editing the rules file, closing and reopening the Cursor window ensures the new content is picked up. This quick verification step saves confusion when later AI responses seem to ignore project conventions you thought were specified.
Rules files are also worth reviewing when you notice the AI making consistent errors that should have been prevented by your instructions. If the AI keeps using requests despite your rules file specifying httpx, the instruction may be phrased too weakly — “prefer httpx” is weaker than “always use httpx, never requests.” Iterating on rule phrasing based on observed failures is the most reliable way to improve rules file effectiveness over time.
What to Put in a Rules File
The rules file should contain anything that would otherwise need to be repeated across many conversations. Language and runtime: “This project uses Python 3.12 and requires compatibility with Python 3.11.” Dependency constraints: “Use httpx for HTTP requests, not requests. Use pydantic v2 for data models. Do not add new dependencies without noting them explicitly.” Code style: “Functions should be short — prefer splitting anything over 30 lines. Use type annotations on all function signatures. Prefer functional patterns over class-based ones where natural.” Error handling: “Always handle errors explicitly — no bare except clauses. Log errors with structured JSON logging using the project’s logger, not print statements.” Architecture: “Database access happens only in the repository layer. Do not write SQL in route handlers or service functions.” Testing: “Every new function should have a corresponding unit test. Use pytest. Mock external dependencies at the boundary.” These instructions make every AI response more consistent with your actual codebase without any per-conversation overhead.
Project Context the AI Needs
Beyond coding conventions, the rules file is the right place for project context that shapes what good code looks like. A brief description of what the project does and who uses it helps the AI make appropriate tradeoffs — a high-traffic production API has different quality standards than an internal data processing script. Key architectural decisions and why they were made: “We use event sourcing for the order system — all state changes are events, not direct mutations. This is intentional, do not suggest simplifying it.” Technology choices that might seem unconventional: “We use Zig for the performance-critical data pipeline components, not Python. Do not suggest rewriting these in Python.” Known technical debt to avoid compounding: “The auth module is being refactored — do not add new functionality there, route new auth needs through the new auth service.” This project context prevents the AI from making suggestions that are technically correct but architecturally wrong for your situation.
What Not to Put in a Rules File
The rules file is injected into every prompt, so bloated rules files waste tokens and dilute the model’s attention. Avoid putting task-specific instructions in the rules file — those belong in individual conversations. Avoid duplicating information that is already clear from the codebase — if you consistently use httpx throughout the project, you probably do not also need to specify it in the rules file. Avoid instructions that are too vague to act on: “write clean code” and “be careful about security” do not shape behaviour; “never interpolate user input directly into SQL queries — always use parameterised queries” does. Aim for a rules file that is 100–400 words — specific enough to be useful, concise enough not to clutter every context window.
A Minimal Effective Rules File Example
Here is the shape of a rules file that improves output quality without becoming a wall of text. Start with a one-sentence project description: “A FastAPI REST API serving a B2B SaaS product for fleet management.” Add the critical technology constraints: “Python 3.12, FastAPI, SQLAlchemy 2.0 (async), PostgreSQL, pytest, httpx. Do not add new dependencies without flagging them.” Add the style rules that differ from defaults: “Type-annotate all functions. Use async/await throughout. Return Pydantic models from all endpoints — never raw dicts. Errors should raise custom exception classes defined in exceptions.py.” Add the architecture rules that prevent common mistakes: “Database queries belong in repository classes in the db/repositories/ directory. Business logic belongs in service classes in services/. Route handlers should be thin — call a service method and return the result.” Add the testing expectation: “New functions need pytest unit tests. Use pytest-asyncio for async tests. Mock the database using the project’s TestDatabase fixture.” That is a complete, actionable rules file under 150 words.
Language-Specific Rules Patterns
Different languages and frameworks have different common failure modes that are worth addressing in rules files. For TypeScript React projects: “Use TypeScript strict mode. Prefer function components with hooks over class components. Use React Query for server state and Zustand for client state — do not use Redux. All API calls go through the api/ directory, never directly from components.” For Python data science: “Use pandas 2.0 API — avoid deprecated methods. Prefer vectorised operations over iterrows(). Save intermediate results to parquet, not CSV. Use type hints even in notebooks.” For Go: “Return errors, do not panic. Use the project’s structured logger, not fmt.Println. Interfaces belong in the package that uses them, not the package that implements them.” Patterns specific to your language’s common pitfalls are among the highest-value additions to a rules file because the AI’s defaults are often shaped by older patterns in its training data.
Keeping Rules Files Current
Rules files need maintenance as projects evolve. When you upgrade a major dependency, update the version in the rules file. When you establish a new architectural pattern, add it. When a rule is consistently being ignored or producing unexpected results, rewrite it more specifically — vague rules produce vague compliance. A good habit is to review the rules file whenever you start a new significant feature and ask whether there is anything about the upcoming work that the AI will get wrong without explicit guidance. The few minutes spent updating the rules file before a multi-hour coding session typically pays back through more accurate first-draft code throughout the session.
Team Rules vs Personal Rules
Cursor supports both project-level rules (in .cursorrules, committed to the repository and shared by the whole team) and user-level rules (in Settings, applying to all projects for that user). Project-level rules should contain team conventions, architecture decisions, and technology constraints that everyone should follow. User-level rules should contain personal preferences — response length, explanation style, how much context to include in answers — that are specific to your working style. Keeping these separated means team members share the project context without imposing their personal AI interaction preferences on each other. Committing the .cursorrules file to version control also means new team members get consistent AI behaviour from day one without any setup beyond installing Cursor.
A well-maintained rules file is one of the highest-leverage investments in an AI-assisted coding workflow. It takes an hour to write and saves time in every subsequent coding session by eliminating the need to re-specify context and by producing more accurate, more consistent first-draft code. Treat it as a living document — update it when conventions change, extend it when you notice the AI making the same wrong assumption repeatedly, and share it with your team so everyone benefits from the accumulated project context.