If you have been building with Cursor for a while, you know it crossed a line somewhere around late 2025. It stopped feeling like an editor with AI bolted on and started feeling like a genuine pair programmer that happens to never need a coffee break.
This guide covers how to actually build production-grade applications with Cursor in 2026, not the surface-level "just press Tab to autocomplete" stuff. We're talking about multi-file agent workflows, .cursorrules architecture, MCP server integrations, context management at scale, and the mental model shifts that separate developers who get 2x productivity from those who get 10x.
What Cursor Actually Is in 2026 (and What Changed)
Cursor started as a VS Code fork. That's still true. But what it's become is more accurately described as an AI-native development environment where the editor is the secondary concern and the AI reasoning layer is the primary one.
The big changes over the last 18 months:
Agent mode became genuinely reliable. Earlier versions of Cursor's agent would confidently make changes across multiple files, break something three files away, and then confidently fix the wrong thing. The 2025/2026 versions have significantly better cross-file reasoning. The agent can hold the context of a reasonably large codebase, understand how changes propagate, and catch its own mistakes before you do.
MCP (Model Context Protocol) integrations arrived. Cursor now supports MCP servers natively, which means your AI assistant can reach out to external services, query your database schema in real time, read from Notion docs, check your Supabase tables, or call your own internal APIs as part of a coding session. This is a bigger deal than it sounds. We'll get into it.
.cursorrules became essential architecture. Most serious Cursor users now treat their .cursorrules file the way they treat package.json. It's not optional configuration. It's the foundation of how your AI collaborator understands your project.
Long-context models changed what's possible. With models handling hundreds of thousands of tokens, Cursor can now index and reason about entire codebases that would have overwhelmed earlier systems. Large-scale refactors, cross-cutting changes, and architectural reasoning across a monorepo are genuinely tractable now.
Setting Up Cursor for Serious Development
Installation and Model Selection
Download from cursor.com. The Pro plan is worth it if you're using this for real work. The difference in API limits and model access between free and Pro becomes obvious within a week.
On model selection: Cursor lets you choose which underlying model powers your completions and chat. In 2026, the practical options are Claude Sonnet (fast, strong code reasoning, excellent for most tasks), Claude Opus (slower, more expensive, better for complex architectural problems), and GPT-4o (solid alternative, slightly different strengths). Most experienced Cursor developers run Sonnet as default and switch to Opus for architecture sessions.
Set your model in Cursor Settings > Models. You can set different defaults for completions versus Composer.
Essential Settings to Change Immediately
Open Cursor Settings (not VS Code settings) and configure:
AI > Codebase Indexing: ON
AI > Auto Index: ON
AI > Include .gitignore'd files: OFF (unless you have a specific reason)
Features > Composer: ON
Features > Agent: ON
Enable Privacy Mode if you're working on proprietary code. This prevents your code from being used for training. Most companies working with Cursor enterprise have this enforced at the org level.
The Codebase Index
Cursor indexes your codebase and uses this index to give the AI context about your project structure without you having to paste files manually. The index is what makes @codebase queries work well.
For the index to be useful, a few things matter:
Keep your .gitignore clean. Cursor respects it, and you don't want node_modules or build artifacts cluttering the index with noise.
Add a .cursorignore file for anything the AI shouldn't see that isn't in .gitignore:
# .cursorignore
*.log
*.lock
dist/
coverage/
.env*
Re-index explicitly after major structural changes: Cursor: Rebuild Index from the command palette.
.cursorrules: The Foundation You Can't Skip
The .cursorrules file lives at your project root. It's a plain text file that gets injected into every AI conversation in that project as persistent system-level context. Think of it as briefing your pair programmer on the project before they touch a single file.
A weak .cursorrules looks like this:
Use TypeScript. Follow best practices. Write clean code.
This is almost useless. The AI already knows TypeScript and "best practices" is context-free.
A strong .cursorrules looks like this:
# Project: TaskFlow API
## Stack
- Runtime: Node.js 22 with TypeScript 5.4
- Framework: Hono (not Express, not Fastify)
- Database: PostgreSQL 16 via Drizzle ORM (not Prisma)
- Auth: Better Auth v1
- Validation: Zod throughout, no exceptions
- Testing: Vitest, not Jest
- Deployment: Fly.io
## Architecture
- Monorepo structure: /apps/api, /apps/web, /packages/shared
- All shared types live in /packages/shared/types
- Database schema lives in /apps/api/src/db/schema.ts
- Never define types inline in route handlers, always import from shared
## Code Style
- Prefer named exports over default exports everywhere
- No any types. Use unknown and narrow properly.
- Error handling: always use Result types, never throw from business logic
- All async functions must have explicit return types
- Environment variables: always validate with Zod at startup in /apps/api/src/env.ts
## Patterns We Use
- Repository pattern for all database access
- Service layer between routes and repositories
- All HTTP errors use our custom AppError class in /packages/shared/errors.ts
## Patterns We Do NOT Use
- No class components in the frontend
- No callbacks, always async/await
- No var, only const and let
- No console.log in committed code, use our logger utility
## When Adding New Features
1. Define the types in /packages/shared/types first
2. Update the database schema if needed, then run migrations
3. Write the repository method
4. Write the service function
5. Add the route handler
6. Write tests before considering the feature complete
## Important Context
- This is a multi-tenant SaaS. Every database query must scope to the authenticated user's organisationId
- We use RLS (Row Level Security) in Postgres as a second layer, but don't rely on it as the only guard
- Rate limiting is handled at the middleware layer in /apps/api/src/middleware/rateLimit.ts
Notice what this does. It tells the AI exactly which libraries to use and which to avoid, explains the architectural decisions that affect every file, documents the patterns the team has committed to, and flags the critical security consideration (multi-tenancy) that can't be left to inference.
When you have a .cursorrules file this detailed, you stop getting suggestions that reach for Prisma when you're using Drizzle, or that try to import from packages that aren't in your stack. The AI's suggestions become coherent with your actual project rather than generic TypeScript.
.cursorrules for Different Project Types
For a Next.js App Router project:
## Routing
- Always use App Router, never Pages Router
- Server Components are the default. Only add 'use client' when you need interactivity or browser APIs
- Data fetching belongs in Server Components, not useEffect
- Loading states use loading.tsx files, not manual loading state management
- Error states use error.tsx with 'use client' directive
## State
- Zustand for global client state
- React Query (TanStack Query) for server state and caching
- No Redux under any circumstances
## Styling
- Tailwind CSS only
- shadcn/ui components as the base layer, customised as needed
- No styled-components, no CSS modules
For a Python FastAPI project:
## Stack
- Python 3.12
- FastAPI with async throughout
- SQLAlchemy 2.0 (async) with Alembic for migrations
- Pydantic v2 for all schemas
- pytest with pytest-asyncio for tests
## Conventions
- All route handlers are async
- Dependency injection via FastAPI's Depends()
- No business logic in route handlers, always delegate to service layer
- Type hints are mandatory on all function signatures
- Use Python 3.10+ union types (X | None) not Optional[X]
Cursor's Core Features and How to Actually Use Them
Tab Completion
Everyone knows about Tab. The useful thing to know is when not to trust it.
Tab completion is probabilistic. It's predicting the most likely continuation of your code based on what it can see. It's excellent when you're writing predictable patterns: implementing an interface, filling out CRUD operations, writing test cases for a pattern that's already in the file.
It's unreliable for: security-sensitive code, complex business logic, anything that requires understanding state that isn't visible in the current context. In these cases, dismiss the suggestion and use Composer instead.
Useful shortcut: Ctrl+Right accepts the next word of a suggestion rather than the whole thing. This is how you use suggestions as a starting point rather than accepting them wholesale.
Cmd+K (Inline Edit)
Select a block of code, press Cmd+K, describe what you want changed. This is faster than Composer for contained changes to a single function or component.
Where this shines: refactoring a function to use a different approach, rewriting a component to match a new design spec, converting synchronous code to async, adding error handling to an existing function.
Where to use Composer instead: when the change will require touching more than one file, when you need to explain architectural context, when you're doing something the AI might get wrong and you want to be able to discuss it.
Composer (The Main Event)
Open Composer with Cmd+I. This is where serious development happens with Cursor.
Composer is a multi-turn conversational interface that can make changes across multiple files simultaneously. It shows you diffs before applying them, lets you accept or reject individual file changes, and maintains conversation history so you can iterate.
The key mental model for Composer: you are writing a specification, not a request. The more precise and complete your specification, the better the output. Vague requests produce vague code.
Bad Composer prompt:
Add authentication to the app
Good Composer prompt:
Add JWT authentication to the API. Use Better Auth which is already installed. Create a POST /auth/login route that accepts email and password, validates credentials against the users table using bcrypt, and returns a signed JWT with userId and email in the payload. JWT secret should come from process.env.JWT_SECRET. Create a middleware function in src/middleware/auth.ts that validates the JWT on protected routes and attaches the decoded user to the context. Apply this middleware to all routes except /auth/login and /auth/register.
The second prompt takes 30 more seconds to write and saves you several rounds of back-and-forth corrections.
Context symbols in Composer:
-
@filereferences a specific file: "Update the auth middleware to also check@src/middleware/rateLimit.tsis applied before it" -
@folderreferences a directory: "Review all components in@src/components/uiand ensure they all accept a className prop" -
@codebasequeries your indexed codebase: "Where in@codebasedo we currently handle database connection errors?" -
@websearches the web inline: "Implement this using the pattern from@web https://docs.example.com/api" -
@docsreferences indexed documentation (you can add your own docs to Cursor's doc index)
Agent Mode
Enable with the toggle in Composer. Agent mode gives Cursor permission to make multiple sequential changes, run terminal commands, read error output, and self-correct without asking for confirmation at each step.
This is powerful and requires some trust. Things to know:
Agent mode can run terminal commands. It will tell you what it's running. You can interrupt at any point. The first few times you use it, watch what it does. It will sometimes run npm install for a package you didn't want, or run a migration you weren't ready for.
Agent mode is best for: setting up new features end-to-end, large refactors, debugging sessions where you want it to read error logs and iterate, scaffolding boilerplate for a new module.
It's less appropriate for: anything touching production, changes to authentication or security logic, database migrations (review these manually), changes to CI/CD configuration.
A practical rule: let the agent work, but treat its terminal commands the way you'd treat a junior dev running things on your machine. Watch what it does, understand each step.
MCP Integrations: Cursor's Biggest Unlock
MCP (Model Context Protocol) lets Cursor's AI reach outside the editor to external data sources and services. The practical implications are significant.
Setting Up MCP in Cursor
Edit your Cursor settings JSON (Cmd+Shift+P > "Open Cursor Settings JSON"):
{
"mcpServers": {
"supabase": {
"command": "npx",
"args": ["-y", "@supabase/mcp-server-supabase@latest"],
"env": {
"SUPABASE_URL": "https://yourproject.supabase.co",
"SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key"
}
},
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres"],
"env": {
"POSTGRES_CONNECTION_STRING": "postgresql://user:pass@localhost:5432/mydb"
}
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "your-token"
}
}
}
}
What MCP Changes in Practice
Database-aware code generation. With a Postgres or Supabase MCP server connected, Cursor can query your actual schema before writing database code. Instead of generating code that assumes a schema, it reads your real tables, columns, and relationships. The code it produces matches your actual database rather than a guess at it.
Prompt example:
"Check the current schema and write a Drizzle query that joins users, organisations, and memberships to return all users in a given organisation with their role"
Without MCP: Cursor guesses your column names and might get them wrong. With MCP: it reads the actual schema and writes accurate code.
GitHub integration for context. With GitHub MCP, you can reference issues and PRs directly in Composer:
"Implement the feature described in GitHub issue #247"
Cursor reads the issue, understands the requirement, and generates the implementation. For teams that write detailed issue specs, this becomes a significant workflow improvement.
Documentation servers. You can run MCP servers that expose your internal documentation to Cursor. If your team maintains ADRs (Architecture Decision Records) or internal API docs, making these available via MCP means the AI references your actual decisions rather than inventing patterns.
Building a Simple MCP Server
If you have internal tools or APIs you want Cursor to access, building a simple MCP server is straightforward:
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
const server = new McpServer({
name: "internal-api",
version: "1.0.0"
});
// Expose a tool that Cursor can call
server.tool(
"get_feature_flags",
"Returns current feature flags for the application",
{},
async () => {
// Fetch from your internal service
const flags = await fetchFeatureFlags();
return {
content: [{
type: "text",
text: JSON.stringify(flags, null, 2)
}]
};
}
);
server.tool(
"get_api_schema",
"Returns the OpenAPI schema for a given service",
{ service: z.string().describe("Service name: users, payments, or notifications") },
async ({ service }) => {
const schema = await fetchOpenAPISchema(service);
return {
content: [{
type: "text",
text: JSON.stringify(schema, null, 2)
}]
};
}
);
const transport = new StdioServerTransport();
await server.connect(transport);
Once registered in your Cursor config, the AI can call get_feature_flags or get_api_schema before generating code that depends on them. It stops guessing at things it can look up.
A Real Project Walkthrough: Building a SaaS API from Scratch
Let's build a real thing. A multi-tenant task management API with authentication, proper data isolation, and a REST interface. We'll do this with Cursor from blank directory to working endpoints.
Project Setup
Start with a Composer session. Open a blank directory, open Composer, and prompt:
Scaffold a new Hono API project with the following setup:
- TypeScript 5.4, Node.js 22
- Hono as the HTTP framework
- Drizzle ORM with PostgreSQL
- Better Auth for authentication
- Zod for validation
- Vitest for testing
- Biome for linting and formatting (not ESLint/Prettier)
Create the full project structure:
src/
db/
schema.ts
index.ts
migrations/
routes/
auth.ts
tasks.ts
services/
taskService.ts
middleware/
auth.ts
lib/
errors.ts
logger.ts
env.ts
index.ts
Include a package.json with all dependencies, a tsconfig.json configured for Node.js 22, a biome.json, and a .env.example file with all required environment variables documented.
Agent mode will scaffold the entire structure. Review what it created before moving on. Check package.json to verify all packages are present, check tsconfig.json for sensible settings, read env.ts to see how it's handling environment validation.
Writing Your .cursorrules
Before generating any real code, write your .cursorrules based on what the scaffolding created:
# TaskFlow API
## Stack (exact versions matter)
- Hono 4.x with TypeScript
- Drizzle ORM (NOT Prisma, NOT TypeORM)
- PostgreSQL 16
- Better Auth for sessions/JWT
- Zod for all validation
- Vitest for tests
- Biome for linting
## Architecture
- Repository pattern: all DB access in /src/db/repositories/
- Service layer: business logic in /src/services/
- Route handlers are thin: validate input, call service, return response
- Never write raw SQL, always use Drizzle query builder
## Multi-tenancy Rules (critical)
- Every table that holds user data has an organisationId column
- Every query must include a WHERE organisationId = ? clause
- Never trust client-provided organisationId, always derive from the authenticated session
- The auth middleware attaches { userId, organisationId } to context.var
## Error Handling
- Use the AppError class from /src/lib/errors.ts
- Business logic throws AppError, never generic Error
- Route handlers catch AppError and return appropriate HTTP status
- All unexpected errors get logged and return 500 with a generic message
## Testing
- Unit tests for all service functions
- Integration tests for all route handlers using Hono's test helpers
- Test files live alongside source: taskService.test.ts next to taskService.ts
- Use test factories from /src/test/factories/ for consistent test data
Building the Schema
Composer prompt:
Write the Drizzle schema in src/db/schema.ts for a multi-tenant task management app.
Tables needed:
- organisations: id, name, slug (unique), createdAt
- users: id, email (unique), passwordHash, name, createdAt
- memberships: id, userId, organisationId, role (enum: owner/admin/member), createdAt
- tasks: id, title, description (nullable), status (enum: todo/in_progress/done), priority (enum: low/medium/high), assigneeId (nullable FK to users), organisationId, createdById, dueDate (nullable), createdAt, updatedAt
Use Drizzle's pgTable, proper TypeScript inference, and export a single db type. Include the createInsertSchema and createSelectSchema Zod schemas for each table using drizzle-zod.
Review the generated schema carefully. Check that foreign keys are correct, enum values match what you want, and the Zod schemas are exported properly. This file will be referenced throughout the project, so correctness here matters.
Adding Routes Iteratively
Rather than generating everything at once, build routes one at a time:
Using the schema in src/db/schema.ts, write the tasks CRUD routes in src/routes/tasks.ts.
Routes needed:
GET /tasks - list tasks for the org, support ?status= and ?assigneeId= filters
POST /tasks - create a task
GET /tasks/:id - get single task
PATCH /tasks/:id - update task (partial updates, all fields optional)
DELETE /tasks/:id - soft delete (add a deletedAt column if not present)
Requirements:
- All routes require auth middleware (already in src/middleware/auth.ts)
- Validate request bodies with Zod
- Delegate to taskService, never query the DB directly in routes
- organisationId always comes from context.var.auth.organisationId, never from the request body
- Return 404 with AppError if task not found or belongs to different org
After Cursor generates this, check a few things manually: the route is using context.var.auth.organisationId and not accepting it from the client, the Zod validation covers all required fields with proper types, errors are going through AppError rather than being thrown raw.
Debugging with Cursor
When something breaks, Cursor's debugging workflow is:
- Paste the full error in Composer (not just the message, the full stack trace)
- Add
@relevantFilereferences for the files involved - Describe what you were doing when the error occurred
A good debugging prompt:
Getting this error when calling POST /tasks:
[paste full stack trace]
The route is in @src/routes/tasks.ts and the service is in @src/services/taskService.ts.
I'm sending this request body:
{
"title": "Fix the bug",
"priority": "high"
}
The auth middleware is definitely running because other routes work fine.
Cursor will usually identify the problem and propose a fix. If the first fix doesn't work, say so with the new error. Don't start a new Composer session mid-debug; keep the conversation going so the AI has full context of what's been tried.
Context Management at Scale
As projects grow, context management becomes the primary skill. Cursor has a context window limit, and a large codebase exceeds it. Here's how to work with this rather than against it.
Use @file Precisely, Not Broadly
@codebase is useful for exploration ("where do we handle X?") but noisy for implementation. When you're implementing something specific, reference only the files that are actually relevant:
Update the task filtering in @src/services/taskService.ts to support
pagination. Look at how we handle pagination in @src/services/userService.ts
and follow the same pattern.
This is more effective than @codebase find the pagination pattern and apply it to tasks, because the AI doesn't have to search and can use its context window for the actual code rather than search results.
Break Large Tasks into Sessions
A 500-line refactor across 20 files in a single Composer session will have worse results than the same refactor done as five focused 100-line sessions. The AI's attention degrades as context fills up.
Plan large changes as a sequence of contained sessions, each with a clear scope and a clear success criterion. End each session by verifying it works before starting the next.
Start Fresh Sessions for New Features
When you finish one feature and start another, open a new Composer window. The previous conversation's context is noise for the new task. Your .cursorrules and the codebase index persist across sessions, so you don't lose the project context, just the conversation history.
Testing Workflow with Cursor
Cursor is particularly effective for writing tests because tests are highly patterned. Once it understands your testing conventions, it can generate comprehensive test suites from a service or route implementation.
Good prompt for test generation:
Write Vitest tests for @src/services/taskService.ts.
Cover:
- createTask: success case, validation failure, org isolation (can't create task for different org)
- getTasks: returns only tasks for the requesting org, filter by status works, filter by assignee works
- updateTask: success, 404 when task not found, 403 when task belongs to different org
- deleteTask: success, 404 handling
Use the test factories in @src/test/factories/ for test data.
Mock the database with vi.mock.
Follow the pattern in @src/services/userService.test.ts.
The @src/services/userService.test.ts reference is key. It gives the AI a concrete example of your testing style rather than letting it invent its own. Consistency in tests is as important as consistency in application code.
Performance Patterns Worth Knowing
A few things Cursor will sometimes get wrong without guidance in your .cursorrules:
N+1 queries. When generating code that fetches related data, Cursor sometimes produces code that queries in a loop. Always review generated database code for this pattern. Add to your .cursorrules: "Never write database queries inside loops. Use JOIN or batch queries."
Missing indexes. Cursor generates schema with primary keys but may miss indexes on foreign keys and frequently-filtered columns. Review every migration and add indexes on: all foreign key columns, columns used in WHERE clauses in common queries, columns used in ORDER BY on large tables.
Overfetching. Generated queries often select all columns. Add to .cursorrules: "Only select the columns needed for the operation. Never use SELECT * in production queries."
When to Override Cursor
Cursor is a tool, not an authority. There are situations where you should ignore or override what it produces:
Security-critical code. Authentication flows, authorisation checks, input sanitisation, cryptographic operations. Review these line by line. The AI can produce code that looks correct but has subtle vulnerabilities. If you're not certain, bring in a specialist or a second set of eyes.
Complex business logic. Cursor excels at patterns. Novel business rules with multiple interacting conditions are harder. The AI will produce something plausible, but plausible isn't always correct. Write the specification in comments first, then let Cursor implement, then verify the implementation against your spec.
Database migrations. Never let Agent mode run a migration without your explicit review. Read the migration SQL directly. Understand what it does. Run it manually on a development database first and verify the result before letting it anywhere near production.
Performance-critical paths. Generated code optimises for correctness over performance. Anything in a hot path (request handlers called thousands of times per second, background jobs processing large datasets) needs manual review and probably manual optimisation.
The Developer's Mental Model Shift
The most important thing about getting good at Cursor is not learning the keyboard shortcuts. It's accepting a different relationship with code authorship.
In traditional development, you're the author and the code is your output. You know every line because you wrote it.
In Cursor-driven development, you're the architect and the reviewer. The code is still yours because it reflects your decisions, your specifications, your review, and your judgment. But you're not the typist.
This requires building a different skill: reading and evaluating code rather than writing it. You need to be fast at spotting problems in generated code, at knowing which parts require scrutiny and which can be trusted, at identifying when the AI's pattern-matching has led it somewhere sensible and when it's confidently wrong.
Developers who try to verify every line with the same intensity end up slower than they were before using Cursor. Developers who trust everything uncritically ship bugs. The calibration between these two is the skill worth building.
What's Coming
The trajectory for 2026 and beyond is pretty clear. AI models are getting better at reasoning about large codebases. MCP ecosystems are expanding, which means richer real-time context. Editor-level awareness of runtime state (connecting to your running application's internals during development) is an active area of work.
The developers who will do the most interesting work in this environment are not those who resist AI tooling. They're the ones who invest in the complementary skills: system design, architectural thinking, security reasoning, and the judgment to know what to build and why. Cursor handles a lot of the how. The what and the why are still entirely yours.
`
What's your current
.cursorrulessetup? I'd be curious what people have found most useful to include, especially for teams rather than solo projects. Drop it in the comments.`
Asad is the founder of AI44.co.uk, a London-based AI training firm helping enterprise teams build with AI tools effectively. He holds the UK Global Talent visa endorsement in digital technology. If you have questions about Cursor workflows or enterprise AI adoption, he writes regularly on both.
This article was originally published by DEV Community and written by Asad (UK Global Talent).
Read original article on DEV Community