Cursor/Windsurf AI IDE Setup & Optimization

# Cursor/Windsurf AI IDE Setup & Optimization Skill

## What This Skill Enables

Claude can help you configure and optimize Cursor or Windsurf AI code editors for maximum productivity. Both editors provide AI-powered code completion, multi-file editing, and intelligent refactoring. Cursor excels with its Agent mode and Composer features, while Windsurf emphasizes collaborative flows and Cascade AI. From initial setup to advanced workflows, Claude handles IDE configuration and optimization.

## Prerequisites

**Required:**
- Claude Pro subscription or Claude Code CLI
- macOS, Windows, or Linux
- Cursor or Windsurf IDE installed
- OpenAI API key or Anthropic API key
- Basic code editor knowledge

**What Claude handles automatically:**
- Configuring API keys and model selection
- Setting up keybindings for AI features
- Optimizing editor settings for performance
- Creating custom rules and context files
- Configuring agent mode behaviors
- Setting up workspace-specific settings
- Implementing best practices for prompting
- Optimizing token usage and costs

## How to Use This Skill

### Initial Setup & Configuration

**Prompt:** "Help me set up Cursor with Claude Sonnet model. Configure keybindings for: inline completion (Tab), chat (Cmd+K), composer (Cmd+I), and agent mode. Optimize for React/TypeScript projects."

Claude will:
1. Guide API key configuration
2. Set model to Claude Sonnet
3. Configure keyboard shortcuts
4. Add .cursorrules for React/TS
5. Set up workspace settings
6. Configure auto-complete behavior
7. Add project context files

### Optimizing Agent Mode

**Prompt:** "Configure Cursor Agent mode for: automatic file edits, test generation, refactoring tasks, and documentation. Set guardrails to prevent breaking changes."

Claude will:
1. Enable agent mode settings
2. Configure file permissions
3. Set up test generation rules
4. Add refactoring guidelines
5. Create .cursorrules for safety
6. Configure approval workflows
7. Set token limits

### Custom Rules & Context

**Prompt:** "Create .cursorrules file for Next.js 15 project with: TypeScript strict mode, shadcn/ui components, Tailwind CSS, server actions, and Zod validation. Include coding standards."

Claude will:
1. Create .cursorrules file
2. Specify tech stack versions
3. Add coding conventions
4. Include common patterns
5. Set error handling rules
6. Add performance guidelines
7. Document API usage

### Multi-File Refactoring

**Prompt:** "Set up Windsurf Cascade for: renaming components across files, updating import paths, refactoring prop types, and running type checks. Configure to preview changes before applying."

Claude will:
1. Configure Cascade settings
2. Enable preview mode
3. Set up diff viewing
4. Add rollback capability
5. Configure type checking
6. Set up batch operations
7. Add safety confirmations

## Tips for Best Results

1. **Use .cursorrules**: Create project-specific rules file with tech stack, conventions, and patterns. AI reads this for context.

2. **Composer for Large Changes**: Use Cmd+I (Cursor) or Cascade (Windsurf) for multi-file edits. More powerful than inline chat.

3. **@ Mentions for Context**: Use @filename, @folder, @docs to give AI specific context. Reduces hallucinations.

4. **Agent Mode Guardrails**: Set file permissions and review changes. Don't let agent edit critical files unsupervised.

5. **Model Selection**: Claude Sonnet for code quality, GPT-4 for speed. Switch based on task complexity.

6. **Token Optimization**: Use codebase indexing wisely. Exclude node_modules, dist, .next from context.

## Common Workflows

### React Component Refactoring
```
"Configure Cursor for React refactoring workflow:
1. Set up .cursorrules with React 19 patterns
2. Enable TypeScript strict mode validation
3. Configure agent mode for component splits
4. Add rules for shadcn/ui usage
5. Set up automatic prop-types to TS conversion
6. Configure test generation with Vitest
7. Enable preview for all agent changes
8. Add rollback shortcuts"
```

### API Route Generation
```
"Set up Windsurf for API development:
1. Create .cursorrules for FastAPI/Next.js API routes
2. Configure agent to generate OpenAPI docs
3. Set up automatic validation with Zod
4. Add error handling templates
5. Configure test generation
6. Set up database query optimization
7. Enable security scanning
8. Add rate limiting patterns"
```

### Legacy Code Migration
```
"Configure Cursor for migrating JS to TS:
1. Set up .cursorrules for TypeScript migration
2. Configure agent for file-by-file conversion
3. Add type inference rules
4. Set up any type replacement
5. Configure import path updates
6. Enable type checking after each file
7. Add rollback on type errors
8. Generate migration report"
```

### Test Coverage Improvement
```
"Set up Windsurf for test generation:
1. Configure agent for unit test creation
2. Add .cursorrules for testing patterns
3. Set up coverage threshold checks
4. Configure mock generation
5. Add integration test templates
6. Set up snapshot testing rules
7. Enable test runner integration
8. Generate coverage reports"
```

## Troubleshooting

**Issue:** "AI suggestions are slow or timing out"
**Solution:** Reduce context size by excluding large folders in settings. Use @filename for specific context instead of full codebase. Check API rate limits. Switch to faster model (GPT-3.5) for simple edits. Clear index and rebuild.

**Issue:** "Agent mode making unwanted changes"
**Solution:** Add .cursorrules with explicit guidelines. Set file permissions to read-only for critical files. Enable preview mode to review all changes. Use 'explain' prompts before 'do' prompts. Add 'do not modify' comments in code.

**Issue:** "API costs higher than expected"
**Solution:** Exclude unnecessary folders from indexing. Use caching (Cursor's @codebase). Switch to smaller models for simple tasks. Disable auto-complete for comments. Review token usage in settings. Use local models for basic completion.

**Issue:** "Keybindings conflicting with other extensions"
**Solution:** Check keybindings.json for conflicts. Reassign Cursor/Windsurf shortcuts. Disable conflicting extensions. Use Cmd+K+S (Cursor) to view all shortcuts. Export keybindings and version control them.

**Issue:** "AI not using project context correctly"
**Solution:** Create detailed .cursorrules file. Use @docs to reference documentation. Add README with architecture overview. Use @folder for package-specific context. Verify codebase indexing is complete. Rebuild index if stale.

## Learn More

- [Cursor Documentation](https://cursor.sh/docs)
- [Windsurf by Codeium](https://codeium.com/windsurf)
- [Cursor Forum](https://forum.cursor.sh/)
- [AI Coding Best Practices](https://cursor.sh/blog/agent-mode)
- [Windsurf Cascade Guide](https://codeium.com/blog/windsurf-editor)