Cursor Deep Dive
Mastering Composer Mode
Composer is Cursor's signature feature—the ability to edit multiple files simultaneously with full codebase context. This lesson teaches you to use it effectively.
What is Composer?
Composer is a multi-file editing interface that:
- Understands your entire codebase
- Creates, modifies, and deletes files
- Maintains consistency across changes
- Shows diffs before applying
Open Composer: ⌘I (macOS) or Ctrl+I (Windows/Linux)
Composer Interface
┌─────────────────────────────────────────────────────────────┐
│ Composer [X] │
├─────────────────────────────────────────────────────────────┤
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Enter your request... │ │
│ │ │ │
│ │ @files @docs @web @codebase │ │
│ └─────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ Context: │
│ ├── Currently open files │
│ ├── @-mentioned files │
│ └── Indexed codebase (if enabled) │
├─────────────────────────────────────────────────────────────┤
│ Changes: │
│ ├── src/api/users.ts [modified] ▼ │
│ │ + import { validateEmail } from '../utils' │
│ │ - // TODO: add validation │
│ ├── src/utils/validation.ts [new file] ▼ │
│ │ + export function validateEmail(email: string)... │
│ └── src/tests/validation.test.ts [new file] ▼ │
├─────────────────────────────────────────────────────────────┤
│ [Accept All] [Reject All] [Accept Selected] │
└─────────────────────────────────────────────────────────────┘
The @-Mention System
Use @-mentions to provide precise context:
@files - Reference Specific Files
@src/components/Button.tsx Create a variant of this button for forms
@docs - Reference Documentation
@docs Next.js App Router How do I implement middleware?
@web - Search the Web
@web latest React 19 features Add any new hooks to our project
@codebase - Search Your Code
@codebase authentication Where is user login handled?
@folders - Reference Directories
@src/components Refactor all components to use the new design system
Effective Composer Prompts
Pattern 1: Feature Implementation
Weak prompt:
Add user authentication
Strong prompt:
Add JWT-based user authentication:
- Create /api/auth/login and /api/auth/register endpoints
- Store user sessions in cookies (httpOnly, secure)
- Add middleware to protect /dashboard routes
- Use bcrypt for password hashing
- Follow the existing error handling pattern in @src/lib/errors.ts
Pattern 2: Refactoring
Weak prompt:
Make this code better
Strong prompt:
Refactor @src/services/payment.ts:
- Extract Stripe-specific logic into a separate adapter
- Create PaymentProvider interface for future gateways
- Add proper TypeScript types (no any)
- Maintain backward compatibility with existing callers
- Add unit tests following @src/services/__tests__ patterns
Pattern 3: Bug Fixing
Weak prompt:
Fix the login bug
Strong prompt:
Fix the login redirect issue:
- Problem: After login, users land on /login instead of /dashboard
- The issue seems related to @src/middleware.ts redirect logic
- Preserve the "redirect to original page" functionality
- Add a test case to prevent regression
Multi-File Workflows
Creating a New Feature
Example: Adding a comments system
Create a comments feature for blog posts:
1. Database: Add Comment model to @prisma/schema.prisma
- Fields: id, content, authorId, postId, createdAt
2. API Routes:
- POST /api/posts/[postId]/comments (create)
- GET /api/posts/[postId]/comments (list)
- DELETE /api/comments/[id] (delete own)
3. Components:
- CommentList: Display comments with pagination
- CommentForm: Create new comment (authenticated only)
- CommentItem: Single comment with delete option
4. Follow existing patterns in @src/features/posts
Composer Output:
- prisma/schema.prisma (modified)
- src/app/api/posts/[postId]/comments/route.ts (new)
- src/app/api/comments/[id]/route.ts (new)
- src/components/comments/CommentList.tsx (new)
- src/components/comments/CommentForm.tsx (new)
- src/components/comments/CommentItem.tsx (new)
Reviewing Changes
Before accepting, always review:
Review Checklist:
├── ✅ Logic correct?
├── ✅ Follows project patterns?
├── ✅ No security issues?
├── ✅ Types properly defined?
├── ✅ Error handling included?
└── ✅ No unnecessary changes?
Accept/Reject Options:
- Accept All: Apply all changes
- Reject All: Discard everything
- Accept Selected: Cherry-pick specific files
- Edit in diff: Modify before applying
Advanced Techniques
Iterative Refinement
After first generation:
Good start, but:
- Add input validation to the API routes
- Use React Query instead of useState for data fetching
- Add loading states to components
Context Stacking
Mention multiple files for complex tasks:
@src/types/api.ts @src/lib/api-client.ts @src/hooks/useApi.ts
Add a new endpoint for user preferences that follows these patterns
Checkpoint Before Big Changes
Before major refactoring:
- Commit current work
- Run Composer
- Review carefully
- Test before committing
Common Mistakes to Avoid
1. Too Much at Once
❌ "Refactor the entire codebase to TypeScript" ✅ "Convert @src/utils to TypeScript, starting with helpers.js"
2. Vague Instructions
❌ "Make it better" ✅ "Improve performance by memoizing expensive calculations"
3. Missing Context
❌ "Add tests" ✅ "Add tests for @src/lib/auth.ts following @src/lib/tests/api.test.ts patterns"
4. Ignoring Diffs
❌ Click "Accept All" without reading ✅ Review each file's changes, especially deletions
Pro Tips
1. Use .cursorrules for Consistency
Your rules file shapes all Composer output.
2. Start Small, Expand
Begin with one file, then add related files.
3. Reference Working Examples
"Like the implementation in @src/features/users"
4. Be Specific About Patterns
"Use server actions, not API routes"
Mastery Insight: The best Composer users provide context upfront rather than correcting after. Spend 30 seconds writing a detailed prompt to save 5 minutes of iteration.
In the next lesson, we'll explore Agent mode—Cursor's autonomous coding capability. :::