Cursor Debug Bundle

Overview

Collect a minimal, redacted reproduction for a Cursor issue involving context, rules, indexing, model behavior, or extensions. Debug material may contain proprietary code or prompts, so scope and retention matter as much as reproducibility.

Prerequisites

• A named issue owner, Cursor version, affected workspace, and approved bug-report destination.
• Permission to inspect logs and settings, plus redaction rules for code, prompts, paths, tokens, and user data.
• A minimal reproducer that does not require customer data or production credentials.

Instructions

1. Start with the smallest reproducible prompt, file set, rule set, and model configuration.
2. Record versions, active context, indexing state, extensions, and redacted console errors.
3. Remove proprietary code, credentials, identifiers, and full prompt/output text before sharing externally.
4. Test the proposed resolution in a non-sensitive workspace and document its result before closing the issue.

Diagnose and fix AI suggestion quality issues in Cursor. Covers why AI generates wrong code, how to improve context, and systematic debugging workflows.

Diagnostic Framework

When AI suggestions are wrong, the cause is almost always one of these:

┌─ Context Problems (80% of issues) ───────────────────────┐
│  1. Missing context: AI doesn't have the relevant code   │
│  2. Wrong context: AI has stale or irrelevant files      │
│  3. Too much context: context window overflow            │
│  4. No project rules: AI doesn't know your conventions   │
└──────────────────────────────────────────────────────────┘
┌─ Model Problems (15% of issues) ─────────────────────────┐
│  5. Wrong model for the task                             │
│  6. Model hallucinating APIs or patterns                 │
└──────────────────────────────────────────────────────────┘
┌─ Prompt Problems (5% of issues) ─────────────────────────┐
│  7. Ambiguous or vague instructions                      │
│  8. Conflicting requirements in prompt                   │
└──────────────────────────────────────────────────────────┘

Debugging by Symptom

AI Uses Wrong API or Library Version

Symptom: Generated code uses React.createClass, old Express syntax, or deprecated patterns.

Root cause: Model training data includes old code. No project rules specifying versions.

Fix:

