cim_summary/Best Practices for Debugging with Cursor_ Becoming.md at 9c916d12f4cd8090a5ebc7941e9fa9e6e0702798

Files

admin 9c916d12f4 feat: Production release v2.0.0 - Simple Document Processor

Major release with significant performance improvements and new processing strategy.

## Core Changes
- Implemented simple_full_document processing strategy (default)
- Full document → LLM approach: 1-2 passes, ~5-6 minutes processing time
- Achieved 100% completeness with 2 API calls (down from 5+)
- Removed redundant Document AI passes for faster processing

## Financial Data Extraction
- Enhanced deterministic financial table parser
- Improved FY3/FY2/FY1/LTM identification from varying CIM formats
- Automatic merging of parser results with LLM extraction

## Code Quality & Infrastructure
- Cleaned up debug logging (removed emoji markers from production code)
- Fixed Firebase Secrets configuration (using modern defineSecret approach)
- Updated OpenAI API key
- Resolved deployment conflicts (secrets vs environment variables)
- Added .env files to Firebase ignore list

## Deployment
- Firebase Functions v2 deployment successful
- All 7 required secrets verified and configured
- Function URL: https://api-y56ccs6wva-uc.a.run.app

## Performance Improvements
- Processing time: ~5-6 minutes (down from 23+ minutes)
- API calls: 1-2 (down from 5+)
- Completeness: 100% achievable
- LLM Model: claude-3-7-sonnet-latest

## Breaking Changes
- Default processing strategy changed to 'simple_full_document'
- RAG processor available as alternative strategy 'document_ai_agentic_rag'

## Files Changed
- 36 files changed, 5642 insertions(+), 4451 deletions(-)
- Removed deprecated documentation files
- Cleaned up unused services and models

This release represents a major refactoring focused on speed, accuracy, and maintainability.

2025-11-09 21:07:22 -05:00

23 KiB

Raw Blame History

Best Practices for Debugging with Cursor: Becoming a Senior Developer-Level Debugger

Transform Cursor into an elite debugging partner with these comprehensive strategies, workflow optimizations, and hidden power features that professional developers use to maximize productivity.

Core Debugging Philosophy: Test-Driven Development with AI

Write Tests First, Always

The single most effective debugging strategy is implementing Test-Driven Development (TDD) with Cursor. This gives you verifiable proof that code works before deployment¹²³.

Workflow:

Start with: "Write tests first, then the code, then run the tests and update the code until tests pass"¹
Enable YOLO mode (Settings → scroll down → enable YOLO mode) to allow Cursor to automatically run tests, build commands, and iterate until passing¹⁴
Let the AI cycle through test failures autonomously—it will fix lint errors and test failures without manual intervention¹⁵

YOLO Mode Configuration: Add this prompt to YOLO settings:

any kind of tests are always allowed like vitest, npm test, nr test, etc. also basic build commands like build, tsc, etc. creating files and making directories (like touch, mkdir, etc) is always ok too

This enables autonomous iteration on builds and tests¹⁴.

Advanced Debugging Techniques

1. Log-Driven Debugging Workflow

When facing persistent bugs, use this iterative logging approach¹⁶:

Tell Cursor: "Please add logs to the code to get better visibility into what is going on so we can find the fix. I'll run the code and feed you the logs results"¹
Run your code and collect log output
Paste the raw logs back into Cursor: "Here's the log output. What do you now think is causing the issue? And how do we fix it?"¹
Cursor will propose targeted fixes based on actual runtime behavior

For Firebase Projects: Use the logger SDK with proper severity levels⁷:

const { log, info, debug, warn, error } = require("firebase-functions/logger");

// Log with structured data
logger.error("API call failed", {
  endpoint: endpoint,
  statusCode: response.status,
  userId: userId
});

2. Autonomous Workflow with Plan-Approve-Execute Pattern

Use Cursor in Project Manager mode for complex debugging tasks⁵⁸:

Setup .cursorrules file:

You are working with me as PM/Technical Approver while you act as developer.
- Work from PRD file one item at a time
- Generate detailed story file outlining approach
- Wait for approval before executing
- Use TDD for implementation
- Update story with progress after completion

Workflow:

Agent creates story file breaking down the fix in detail
You review and approve the approach
Agent executes using TDD
Agent runs tests until all pass
Agent pushes changes with clear commit message⁵⁸

