Engineering

How to Write Cursor Rules

Give Cursor a project context profile to load on every request — stack conventions, glossary, and never-assume rules — saved as your .cursorrules file.

Open in Project Context Builder

Overview

Cursor is only as good as the context it has, and an empty repo gives it none — so it guesses your conventions. This builds a project context profile aimed at Cursor: the overview, the stack-inferred conventions, a glossary, and the never-assume rules, with the install note pointing at your repo-root .cursorrules file. The example loads a TypeScript React/Node app. Open it in the Project Context Builder and switch the project details to your own; the Cursor output target writes the rules in the right place.

How to use this resource

Open the example in the tool

It loads with realistic inputs already filled in.
Swap in your own details

Adjust the inputs and options to match your case.
Generate and copy

Produce the output and paste it where you need it.

Why This Works

Cursor reads repo rules on every request, so the context travels with the code for the whole team
Stack detection turns "React, TypeScript, Postgres" into the conventions those tools imply, automatically
The never-assume rules stop Cursor guessing the things it gets wrong most often

Best for

Setting up Cursor for an existing repo
Sharing one rules file across a team
Stopping Cursor from breaking project conventions

Not for

A one-off task prompt — use a template instead
Defining an AI persona — use the System Prompt Generator

FAQ

Where does the generated Cursor rules file need to go in my repo?

At the repo root as .cursorrules (or .cursor/rules/project.mdc); the profile's own header says save it there "so Cursor loads it for every request." Project Context Builder writes the rules for that target, and because Cursor reads repo rules on each request, the file travels with the code so every teammate gets the same context.

What stops Cursor from guessing my project's conventions with this file?

The ## Never Assume block spells out the guesses to avoid: do not add a dependency without checking package.json, do not assume the schema before writing a query, do not hand-write SQL when a Prisma query exists. Paired with ## Team Conventions inferred from the stack (React, Express, Prisma, TypeScript), it turns "the codebase uses function components" into an explicit rule rather than a hope.

Is a .cursorrules file the right place to define how the AI should behave, like tone and escalation?

It is not; this profile is project KNOWLEDGE, not behavior, and the AI USAGE NOTES say for a task persona (role, tone, escalation) build a System Prompt in the System Prompt Generator instead. The .cursorrules file carries durable facts like the Glossary and "all dates are stored and compared in UTC"; continuing an in-progress task in a new chat is the Context Handoff Builder's job.

Customize This Resource

Opens this project in Project Context Builder. Build to get the full context profile — then adjust the mode, stack, glossary, and output target.

Open in Project Context Builder

Prompt Template

Copy it as-is, or use Open in Project Context Builder to load it pre-filled and customize it with your own context.

# Project Context: Aspen

> Save this at your repo root as `.cursorrules` (or `.cursor/rules/project.mdc`) so Cursor loads it for every request.

## Project Overview
Aspen is a TypeScript web app — a React front end and a Node API — that lets small teams plan and track product roadmaps.

## Core Facts
- Project type: Software Project
- Primary stack: React, Express, Node.js, PostgreSQL, Prisma, TypeScript
- This is a software codebase — correctness, readability, and maintainability come before cleverness.

## Tech Stack
- React
- Express
- Node.js
- PostgreSQL
- Prisma
- TypeScript

## Team Conventions
- Components are function components with hooks.
- Every API route has an integration test.
- No business logic in React components.
- Function components with hooks only — no class components; keep components pure and side effects in effects. (React)
- Keep route handlers thin; put logic in services and use middleware for cross-cutting concerns. (Express)
- Prefer async/await over callbacks; never block the event loop with sync I/O in request paths. (Node.js)
- Change the schema through `schema.prisma` and migrations; use the generated client, not raw SQL, unless necessary. (Prisma)
- No `any` — prefer `unknown` with narrowing; keep `strict` mode on and types honest. (TypeScript)

## Naming Rules
- Database: snake_case for tables and columns; plural table names. (PostgreSQL)
- camelCase for variables and functions, PascalCase for types and components. (TypeScript)

## Architecture Principles
- Keep modules focused — a file or function should do one thing well.
- Prefer clarity over abstraction; introduce indirection only when duplication has actually appeared.
- Changes should come with the test that proves them.

## Glossary
- **Roadmap** — an ordered set of planned initiatives.
- **Initiative** — one planned unit of work with an owner.

## Always Remember
- All dates are stored and compared in UTC.
- This profile is the source of truth for project facts — prefer it over general assumptions.

## Never Assume
- Do not introduce a new dependency without checking package.json first.
- Do not assume a component is class-based — the codebase uses function components and hooks.
- Do not assume the schema — reference the migrations or schema file before writing a query.
- Do not hand-write SQL when a Prisma query exists — and do not edit generated client code.
- Do not assume a value's type — check the type definition before changing a signature.
- Do not assume how a module is used elsewhere — check the call sites before changing a signature.
- When a fact is missing from this profile, ask — do not invent it.

## AI Usage Notes
- Cursor reads project rules from the repo, so this travels with the code and every teammate gets the same context.
- This profile is project KNOWLEDGE, not behavior — for a task persona (role, tone, escalation rules), build a System Prompt in the System Prompt Generator.
- It is durable project identity, not work state — to continue an in-progress task in a new chat, use the Context Handoff Builder.
- Profile completeness: 100/100 (Complete) — bracketed gaps, if any, mark missing info that was never invented.

More resources from Project Context Builder

Resource

Build Project Memory for AI

Stop re-explaining your project in every new chat. Capture it once as a context profile the AI keeps across every conversation — stack-inferred conventions and all.

Prompt Engineering

Resource

Create an AI Project Profile

A reusable profile that tells AI everything constant about your project — type, stack, conventions, glossary, architecture principles, and the rules it must never guess.

Prompt Engineering

Resource

AI Onboarding Context for an Existing Codebase

Onboard AI to a codebase the way you'd onboard a new hire: what it is, how it's built, the rules that aren't written down, and the things never to assume.

Engineering

Resources that pair well

Resource

AI Session Handoff — Shift Change for Working Sessions

End a working session like a shift change, not an abandonment: state captured, decisions logged, next step named — ready for the next session to pick up.

Prompt Engineering

Resource

Bug Triage Assistant

Convert scattered bug notes, Slack messages, or user complaints into structured engineering tasks with reproduction steps, severity, and root cause hypothesis.

Engineering

Resource

Convert a Conversation to a Prompt — the Full Anatomy

What a converged conversation contains: a rejected voice, an accepted framing, a hard constraint, a format decision, and a final-version moment — each mapped to its prompt section.

Prompt Engineering

Related tools

Tool

Project Context Builder

Define what AI should permanently know about your project — stack conventions, glossary, and never-assume rules in a profile you paste once.

Context Tools

Tip: Save time by exploring related resources and tools that integrate with this resource.