# .cursor/rules/stack-versions.mdc
---
description: "Tech stack version pinning"
globs: ""
alwaysApply: true
---
# Stack Versions (ALWAYS use these)
- React 19 with Server Components (NOT class components)
- Next.js 15 App Router (NOT Pages Router)
- TypeScript 5.7 strict mode
- Prisma 6 (NOT Sequelize or TypeORM)
- Tailwind CSS 4 (NOT s

Cursor Extension Integration

Overview

Add extensions only when their publisher, permissions, data flow, compatibility, and maintenance risk are understood for the target repository.

Prerequisites

• Approved extension source, publisher verification, and workspace/data classification.
• A disposable profile or test workspace and a rollback method for extension settings.

Instructions

1. Review publisher, permissions, license, update history, and network/data behavior.
2. Test one extension in an isolated profile with a non-sensitive workspace.
3. Check conflicts with Cursor, rules, completion providers, and repository tooling.
4. Approve, document, and periodically review the extension; remove it on security or compatibility failure.

Output

• A tested extension decision with owner, version, permission/data assessment, and rollback path.

Error Handling

Examples

Test a formatter extension in a disposable profile against a sample repository, verify it does not transmit code or conflict with existing formatting, and then document the approved version. Remove it rather than disabling security controls if it conflicts.

Integrate VS Code extensions with Cursor IDE. Covers the Open VSX Registry, VSIX installation for Microsoft-exclusive extensions, conflict resolution with AI features, and recommended extension stacks.

Extension Marketplace: Key Difference from VS Code

Cursor uses the Open VSX Registry instead of Microsoft's VS Code Marketplace. This is because Microsoft's marketplace terms restrict access to VS Code products only.

Impact: Most popular extensions are on Open VSX. Some Microsoft-published extensions are not.

Available on Open VSX (works directly)

Examples

Review a Cursor-generated diff, stage only its intended files, run the focused suite, and push a topic branch for review. If an accidental file is staged, unstage it and recheck the diff before committing.

Leverage Cursor's AI features within Git workflows: AI-generated commit messages, @Git context for code review, merge conflict resolution, and branch management.

Source Control Panel

Access with Cmd+Shift+G / Ctrl+Shift+G:

┌─ SOURCE CONTROL ────────────────────────────────┐
│  main ← current branch                         │
│                                                 │
│  Changes (3)                                    │
│    M  src/api/users.ts                         │
│    A  src/api/products.ts                      │
│    M  prisma/schema.prisma                     │
│                                                 │
│  Commit message: [✨ Generate with AI]          │
│  [Commit]  [Commit & Push]                      │
└─────────────────────────────────────────────────┘

AI-Generated Commit Messages

Click the sparkle/AI icon next to the commit message input. Cursor reads the staged diff and generates a message:

Example output:

feat: add product catalog CRUD API with Prisma model

- Add Product model to Prisma schema with name, price, category fields
- Create GET/POST/PUT/DELETE endpoints in src/api/products.ts
- Add Zod validation for product creation and update

Cursor Hello World

Overview

Practice Tab, Chat, Inline Edit, and Composer in a disposable sample project before using them on production code. Every proposed diff remains subject to normal review, tests, security checks, and repository rules.

Instructions

1. Create a non-sensitive example project and enable the approved privacy setting.
2. Use one feature at a time, give clear constraints, and inspect every generated diff before accepting it.
3. Run focused tests/formatting after applying a change; reject or revert unexpected edits.
4. Move to real repositories only after rules, indexing exclusions, and review expectations are configured.

A hands-on 10-minute walkthrough of Cursor's four core AI features: Tab Completion, Chat, Inline Edit, and Composer.

Setup

mkdir cursor-hello && cd cursor-hello
npm init -y
npm install typescript tsx @types/node --save-dev
npx tsc --init

Open the project in Cursor: cursor . (or File > Open Folder).

Exercise 1: Tab Completion

Create src/utils.ts. Start typing and let Tab complete:

// Type this much:
export function formatCurrency(amount: number, currency: string

// Tab suggests:
export function formatCurrency(amount: number, currency: string = 'USD'): string {
  return new Intl.NumberFormat('en-US', {
    style: 'currency',
    currency,
  }).format(amount);
}

Press Tab to accept the full suggestion, or Cmd+Right Arrow to accept word-by-word.

Try These Prompts for Tab

Type a comment describing what you want, then start the function:

// Validate an email address using regex
export function validateEmail(

// Sort an array of objects by a key
export function sortBy<T>(

// Calculate the distance between two lat/lng points in km
export function haversineDistance(

Tab reads your comment and generates the implementation.

Exercise 2: Chat (Cmd+L)

Open Chat with Cmd+L. Try these prompts:

Ask about your code:

@src/utils.ts
What does the formatCurrency function do? Does it handle edge cases
like negative numbers or very large values?

Generate new code:

Write a TypeScript function that converts a nested object
to a flat key-value map with dot-separated keys.
Example: { a: { b: 1 } } → { "a.b": 1 }

Debug a concept:

Explain the difference between Promise.all() and Promise.allSettled()
with code examples showing when to use each.

Chat responds with explanations and code snippets. Click Apply on any code block to insert it into your editor.

Cursor Install & Auth

Overview

Install Cursor, authenticate through the approved identity flow, and establish privacy settings before opening sensitive repositories. Do not treat local profiles or settings files as a secrets store.

Instructions

1. Download the signed installer from the official site or approved software catalog.
2. Sign in through the organization-approved account or SSO flow and confirm the expected tenant.
3. Enable approved privacy/data controls before opening proprietary code, then import only reviewed settings and extensions.
4. Verify Tab and Chat with a non-sensitive sample project; escalate tenant mismatch to the administrator.

Install Cursor IDE and authenticate your account. Covers all platforms, plan activation, and VS Code migration.

Installation

macOS

# Option 1: Direct download
open https://cursor.com/download

# Option 2: Homebrew
brew install --cask cursor

After install, drag Cursor.app to Applications. First launch may require: System Settings > Privacy & Security > Allow.

Linux

# Download AppImage
curl -fSL https://download.cursor.com/linux/appImage/x64 -o cursor.AppImage
chmod +x cursor.AppImage
./cursor.AppImage

# Or via .deb (Debian/Ubuntu)
curl -fSL https://download.cursor.com/linux/deb/x64 -o cursor.deb
sudo dpkg -i cursor.deb

Add to PATH for terminal launching:

# Add to ~/.bashrc or ~/.zshrc
alias cursor='/path/to/cursor.AppImage'

Windows

Download installer from cursor.com/download. Run the .exe installer. Cursor installs per-user (no admin required by default).

Authentication

First Launch Sign-In

1. Launch Cursor
2. Click Sign In in the welcome screen
3. Choose auth method:

• GitHub (recommended for developers)
• Google
• Email + password

1. Browser opens for OAuth flow
2. Approve the authorization
3. Return to Cursor -- it detects the auth automatically

Plan Activation

After sign-in, your plan is automatically active:

1. Click each file in the Changes panel to review its diff
2. Check imports: are they real packages in your project?
3. Check function calls: do the methods actually exist?
4. Run build after applying: npm run build
5. Run tests: npm test
6. Commit BEFORE running Composer (easy rollback with git checkout .)

- Use @Files (specific) over @Folders (broad) over @Codebase (broadest)
- Limit to 3-5 file references per prompt
- Start new chats for new topics
- Remove stale context pills by clicking X

┌─────────────────────────────────────────────────────────────┐
│  1. PLAN        →  Chat (Cmd+L) with @Codebase, @Docs      │
│  2. SCAFFOLD    →  Composer (Cmd+I) for new files           │
│  3. IMPLEMENT   →  Tab completion for line-by-line coding   │
│  4. REFINE      →  Inline Edit (Cmd+K) for targeted fixes  │
│  5. TEST        →  Chat to generate tests, terminal to run  │
│  6. COMMIT      →  AI-generated commit messages             │
│  7. REVIEW      →  @Git for branch diff review              │
└─────────────────────────────────────────────────────────────┘

@Codebase @Docs Prisma

I need to add a "favorites" feature where users can bookmark products.
What's the best approach given our current data model and API structure?
Consider: database schema, API endpoints, and frontend hooks.

// mywork.code-workspace
{
  "folders": [
    { "path": "/home/dev/api-service" },
    { "path": "/home/dev/web-frontend" },
    { "path": "/home/dev/shared-lib" }
  ],
  "settings": {
    "editor.tabSize": 2,
    "files.exclude": {
      "**/node_modules": true,
      "**/dist": true
    }
  }
}

Step 1: Identify bottleneck
         ├── Editor lag? → Step 2 (Editor settings)
         ├── High CPU?   → Step 3 (Extension audit)
         ├── Slow AI?    → Step 4 (AI tuning)
         └── Memory?     → Step 5 (Memory management)

Step 2: Editor settings
         ├── Disable minimap, breadcrumbs
         ├── Reduce file watcher scope
         └── Increase memory limits

Step 3: Extension audit
         ├── Profile running extensions
         ├── Disable heavy extensions
         └── Use workspace-scoped disabling

Step 4: AI feature tuning
         ├── Optimize .cursorignore
         ├── Use faster models
         └── Manage chat history

Step 5: Memory management
         ├── Close unused workspace folders
         ├── Limit open editor tabs
         └── Clear caches

{
  // Disable visual features f

[ ] All team members authenticated with correct plan (Pro/Business/Enterprise)
[ ] SSO configured (Business/Enterprise) -- see cursor-sso-integration skill
[ ] Privacy Mode enabled (enforced at team level for Business+)
[ ] Verify plan at cursor.com/settings

[ ] .cursor/rules/ directory created and committed to git
[ ] Core project rule with alwaysApply: true (stack, conventions, standards)
[ ] Language-specific rules with glob patterns (*.ts, *.py, etc.)
[ ] Security rule: "Never suggest hardcoded credentials or secrets"
[ ] No sensitive data (API keys, passwords) in any rule file

# .cursor/rules/project.mdc
---
description: "Core project context"
globs: ""
alwaysApply: true
---
# Project: [Name]
Stack: [framework, language, database, etc.]
Package manager

my-project/
├── .cursor/
│   └── rules/
│       ├── project.mdc          # alwaysApply: true (stack, conventions)
│       ├── security.mdc         # alwaysApply: true (security constraints)
│       ├── typescript.mdc       # globs: "**/*.ts,**/*.tsx"
│       ├── api-routes.mdc       # globs: "src/api/**/*.ts"
│       ├── database.mdc         # globs: "src/db/**/*.ts,prisma/**"
│       └── testing.mdc          # globs: "**/*.test.ts,**/*.spec.ts"
├── .cursorignore                # Exclude from AI + indexing
├── .cursorindexingignore        # Exclude from indexing only
├── .gitignore
├── src/
│   ├── api/                     # API routes
│   ├── services/                # Business logic
│   ├── db/                      # Database layer
│   ├── types/                   # Shared TypeScript types
│   ├── ut

---
description: "Enforce TypeScript strict mode and functional patterns"
globs: "src/**/*.ts,src/**/*.tsx"
alwaysApply: false
---
# TypeScript Standards

- Use `const` over `let`, never `var`
- Prefer pure functions over classes
- All functions must have explicit return types
- Use discriminated unions over enums

Single Sign-On URL (ACS URL):
  https://cursor.com/api/auth/saml/callback

Audience URI (Entity ID):
  https://cursor.com/api/auth/saml

Name ID format: EmailAddress
Application username: Email

Attribute Statements:
  email    → user.email       (Required)
  name     → user.firstName + " " + user.lastName  (Optional)

// You type:
function validateEmail(email: string)

// Ghost text appears:
function validateEmail(email: string): boolean {
  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;    ← gray ghost text
  return emailRegex.test(email);
}

# macOS (Homebrew)
brew upgrade --cask cursor

# macOS/Linux/Windows: Download latest from
# https://cursor.com/download

# Linux AppImage: replace the old file
curl -fSL https://download.cursor.com/linux/appImage/x64 -o cursor.AppImage
chmod +x cursor.AppImage

[ ] Note current version: Help > About
[ ] Check release notes: changelog.cursor.sh
[ ] Backup settings:
    macOS: cp -r ~/Library/Application\ Support/Cursor/User ~/cursor-settings-backup
    Linux: cp -r ~/.config/Cursor/User ~/cursor-settings-backup
[ ] Export extension li

┌─ Dashboard ────────────────────────────────────────────┐
│                                                        │
│  Total Requests This Month:  12,847                    │
│  Fast Requests Remaining:    2,153 / 15,000            │
│  Active Users:               28 / 30 seats             │
│  Most Used Model:            Claude Sonnet (62%)       │
│                                                        │
│  ┌─ Usage Trend ─────────────────────────────────┐     │
│  │  ▆▆▇▇██▇▆▇█▇▇▆▅                              │     │
│  │  Mon Tue Wed Thu Fri Sat Sun                   │     │
│  └───────────────────────────────────────────────┘     │
│                                                        │
│  ┌─ Top Users ───────────────────────────────────┐     │
│  │  alice@co.com     847 requests  (Sonnet)      │     │
│  │  bob@co.com       623 reques