This prevents the AI from going off-track and ensures deliberate, verifiable fixes.

Context Management Mastery

3. Strategic Use of @ Symbols

Master these context references for precise debugging⁹¹⁰:

@Files - Reference specific files
@Folders - Include entire directories
@Code - Reference specific functions/classes
@Docs - Pull in library documentation (add libraries via Settings → Cursor Settings → Docs)⁴⁹
@Web - Search current information online
@Codebase - Search entire codebase (Chat only)
@Lint Errors - Reference current lint errors (Chat only)⁹
@Git - Access git history and recent changes
@Recent Changes - View recent modifications

Pro tip: Stack multiple @ symbols in one prompt for comprehensive context⁹.

4. Reference Open Editors Strategy

Keep your AI focused by managing context deliberately¹¹:

Close all irrelevant tabs
Open only files related to current debugging task
Use @ to reference open editors
This prevents the AI from getting confused by unrelated code¹¹

5. Context7 MCP for Up-to-Date Documentation

Integrate Context7 MCP to eliminate outdated API suggestions¹²¹³¹⁴:

Installation:

// ~/.cursor/mcp.json
{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    }
  }
}

Usage:

use context7 for latest documentation on [library name]

Add to your cursor rules:

When referencing documentation for any library, use the context7 MCP server for lookups to ensure up-to-date information

Power Tools and Integrations

6. Browser Tools MCP for Live Debugging

Debug live applications by connecting Cursor directly to your browser¹⁵¹⁶:

Setup:

Clone browser-tools-mcp repository
Install Chrome extension
Configure MCP in Cursor settings:

{
  "mcpServers": {
    "browser-tools": {
      "command": "node",
      "args": ["/path/to/browser-tools-mcp/server.js"]
    }
  }
}

Run the server: npm start

Features:

"Investigate what happens when users click the pay button and resolve any JavaScript errors"
"Summarize these console logs and identify recurring errors"
"Which API calls are failing?"
Automatically captures screenshots, console logs, network requests, and DOM state¹⁵¹⁶

7. Sequential Thinking MCP for Complex Problems

For intricate debugging requiring multi-step reasoning¹⁷¹⁸¹⁹:

Installation:

{
  "mcpServers": {
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    }
  }
}

When to use:

Breaking down complex bugs into manageable steps
Problems where the full scope isn't clear initially
Analysis that might need course correction
Maintaining context over multiple debugging steps¹⁷

Add to cursor rules:

Use Sequential thinking for complex reflections and multi-step debugging

8. Firebase Crashlytics MCP Integration

Connect Crashlytics directly to Cursor for AI-powered crash analysis²⁰²¹:

Setup:

Enable BigQuery export in Firebase Console → Project Settings → Integrations
Generate Firebase service account JSON key
Configure MCP:

{
  "mcpServers": {
    "crashlytics": {
      "command": "node",
      "args": ["/path/to/mcp-crashlytics-server/dist/index.js"],
      "env": {
        "GOOGLE_SERVICE_ACCOUNT_KEY": "/path/to/service-account.json",
        "BIGQUERY_PROJECT_ID": "your-project-id",
        "BIGQUERY_DATASET_ID": "firebase_crashlytics"
      }
    }
  }
}

Usage:

"Fetch the latest Crashlytics issues for my project"
"Add a note to issue xyz summarizing investigation"
Use crashlytics:connect command for structured debugging flow²⁰²¹

Cursor Rules & Configuration

9. Master .cursorrules Files

Create powerful project-specific rules²²²³²⁴:

Structure:

