Cursor looks like VS Code with superpowers, and it is — but to truly leverage it you need to understand how each AI mode works and when to use each one. This guide takes you from installation to a productive workflow with Composer, Tab, Chat, and Rules.
Prerequisites
- Download Cursor from cursor.com (Mac, Windows, Linux)
- An existing project to practice with
- If you’re coming from VS Code: your extensions and configuration migrate automatically
Step 1: Installation and Migration
- Download and install Cursor
- On first launch, Cursor offers to import your VS Code configuration — accept it
- Your extensions, themes, keybindings, and settings are copied automatically
- Open your project with
File → Open Folder
If you already had VS Code open, close it. Cursor and VS Code can coexist but share some extensions and conflicts may occur.
Step 2: Understanding AI Modes
Cursor has four main modes of interaction with AI. Each has its use case:
Tab (Intelligent Autocomplete)
- Activates automatically as you type
- Goes beyond typical autocomplete — predicts your intention, not just the next line
- Can suggest edits across multiple lines simultaneously
- Accept with
Tab, reject withEsc, partially accept withCtrl+→
Cmd+K / Ctrl+K (Inline Edit)
- Select code → press
Ctrl+K→ describe the change - Cursor rewrites the selected code in place
- Ideal for targeted changes: “convert this to async/await”, “add error handling”, “optimize this query”
Chat (Ctrl+L / Cmd+L)
- Conversational sidebar panel
- Use
@to reference files, symbols, documentation - Ideal for questions about your codebase, explanations, and exploring approaches
- Doesn’t edit files directly — shows you code you can apply
Composer (Ctrl+I / Cmd+I)
- The most powerful mode — an agent that plans and applies changes across multiple files
- Describe a complete task: “add JWT authentication to API routes”
- Composer analyzes your codebase, plans the changes, and applies them
- Shows diffs for each file — you review and accept or reject
Step 3: Configure Rules
Rules are Cursor’s equivalent of custom instructions. Create a .cursor/rules/ folder at your project root:
.cursor/rules/general.mdc
---
description: General project rules
globs: "**/*"
---
# Project Context
This is an e-commerce project built with:
- Frontend: Next.js 14 with App Router and TypeScript
- Backend: API Routes in Next.js
- Database: Supabase (PostgreSQL)
- Auth: Supabase Auth
- Styling: Tailwind CSS
- Deployment: Vercel
# Conventions
- Code in English, documentation comments in Spanish
- Use Server Components by default, Client Components only when necessary
- Always handle loading and error states
- Validate inputs with Zod on the server side
- Use Next.js naming conventions for special files
.cursor/rules/api.mdc
---
description: Rules for API routes
globs: "app/api/**/*"
---
# API Routes
- Always validate request body with Zod
- Use try/catch with consistent error responses
- Error format: { error: string, code: string, details?: object }
- Authenticate with Supabase Auth middleware
- Rate limiting on public endpoints
- Structured logs with timestamp and request ID
Rules with globs activate automatically when you work on files matching the pattern. This means Composer and Chat receive different instructions depending on which file you’re in.
Step 4: Workflow with Composer
Composer is where Cursor really differentiates itself. Here’s a practical workflow for implementing a feature:
Example: Add a product reviews system
- Open Composer (
Ctrl+I) - Write your prompt with context:
I need to add a reviews system for products. Authenticated users can
leave a review with a rating (1-5 stars) and an optional comment.
I need:
1. Supabase schema for the reviews table (SQL migration)
2. API route POST /api/reviews to create a review
3. API route GET /api/reviews/[productId] to get product reviews
4. ReviewForm component to submit a review
5. ReviewList component to display reviews with average rating
Use the existing project conventions. Look at how other API routes
and components are structured to maintain consistency.
- Composer analyzes your project, generates a plan, and starts creating/modifying files
- Review each diff carefully — accept what’s good, reject what’s not
- If something isn’t right, describe the adjustment in the same conversation thread
Tips for effective Composer prompts:
- Be specific about what you want, but not about how to implement it — let Cursor choose the approach based on your existing codebase
- Reference existing files: “follow the pattern in
app/api/products/route.ts” - Break large tasks into steps — it’s better to make 3 focused prompts than one giant one
Step 5: Workflow with @ References
The @ system in Chat and Composer is fundamental:
@file— reference a specific file@folder— include all files in a folder@codebase— search your entire project (uses the index)@docs— reference external documentation (you can add URLs)@web— search the web@git— reference commits, diffs, and change history
Practical example in Chat:
@app/lib/supabase.ts @app/api/products/route.ts
How can I add pagination to the products endpoint while
maintaining the existing error handling pattern?
This gives Cursor exactly the context it needs without including irrelevant files.
Step 6: Configure External Docs
Add documentation for the libraries you use so Cursor can reference them:
- Go to
Cursor Settings → Features → Docs - Add documentation URLs:
https://nextjs.org/docs— Next.jshttps://supabase.com/docs— Supabasehttps://tailwindcss.com/docs— Tailwind
- Now in Chat you can use
@docs Next.jsand Cursor searches directly in the documentation
This is especially useful for APIs that change frequently — Cursor uses current documentation instead of its training knowledge.
Step 7: Model Selection
Cursor supports multiple models. Practical recommendations:
- Claude Sonnet — best quality/speed ratio for most Composer tasks
- Claude Opus — for complex architecture tasks and large refactoring
- GPT-4o — fast for inline edits and simple questions
- cursor-small — Cursor’s own model, fast for Tab autocomplete
You can change the model in each Chat or Composer conversation. You’re not limited to just one.
Common Mistakes
Accepting all Composer diffs without reviewing. Composer is powerful but not infallible. Review each change like you would a PR — especially for business logic and security.
Not using Rules. Without Rules, Cursor generates generic code. With well-written Rules, it generates code that follows your conventions. The difference is huge.
Vague prompts. “Improve this code” produces mediocre results. “Refactor this function to separate validation logic from processing, and add specific TypeScript types instead of any” produces excellent results.
Not indexing the project. Make sure indexing is enabled in Settings. Without it, @codebase and Composer suggestions are much less accurate.
Result
With this setup you have a workflow where:
- Tab handles intelligent autocomplete as you type
- Ctrl+K makes targeted edits without leaving the file
- Chat answers questions with full project context
- Composer implements complete features with diff review
- Rules ensure all generated code follows your conventions
The learning curve is a couple of days. The impact on productivity is immediate.Are you already using Cursor? Share your favorite Rules and workflows. 