Cursor AI Prompt Engineering Guide

Cursor is an AI-powered code editor built on VS Code that integrates AI deeply into your development workflow. Unlike traditional coding assistants, Cursor understands your entire codebase and can make intelligent edits across multiple files.

This guide will teach you how to write prompts that leverage Cursor's unique capabilities, from simple completions to complex multi-file refactoring tasks.

Cursor offers several AI features, each requiring a different prompting approach:

• Tab Completion - Intelligent autocomplete that predicts your next code
• Cmd+K Edits - Inline code generation and editing
• Chat (Cmd+L) - Conversational AI with codebase context
• Composer - Multi-file editing for larger changes

Each mode has different context windows and capabilities. Chat and Composer can see your entire codebase through @-mentions, while Cmd+K focuses on the current file and selection.

1. Reference Specific Files with @-mentions

Use @filename to give Cursor context about relevant files:

Looking at @auth.ts and @middleware.ts, add rate limiting to the login endpoint

2. Be Specific About Location

Tell Cursor exactly where you want changes:

In the UserProfile component, add a loading skeleton that matches the final layout

3. Include Existing Patterns

Reference existing code patterns you want to follow:

Create a new API endpoint for orders, following the same pattern as @products/route.ts

4. Specify Technology Stack

Be explicit about frameworks and libraries:

Using React Query and Zod, add form validation to the checkout flow with proper error handling

5. Request Minimal Changes

Ask for focused changes to avoid over-engineering:

Fix the null pointer exception in calculateTotal. Don't refactor other code.

Bug Fixing

The useEffect in @Dashboard.tsx has a missing dependency causing stale data. Fix it while avoiding infinite loops.

Feature Implementation

Add dark mode support to @ThemeProvider.tsx. Use CSS variables for colors. Keep the existing light theme as default.

Refactoring

Extract the authentication logic from @api/auth/route.ts into a reusable authMiddleware function in @lib/auth.ts

Code Review

Review @checkout.ts for security issues. Focus on input validation and SQL injection prevention.

Testing

Write unit tests for the calculateDiscount function in @pricing.ts. Cover edge cases: negative prices, 100% discounts, and expired coupons.

Too Vague

Bad: Make this better

Good: Improve the error handling in this function by adding try-catch and user-friendly error messages

No Context

Bad: Add a button

Good: Add a "Save Draft" button next to the existing "Publish" button in @PostEditor.tsx, styled consistently

Too Many Changes at Once

Bad: Refactor the entire codebase to use TypeScript strict mode

Good: Enable strict null checks in @utils.ts and fix the resulting type errors

Missing Technology Context

Bad: Add authentication

Good: Add NextAuth.js authentication with Google OAuth provider, storing sessions in the existing PostgreSQL database

Multi-File Operations with Composer

For changes spanning multiple files, use Composer (Cmd+I) with clear scope:

Create a new "notifications" feature:
- Add @components/NotificationBell.tsx component
- Create @hooks/useNotifications.ts for state management
- Add API route @api/notifications/route.ts
- Update @layout.tsx to include the notification bell
Follow existing patterns from the @messages feature

Using .cursorrules

Create a .cursorrules file in your project root to set persistent context:

# .cursorrules
This is a Next.js 14 project using App Router.
- Use TypeScript strict mode
- Prefer server components unless interactivity is needed
- Use Tailwind CSS for styling
- Follow the existing component structure in /components

Iterative Refinement

Use follow-up prompts to refine:

Initial: "Add form validation to the signup form"
Follow-up: "Also add real-time validation as the user types"
Follow-up: "Show validation errors below each field, not in an alert"