cursor

---
name: cursor
description: Expert Cursor IDE assistance covering AI pair programming, codebase indexing, custom rules (.cursorrules), Composer, and debugging. Use when maximizing AI-native software development velocity.
---

# Cursor

Cursor is an AI-native code editor built on VS Code, featuring multi-file code editing via Cursor Composer, predictive codebase indexing, and contextual code generation.

## When to Use

- **AI-First Software Development**: Accelerating feature engineering with Cursor IDE, Composer, and multi-file edits.
- **Repository-Level Contextual Reasoning**: Using `@codebase` to search across semantic embeddings of entire projects.
- **Custom Project Guidelines with .cursorrules**: Instructing the AI model on architecture, frameworks, and testing standards.
- **Interactive Inline Code Editing**: Generating, refactoring, and fixing code directly in the editor buffer via `Cmd+K`.

## Quick Start

Configure repository rules in `.cursorrules`:

```markdown
# .cursorrules

- Prefer functional components and hooks in React 19.
- Always use TypeScript with strict null checks.
- Keep helper functions small and pure.
- Include unit tests in Vitest for new features.
```

## Core Concepts

### Configuring .cursorrules for Automated Agent Guidelines

Defining persistent project rules for code generation:

```markdown
# .cursorrules

You are an expert Full-Stack TypeScript and Rust developer.
Always adhere strictly to these conventions:

- Framework: Next.js 15 (App Router), React 19, Tailwind CSS v4.
- Language: Strict TypeScript, no `any`, use `unknown` with type guards.
- Code Style: Functional, immutable, early returns, descriptive error messages.
- State: Favor Server Components and Server Actions over client state.
- Testing: Always write unit tests with Vitest and integration tests with Playwright.
- Do NOT hallucinate dependencies not present in package.json.
- When generating code, omit explanatory conversational filler; output code and brief rationale.
```

### Targeted Context Tagging with @ Directives

Injecting precise context into AI prompt buffers:

```text
Prompt:
@codebase How is authentication token verification handled across our microservice routes?
Inspect @middleware.ts and @src/auth/session.ts to implement a new rate-limited admin route guard.
Ensure compliance with @docs/security-guidelines.md.
```

### Multi-File Composer Refactoring Workflows

Prompting across architectural boundaries:

```text
Prompt in Composer:
Refactor our legacy User REST endpoints to modern Server Actions:
1. Create app/actions/user.ts with Zod input validation schemas.
2. Update app/profile/page.tsx to call the server action with useActionState.
3. Remove old API route handler in app/api/user/route.ts.
4. Add unit test in tests/actions/user.test.ts verifying rejection of invalid email.
```

## Common Patterns

### Global and Project .cursorrules Configuration

**Problem**: Cursor generates responses with generic boilerplate that violates repository architectural rules.  
**Solution**: Define comprehensive repository rules in root `.cursorrules`.

```markdown
# .cursorrules

- Prefer TypeScript strict mode with no explicit 'any'.
- Use named exports rather than default exports for React components.
- Colocate unit tests next to source files using the *.test.ts pattern.
- Wrap all external network calls with timeout boundaries.
```

## Best Practices

**Do**:

- Create a `.cursorrules` file in the project root to permanently align model completions with team conventions.
- Use `@file`, `@docs`, and `@symbol` instead of `@codebase` for targeted tasks to reduce prompt token noise and cost.
- Review AI-generated diffs carefully before accepting multi-file Composer changes.
- Configure `.cursorignore` to prevent indexing of generated files, `.env` secrets, and build output directories.

**Don't**:

- Prompt the AI with raw database passwords, production API keys, or private customer data.
- Blindly accept massive multi-file refactors without running automated test suites (`npm test`).
- Write ambiguous prompts; specify desired libraries, error handling strategies, and boundary constraints.

## Troubleshooting

| Error                              | Cause                                                        | Solution                                              |
| :--------------------------------- | :----------------------------------------------------------- | :---------------------------------------------------- |
| `Codebase indexing failed`         | Massive files (`node_modules`, large binaries) not excluded. | Add paths to `.cursorignore`.                         |
| `Composer diff cannot be applied`  | File edited externally while Cursor was generating code.     | Re-run prompt using fresh file state.                 |
| `Cursor tab autocomplete sluggish` | Large language server indexing lag in background.            | Restart Cursor or disable unused language extensions. |

## References

- [Cursor Documentation](https://docs.cursor.com/)