Cursor context files: what to include and what to leave out

Every Cursor session starts cold. The model has no memory of what you built last week, what decisions you made, or what's weird about your codebase. Context files are how you fix that.

Here's what actually belongs in them.

What cursor reads automatically

Cursor reads a few things automatically:

• .cursorrules in your project root
• Files you've opened or pinned in the current session
• Whatever's in the active editor tab

That's it. Everything else, you have to tell it about.

The most useful thing to include

A plain-text description of your architecture. Not your README (too long). Not your package.json (too noisy). A short file that says:

# Project architecture
- Frontend: Next.js App Router, TypeScript
- API: tRPC, routes in /server/routers/
- Database: Postgres via Prisma, schema in /prisma/schema.prisma
- Auth: NextAuth, session in req.session.user
- State: Zustand, stores in /stores/

Five to ten lines. When you @-mention this file in a Cursor prompt, it gives the model enough to make sensible decisions.

Second most useful: a decisions log

Why did you pick this ORM? Why is the user store structured that way? Why is there a weird workaround in /lib/api.ts?

Keep a DECISIONS.md in the root:

## Why Zustand instead of Redux
App is read-heavy, minimal cross-component state. Redux overhead not justified.

## The /lib/api.ts fetchWithRetry wrapper
Fetch doesn't retry on 429s by default. All API calls should go through this.

## Prisma instead of Drizzle
Team is more familiar. Will revisit if we hit performance issues.

When you @-mention this, Cursor stops second-guessing your decisions and starts working within them.

What NOT to include

Don't include large generated files. Lock files, build artifacts, node_modules paths — these eat context and produce nothing useful.

Don't include every open tab. More context isn't better context. Two relevant files beat ten tangential ones.

Don't include files with secrets. Cursor sends context to the API. Treat it like a code review from a contractor — don't share .env.

A .cursorrules tip for context management

Add a line to your .cursorrules:

When I ask about a specific module, read its file before answering. Don't infer behavior from type signatures alone.

This prevents Cursor from confidently hallucinating what a function does based on its name rather than its implementation.

The pattern that works

• ARCHITECTURE.md — 10 lines on structure
• DECISIONS.md — bullets on non-obvious choices
• .cursorrules — rules on how to work in this codebase

Reference these files at the start of any complex task. The result is fewer wrong-direction suggestions and less time course-correcting.

More Cursor patterns at builtbyzac.com/cursor-rules.html.