# Project Overview
[High-level description of what you're building]

# Tech Stack
- Framework: [e.g., Next.js 14]
- Language: TypeScript (strict mode)
- Database: [e.g., PostgreSQL with Prisma]

# Critical Rules
- Always use strict TypeScript - never use `any`
- Never modify files without explicit approval
- Always read relevant files before making changes
- Log all exceptions in catch blocks using Crashlytics

# Deprecated Patterns (DO NOT USE)
- Old API: `oldMethod()` ❌
- Use instead: `newMethod()` ✅

# Common Bugs to Document
[Add bugs you encounter here so they don't recur]

Pro Tips:

Document bugs you encounter in .cursorrules so AI avoids them in future²³
Use cursor.directory for template examples¹¹²³
Stack multiple rule files: global rules + project-specific + feature-specific²⁴
Use .cursor/rules directory for organized rule management²⁴²⁵

10. Global Rules Configuration

Set personal coding standards in Settings → Rules for AI¹¹⁴:

- Always prefer strict types over any in TypeScript
- Ensure answers are brief and to the point
- Propose alternative solutions when stuck
- Skip unnecessary elaborations
- Emphasize technical specifics over general advice
- Always examine relevant files before taking action

11. Notepads for Reusable Context

Use Notepads to store debugging patterns and common fixes¹¹²⁶²⁷²⁸:

Create notepads for:

Common error patterns and solutions
Debugging checklists for specific features
File references for complex features
Standard prompts like "code review" or "vulnerability search"

Usage: Reference notepads in prompts to quickly load debugging context without retyping²⁷²⁸.

Keyboard Shortcuts for Speed

Essential Debugging Shortcuts²⁹³⁰³¹:

Core AI Commands:

Cmd/Ctrl + K - Inline editing (fastest for quick fixes)¹³²³⁰
Cmd/Ctrl + L - Open AI chat³⁰³¹
Cmd/Ctrl + I - Open Composer³⁰
Cmd/Ctrl + Shift + I - Full-screen Composer³⁰

When to use what:

Use Cmd+K for fast, localized changes to selected code¹³²
Use Cmd+L for questions and explanations³¹
Use Cmd+I (Composer) for multi-file changes and complex refactors³²⁴

Navigation:

Cmd/Ctrl + P - Quick file open²⁹³³
Cmd/Ctrl + Shift + O - Go to symbol in file³³
Ctrl + G - Go to line (for stack traces)³³
F12 - Go to definition²⁹

Terminal:

`Cmd/Ctrl + `` - Toggle terminal²⁹³⁰
Cmd + K in terminal - Clear terminal (note: may need custom keybinding)³⁴³⁵

Advanced Workflow Strategies

12. Agent Mode with Plan Mode

Use Plan Mode for complex debugging³⁶³⁷:

Hit Cmd+N for new chat
Press Shift+Tab to toggle Plan Mode
Describe the bug or feature
Agent researches codebase and creates detailed plan
Review and approve before implementation

Agent mode benefits:

Autonomous exploration of codebase
Edits multiple files
Runs commands automatically
Fixes errors iteratively³⁷³⁸

13. Composer Agent Mode Best Practices

For large-scale debugging and refactoring³⁹⁵⁴:

Setup:

Always use Agent mode (toggle in Composer)
Enable YOLO mode for autonomous execution⁵⁴
Start with clear, detailed problem descriptions

Workflow:

Describe the complete bug context in detail
Let Agent plan the approach
Agent will:
- Pull relevant files automatically
- Run terminal commands as needed
- Iterate on test failures
- Fix linting errors autonomously⁴

Recovery strategies:

If Agent goes off-track, hit stop immediately
Say: "Wait, you're way off track here. Reset, recalibrate"¹
Use Composer history to restore checkpoints⁴⁰⁴¹

14. Index Management

Keep your codebase index fresh¹¹:

Manual resync: Settings → Cursor Settings → Resync Index

Why this matters:

Outdated index causes incorrect suggestions
AI may reference deleted files
Prevents hallucinations about code structure¹¹

15. Error Pattern Recognition

Watch for these warning signs and intervene¹⁴²:

AI repeatedly apologizing
Same error occurring 3+ times
Complexity escalating unexpectedly
AI asking same diagnostic questions repeatedly

When you see these:

Stop the current chat
Start fresh conversation with better context
Add specific constraints to prevent loops
Use "explain your thinking" to understand AI's logic⁴²

Firebase-Specific Debugging

16. Firebase Logging Best Practices

Structure logs for effective debugging⁷⁴³:

Severity levels:

logger.debug("Detailed diagnostic info")
logger.info("Normal operations")
logger.warn("Warning conditions")
logger.error("Error conditions", { context: details })
logger.write({ severity: "EMERGENCY", message: "Critical failure" })

Add context:

// Tag user IDs for filtering
Crashlytics.setUserIdentifier(userId)

// Log exceptions with context
Crashlytics.logException(error)
Crashlytics.log(priority, tag, message)

View logs:

Firebase Console → Functions → Logs
Cloud Logging for advanced filtering
Filter by severity, user ID, version⁴³

17. Version and User Tagging

Enable precise debugging of production issues⁴³:

// Set version
Crashlytics.setCustomKey("app_version", "1.2.3")

// Set user identifier
Crashlytics.setUserIdentifier(userId)

// Add custom context
Crashlytics.setCustomKey("feature_flag", "beta_enabled")

Filter crashes in Firebase Console by version and user to isolate issues.

Meta-Strategies

18. Minimize Context Pollution

Project-level tactics:

Use .cursorignore similar to .gitignore to exclude unnecessary files⁴⁴
Keep only relevant documentation indexed⁴
Close unrelated editor tabs before asking questions¹¹

19. Commit Often

Let Cursor handle commits⁴⁰:

Push all changes, update story with progress, write clear commit message, and push to remote

This creates restoration points if debugging goes sideways.

20. Multi-Model Strategy

Don't rely on one model⁴⁴⁵:

Use Claude 3.5 Sonnet for complex reasoning and file generation⁵⁸
Try different models if stuck
Some tasks work better with specific models

21. Break Down Complex Debugging

When debugging fails repeatedly³⁹⁴⁰:

Break the problem into smallest possible sub-tasks
Start new chats for discrete issues
Ask AI to explain its approach before implementing
Use sequential prompts rather than one massive request

Troubleshooting Cursor Itself

When Cursor Misbehaves:

Context loss issues:⁴⁶⁴⁷⁴⁸

Check for .mdc glob attachment issues in settings
Disable workbench/editor auto-attachment if causing crashes⁴⁶
Start new chat if context becomes corrupted⁴⁸

Agent loops:⁴⁷

Stop immediately when looping detected
Provide explicit, numbered steps
Use "complete step 1, then stop and report" approach
Restart with clearer constraints

Rule conflicts:⁴⁹⁴⁶

User rules may not apply automatically - use project .cursorrules instead⁴⁹
Test rules by asking AI to recite them
Check rules are being loaded (mention them in responses)⁴⁶

Ultimate Debugging Checklist

Before starting any debugging session:

Setup:

Enable YOLO mode
Configure .cursorrules with project specifics
Resync codebase index
Close irrelevant files
Add relevant documentation to Cursor docs

During Debugging:

Write tests first before fixing
Add logging at critical points
Use @ symbols to reference exact files
Let Agent run tests autonomously
Stop immediately if AI goes off-track
Commit frequently with clear messages

Advanced Tools (when needed):

Context7 MCP for up-to-date docs
Browser Tools MCP for live debugging
Sequential Thinking MCP for complex issues
Crashlytics MCP for production errors

Recovery Strategies:

Use Composer checkpoints to restore state
Start new chat with git diff context if lost
Ask AI to recite instructions to verify context
Use Plan Mode to reset approach

By implementing these strategies systematically, you transform Cursor from a coding assistant into an elite debugging partner that operates at senior developer level. The key is combining AI autonomy (YOLO mode, Agent mode) with human oversight (TDD, plan approval, checkpoints) to create a powerful, verifiable debugging workflow¹⁵⁸⁴. ⁵⁰⁵¹⁵²⁵³⁵⁴⁵⁵⁵⁶⁵⁷⁵⁸⁵⁹⁶⁰⁶¹⁶²⁶³⁶⁴⁶⁵⁶⁶⁶⁷⁶⁸⁶⁹⁷⁰⁷¹⁷²⁷³⁷⁴⁷⁵⁷⁶⁷⁷⁷⁸⁷⁹⁸⁰⁸¹⁸²⁸³⁸⁴⁸⁵⁸⁶⁸⁷⁸⁸⁸⁹⁹⁰⁹¹⁹²⁹³⁹⁴⁹⁵⁹⁶⁹⁷⁹⁸

⁂

23 KiB Raw Blame History

Best Practices for Debugging with Cursor: Becoming a Senior Developer-Level Debugger

Core Debugging Philosophy: Test-Driven Development with AI

Advanced Debugging Techniques

Context Management Mastery

Power Tools and Integrations

Cursor Rules & Configuration

Keyboard Shortcuts for Speed

Advanced Workflow Strategies

Firebase-Specific Debugging

Meta-Strategies

Troubleshooting Cursor Itself

Ultimate Debugging Checklist

23 KiB

Raw Blame History