Bugbot - Practical Debugging | Developer Onboarding

How to use Cursor's autonomous debugging mode effectively in production, with real examples and workflows

Bugbot is Cursor's autonomous debugging mode. Here's what actually works in production.

When to Use Bugbot (and When Not)

Good Use Cases

Complex stack traces across multiple files

Problem: Error in frontend, originates in backend,
involves 5+ files

Bugbot excels at: Following error propagation through layers

Race conditions and async bugs

Problem: "Works 90% of time, fails randomly"

Bugbot excels at: Identifying timing issues, missing awaits,
unhandled promise rejections

Unfamiliar codebase

Problem: Bug in legacy code you don't know well

Bugbot excels at: Code archaeology, finding root cause
in unfamiliar territory

Integration issues

Problem: API calls failing, unclear why

Bugbot excels at: Comparing contracts, finding mismatches,
suggesting fixes

When NOT to Use Bugbot

Simple bugs you already understand

Just fix it manually (faster)
Example: Typo in variable name, off-by-one error

Security vulnerabilities

Needs human security review
Example: SQL injection, XSS, auth bypass

Business logic bugs

Bugbot doesn't know your business rules
Example: "Discount calculates wrong" (what's "right"?)

Performance issues requiring profiling

Use profiler first, then AI for optimization
Example: "App is slow" (too vague for Bugbot)

Real Pattern: Client A Checkout Bug

Problem: User checkout fails with international addresses (reported by client)

Before Bugbot (traditional debugging):

Try to reproduce (30 min)
Add logging everywhere (20 min)
Deploy to staging (15 min)
Test multiple countries (45 min)
Find the issue in AddressValidator (30 min)
Fix and test (30 min) Total: ~3 hours

With Bugbot:

Step 1: Prepare context (5 min)

Bug report:
- User: International address (UK)
- Error: "Invalid postal code format"
- Expected: Should accept UK postcodes like "SW1A 1AA"
- Stack trace: [paste]

Files involved:
@src/checkout/CheckoutService.ts
@src/validation/AddressValidator.ts

Reproduction:
1. Add item to cart
2. Enter UK address with space in postcode
3. Click "Complete Order"
4. Error appears

Step 2: Activate Bugbot (10 min)

Bugbot analyzes:
- Identifies AddressValidator uses US-only regex
- Shows the problematic line: /^\d{5}$/
- Explains: Doesn't handle international formats
- Notes: Also affects Canada, Australia, etc.

Step 3: Human reviews diagnosis (2 min)

You: "Correct. We need international postal code support."

Step 4: Bugbot suggests fix (8 min)

Bugbot proposes:
1. Add country-specific regex patterns
2. Update validation logic
3. Add test cases for US, UK, CA, AU formats
4. Handle edge cases (spaces, dashes, mixed case)

Step 5: Human review and refine (5 min)

You: "Good, but also add DE and FR formats.
Use a validation library instead of regex."

Bugbot: Updates to use validator.js library

Step 6: Test and ship

Tests generated: UK, DE, FR, CA, AU formats
All pass

Total: 30 minutes (6x faster)

Key lesson: Bugbot excellent when you have clear reproduction steps and error messages.

Bugbot Context Pattern

What to give Bugbot for best results:

## Bug Report for Bugbot

**Description:** [One sentence summary]

**Environment:**

- Production / Staging / Development
- Frequency: Always / Sometimes / Rarely
- Affects: All users / Specific user type / Specific data

**Reproduction Steps:**

1. [Step by step]
2. [Include sample data if relevant]
3. [Expected vs Actual behavior]

**Error Messages:**
[Paste full stack trace, not screenshot]

**Relevant Files:**
@src/[file1]
@src/[file2]

**Recent Changes:**
[PR # or "No recent changes to this area"]

**What I've tried:**
[Saves Bugbot from suggesting things you already tested]

**Business Context:**
[Why this matters - helps prioritize fix scope]

Bugbot + Rules = Better Fixes

Remember those .cursor/rules/bugbot.md rules from setup? Here's why they matter:

Without rules:

Bug: Login fails with empty password

Bugbot fix:
- Removes password validation
- Removes error handling
- "Now it doesn't error!" 🤦

With rules:

Bug: Login fails with empty password

Bugbot fix:
- Adds proper password validation
- Improves error message
- Adds test case for empty password
- Preserves all other validation

The rules remind Bugbot to:

Explain root cause first
Minimal necessary changes
Add tests
Consider side effects

Common Bugbot Mistakes

Mistake 1: Band-aid over root cause

Example from real project:

Bug: API returns 500 error randomly

Bugbot suggests: Wrap in try-catch, return 200
- This hides the real error!

Better: Bugbot identifies the actual cause
(race condition in database connection pool)

How to prevent:

Ask Bugbot to explain root cause FIRST
Don't accept the first suggestion
Prompt: "Is there a deeper issue causing this?"

Mistake 2: Changing too much

Example:

Bug: Button click doesn't work

Bugbot suggests:
- Rewrite entire component
- Change state management
- Update 5 other components
- Way too much scope!

Better: Fix just the onClick handler

How to prevent:

Use rules: "Minimal changes to fix bug"
Ask: "Can this be fixed with less than 10 lines changed?"

Mistake 3: Breaking other things

Example:

Bug: Date format wrong for US users

Bugbot fix: Changes date format globally
- Breaks it for EU users!

Better: Conditional format based on user locale

How to prevent:

Always ask: "What else uses this code?"
Run full test suite, not just the new test
Manual smoke test of related features

Visual Debugging with Screenshots

AI can now read images. This is powerful for debugging visual issues where "show, don't tell" is more effective.

When Screenshots Help

Visual bugs and layout issues:

Good use case:
"Here's a screenshot of the broken layout [attach image]
Compare with the Figma design [attach design]
What's causing the misalignment?"

Why it works:
AI sees exactly what you see - no need to describe "the button is 3px too far left"

CSS/styling problems:

Problem: "The modal looks wrong on mobile"

Instead of describing:
"The modal header is cut off, the close button overlaps the title,
and the padding seems off..."

Just show:
[Screenshot of broken modal]
"Debug this modal layout issue"

AI can spot:
- Overflow issues
- Z-index problems
- Flexbox/grid misconfigurations
- Responsive breakpoint issues

Comparing states:

"Here are screenshots of the same page:
- Before: [screenshot 1]
- After: [screenshot 2]

Something changed between these. What broke?"

AI can diff visually:
- Identify missing elements
- Spot layout shifts
- Find styling regressions

When Screenshots Hurt

Screenshots are often the wrong tool:

1. Logic bugs (use text instead):

Bad: Screenshot of console with error message
Good: Copy-paste the actual error text

Why: Text is searchable, copy-pasteable, and gives AI full stack trace

2. Code review (use file references):

Bad: Screenshot of code
Good: @filename references or copy-paste code

Why: AI can't jump to definitions or see surrounding context from screenshots

3. Data issues (use actual data):

Bad: Screenshot of database table
Good: Copy-paste SQL query results

Why: AI can analyze actual data structure, not blurry screenshots

4. Performance issues (use profiler output):

Bad: Screenshot of slow page loading
Good: Lighthouse report, profiler data, network waterfall

Why: Screenshots don't show timing, bottlenecks, or metrics

Pattern: Visual for UI, Text for Logic

Bug Type	Use Screenshot	Use Text	Why
Layout broken	✅	❌	Visual problem, visual diagnosis
Button click doesn't work	❌	✅	Logic issue, need stack trace
Colors wrong	✅	❌	Visual comparison easiest
API returns 500	❌	✅	Need error details, not UI
Responsive design issue	✅	❌	Multi-screen comparison
TypeScript error	❌	✅	Need exact error message
Animation janky	✅	❌	Visual perception issue
Database query slow	❌	✅	Need EXPLAIN output

Reading Architecture Diagrams

AI can parse diagrams you have:

You: "Here's our current architecture [attach diagram]
     We're adding real-time notifications.
     Where does this fit? What changes?"

AI: [Reads diagram, suggests modifications]

Useful for:

Reviewing system architecture
Planning new features in context
Identifying integration points
Spotting architectural smells

Not useful for:

Generating diagrams from scratch (use Mermaid in text instead)
Editing diagrams (AI can't output edited images)

Best Practices for Screenshot Debugging

DO:

✅ Annotate screenshots with arrows/highlights if issue is subtle
✅ Include multiple screenshots for context (before/after, desktop/mobile)
✅ Crop to relevant area (no need for entire screen)
✅ Use high-resolution screenshots (text should be readable)
✅ Combine screenshot + relevant code: "Here's the bug [image] in @Component.tsx"

DON'T:

❌ Screenshot text that could be copy-pasted
❌ Screenshot code (use @ references instead)
❌ Use blurry/low-res screenshots
❌ Screenshot cluttered screen with 20 open tabs
❌ Assume AI can edit images (it can only read them)

Example: Effective Visual Debugging

Ineffective:

You: "The button doesn't look right"
AI: "Can you describe what's wrong?"
You: "It's like... too small? And the color is off?"
AI: "What color should it be?"
[10 messages back and forth]

Effective:

You: "Button styling broken [screenshot of broken button]
     Should look like this [screenshot from design/working version]
     Code: @components/Button.tsx
     Debug the styling issue"

AI: [Reads both screenshots, sees the difference]
"The button is missing padding-x (should be 24px, currently 0)
 and using wrong color variable (--primary-dark instead of --primary)

 In Button.tsx line 15, change:
 className='px-0 bg-primary-dark'
 to:
 className='px-6 bg-primary'"

Time saved: 10 messages → 1 message with screenshots.

When Text Context Still Matters

Screenshots alone often aren't enough:

Incomplete:
[Screenshot of broken page]
"Fix this"

Complete:
[Screenshot of broken page]
"This page breaks on Safari 15+ but works on Chrome
 Code: @pages/dashboard.tsx
 Started after we added @components/Chart.tsx
 Error in console: [paste error]

 Debug the Safari-specific issue"

Golden rule: Screenshots show symptoms, text provides context.

Bugbot Metrics (from our projects)

Debugging time reduction:

Simple bugs: 40-60% faster
- Example: Type errors, null checks, validation bugs

Complex bugs: 60-80% faster
- Example: Race conditions, integration issues,
  async problems

Mysteries: 70-90% faster
- Example: "It works locally but not in prod"

Where Bugbot struggles:

Business logic bugs: 0-20% faster
- Bugbot doesn't know business rules
- Still need human to define "correct" behavior

Performance issues: 30-50% faster
- Needs profiling data first
- Good at suggesting fixes after you identify bottleneck

Intermittent bugs: Variable
- Needs clear reproduction steps
- If you can't reproduce, Bugbot can't either

Real data from Limestone Digital (8 weeks):

Bugs fixed with Bugbot: 47
Average time saved: 1.2 hours per bug
Total time saved: ~56 hours
Bugbot-caused regressions: 3 (caught in review)

Bugbot - Practical Debugging

On this page