Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Um comando direto ignora o prompt de revisão. Verifique a origem antes de executá-lo.
Debug AI suggestion quality, context issues, and code generation problems in Cursor. Triggers on
"debug cursor ai", "cursor suggestions wrong", "bad cursor completion", "cursor ai debug",
"cursor hallucination".
allowed-tools
Read, Write, Edit, Bash(cmd:*)
version
1.18.0
license
MIT
author
Jeremy Longshore <jeremy@intentsolutions.io>
tags
["saas","cursor","debugging"]
compatibility
Designed for Claude Code, also compatible with Codex and OpenClaw
Cursor Debug Bundle
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)-React19withServerComponents(NOTclasscomponents)-Next.js15AppRouter(NOTPagesRouter)-TypeScript5.7strictmode-Prisma6(NOTSequelizeorTypeORM)-TailwindCSS4(NOTstyled-components)-Node.js22(ESM,NOTCommonJSrequire())
AI Generates Code That Doesn't Match Your Patterns
Symptom: Generated code uses different naming, structure, or patterns than your codebase.
Root cause: AI does not have your existing code as context.
Fix: Reference your existing patterns explicitly:
@src/api/users/route.ts
Create src/api/products/route.ts following the EXACT same patterns:
same error handling, same response format, same validation approach.
AI Hallucinates Non-Existent Functions
Symptom: AI calls functions or uses imports that do not exist in your project or in the library.
Root cause: Model confuses similar libraries or invents plausible-sounding APIs.
Fix:
Add @Docs context: @Docs Prisma gives the AI real API documentation
Verify generated imports: run npm run build immediately after applying
Use @Files to show the actual module interface: @src/lib/database.ts
AI Ignores Your Instructions
Symptom: You ask for one thing, AI does something different.
Root cause: Context window overflow -- your instructions get pushed out by file contents.
Fix:
Start a new chat (Cmd+N) -- conversation history may be using too much context
Use fewer @ references -- each consumes context budget
Put instructions at the end of the prompt (models attend more to recent text)
Use @Files instead of @Codebase to reduce context volume
Tab Completion is Repetitive or Wrong
Symptom: Tab keeps suggesting the same wrong pattern.
Root cause: Tab has limited context compared to Chat/Composer.
Fix:
Open related files in editor tabs (Tab reads open tabs)
Add a comment above your cursor describing what you want
Reject bad suggestions with Esc (trains the model)
If persistently wrong, use Cmd+K inline edit instead
Systematic Debug Workflow
When AI output is consistently wrong:
Step 1: Check context
- Open Chat, look at context pills at top
- Are the right files included?
- Are stale files adding noise?
Step 2: Check rules
- @Cursor Rules in chat -- what rules are active?
- Do rules conflict with each other?
- Are glob patterns matching the right files?
Step 3: Test with minimal context
- Start new chat
- Add ONLY the most relevant file: @src/the-file.ts
- Ask your question with explicit constraints
- If this works, the issue was context pollution
Step 4: Test with different model
- Switch from Sonnet to Opus or GPT-5
- If better model gives better results, the task needs more reasoning power
Step 5: Check indexing
- Is the codebase indexed? (status bar shows "Indexed")
- Is the relevant file excluded by .cursorignore?
- Run Cmd+Shift+P > "Cursor: Resync Index"
Logs and Diagnostics
Opening Developer Tools
Cmd+Shift+P > Developer: Toggle Developer Tools
Check the Console tab for:
API request errors (red)
Context assembly logs
Extension errors
Verbose Logging
Enable verbose output: Cursor Settings > search "log level" > set to "Debug"
Logs location:
macOS: ~/Library/Application Support/Cursor/logs/
Linux: ~/.config/Cursor/logs/
Reproducing Issues for Bug Reports
1. Note Cursor version: Help > About
2. Note model used (from Chat/Composer header)
3. Copy the exact prompt that produced wrong output
4. Copy the wrong output
5. List active extensions: Cmd+Shift+P > "Extensions: Show Installed"
6. Note if Privacy Mode is on (affects model behavior)
7. Report at forum.cursor.com or github.com/getcursor/cursor/issues
Enterprise Considerations
Quality baselines: Track AI suggestion accuracy over time per team/project
Model pinning: If a model update degrades quality, temporarily switch to a different model while reporting
Rule audits: Periodically review .cursor/rules/ for outdated or conflicting rules
Training: Ensure team knows the difference between context, model, and prompt issues
