Context Management & Development

Context management is the secret to getting great results from Cursor. This 15-minute guide will teach you to wield @ symbols like a pro, manage large codebases efficiently, and develop features with surgical precision.

Understanding Context in AI Development

Tip

Context is everything - The quality of AI assistance is directly proportional to the quality of context you provide.

The Context Window

Token Limits

Standard: 128k tokens (~10,000 lines) Max Mode: Up to 1M tokens (~80,000 lines)

Smart Selection

More context isn’t always better - focused, relevant context produces superior results

Cost Impact

Every token costs money - efficient context management saves significant budget

Performance

Smaller, focused context = faster responses and better accuracy

Mastering @ Symbols

Core @ Symbol Reference

Symbol	Purpose	Best Used For
@Files	Reference specific files	Implementation details, bug fixes
@Folders	Include entire directories	Feature development, refactoring
@Code	Semantic code search	Finding implementations, understanding flow
@Docs	Access documentation	Learning libraries, checking APIs
@Web	Search online resources	Latest updates, solutions
@Definitions	Find symbol definitions	Understanding code structure
@Git	Version control context	History, changes, blame
@Recent-changes	Latest modifications	Continuing work, debugging
@Linter-errors	Current errors	Fixing issues, improving quality

@Files - Precision File Reference

Basic Usage

# Single file
@auth.service.ts

# Multiple files
@auth.service.ts @auth.controller.ts @auth.module.ts

# With path
@src/services/auth.service.ts

Advanced Patterns

# Fuzzy matching
@auth  # Finds auth-related files

# Multiple selection
Type @, then hold Shift and click multiple files

# Recent files
@<Tab> shows recently opened files

Best Practices

• Reference test files with implementation
• Include interface files with implementations
• Add config files when changing behavior
• Reference parent classes for inheritance

@Folders - Directory Context

When to Use @Folders

Use for feature-wide changes, understanding module structure, or refactoring entire components.

1. Feature Development:

   "Implement user authentication using @src/auth/"

2. Module Understanding:

   "Explain how the payment system works @src/payments/"

3. Refactoring:

   "Refactor to use dependency injection @src/services/"

Caution

Avoid using @Folders on directories with 100+ files - it can overwhelm the context window.

@Code - Semantic Search

The most powerful @ symbol for understanding codebases:

Finding Implementations

# Find where a function is implemented
@Code "validateUser implementation"

# Locate usage patterns
@Code "where is Redis cache used"

# Understand data flow
@Code "how user data flows through the system"

Architecture Queries

# Design patterns
@Code "repository pattern implementations"

# Cross-cutting concerns
@Code "error handling strategy"

# Integration points
@Code "external API calls"

Debugging

# Find related code
@Code "functions that call sendEmail"

# Trace execution
@Code "authentication flow from login to dashboard"

# Locate similar patterns
@Code "similar validation logic"

@Docs - Documentation Access

Indexed Docs

Access your project’s documentation instantly

External Docs

Combined with MCP servers like Context7 for library docs

Usage patterns:

# Project documentation
@Docs "API authentication"

# With Context7 MCP
"How do I use Stripe webhooks? @Docs with context7"

# Architecture decisions
@Docs "database schema design"

@Git - Version Control Context

History Analysis

# Recent changes
@Git "changes in last week"

# Feature history
@Git "commits related to authentication"

# Bug introduction
@Git "when was this bug introduced"

Blame and Authors

# Who wrote this
@Git "who last modified auth.service.ts"

# Understanding decisions
@Git "why was caching added here"

# Team patterns
@Git "most active contributors to payments module"

Branch Comparison

# Feature branches
@Git "differences between main and feature/oauth"

# Release planning
@Git "what's new in release/2.0"

# Conflict resolution
@Git "merge conflicts with main branch"

Context Strategies for Different Tasks

New Feature Development

1. Start Broad:

   "Explain the current user system @src/users/"

2. Zoom In:

   "Focus on user creation @user.service.ts @user.dto.ts"

3. Related Context:

   "Show similar patterns @Code 'entity creation'"

4. Implementation:

   "Implement user preferences with @user.model.ts @preferences.dto.ts"

Debugging Complex Issues

Debugging Context Stack

Layer context from specific to general for effective debugging.

# Layer 1: Error location
@src/api/users/users.controller.ts
@Linter-errors

# Layer 2: Related files
@src/api/users/users.service.ts
@src/api/users/dto/

# Layer 3: Recent changes
@Recent-changes
@Git "recent changes to users module"

# Layer 4: System understanding
@Code "user data flow"

Large Refactoring

Planning Phase

Use Ask mode with broad context:

"Analyze the impact of changing our ORM
@src/models/ @src/repositories/ @Code 'database queries'"

Execution Phase

Use Agent mode with focused context:

"Migrate UserRepository to new ORM pattern
@src/repositories/user.repository.ts
@src/models/user.model.ts
@migrations/"

Verification Phase

Test-driven context:

"Verify all tests pass after refactoring
@src/repositories/user.repository.spec.ts
@Linter-errors"

Advanced Context Techniques

Context Layering

Build context incrementally for complex tasks:

# Base layer
@auth.service.ts

# Add tests
@auth.service.ts @auth.service.spec.ts

# Add dependencies
@auth.service.ts @auth.service.spec.ts @jwt.service.ts

# Add configuration
@auth.service.ts @auth.service.spec.ts @jwt.service.ts @config/auth.config.ts

Context Templates

Create reusable context patterns:

Feature Template

# Feature Context Template
@src/features/[feature]/
@src/features/[feature]/dto/
@src/features/[feature]/tests/
@Code "[feature] implementation"
@Docs "[feature] requirements"

Debug Template

# Debug Context Template
@[error-file]
@Linter-errors
@Recent-changes
@Git "recent commits touching [error-file]"
@Code "functions calling [error-function]"

Refactor Template

# Refactor Context Template
@[target-directory]/
@Code "[old-pattern] usage"
@Code "[new-pattern] examples"
@Git "previous refactoring commits"

Dynamic Context Management

Context Switching

Use keyboard shortcuts to quickly adjust context without breaking flow.

Action	Shortcut	When to Use
Add file	@ then filename	Need specific file
Remove from context	Click ✕ on pill	Too much context
Clear all context	/Reset Context	Starting fresh
Add open files	/Add Open Files	Working across multiple files

Optimizing for Large Codebases

Indexing Strategies

1. Enable Smart Indexing:

   • Settings → Indexing & Docs
   • Enable “Include Project Structure”
   • Set appropriate ignore patterns

2. Optimize .gitignore:

   # Cursor-specific ignores
   node_modules/
   dist/
   build/
   *.log
   .env*
   coverage/

3. Use .cursorignore:

   # Additional Cursor-only ignores
   test-data/
   migrations/data/
   docs/legacy/

Performance Patterns

Chunk Large Tasks

Break down into smaller, focused operations

Progressive Context

Start minimal, add context as needed

Clear Regularly

Reset context between major tasks

Use Specific Paths

Full paths are faster than fuzzy search

Context Anti-Patterns to Avoid

❌ Common Mistakes

Too Much Context

❌ BAD: @src/ "Fix the authentication bug"

✅ GOOD: @src/auth/auth.service.ts @logs/auth-error.log
"Fix the JWT expiration bug on line 47"

Missing Related Files

❌ BAD: @user.service.ts "Add validation"

✅ GOOD: @user.service.ts @user.dto.ts @validation/
"Add validation matching our patterns"

Ignoring History

❌ BAD: "Why doesn't this work?"

✅ GOOD: @feature.ts @Git "recent changes"
"Why doesn't this work after recent changes?"

Real-World Context Workflows

Scenario: Adding API Endpoint

Step 1: Understand existing patterns
@Code "POST endpoint implementations" @src/api/

Step 2: Focus on specific module
@src/api/products/ @src/api/products/dto/

Step 3: Implementation with examples
"Create POST /api/products/review endpoint"
@src/api/products/products.controller.ts
@src/api/products/products.service.ts
@src/api/products/dto/create-review.dto.ts

Step 4: Testing
@src/api/products/products.controller.spec.ts
"Add tests for the review endpoint"

Scenario: Performance Debugging

Step 1: Identify slow areas
@Code "database queries" @logs/performance.log

Step 2: Focus on bottleneck
@src/services/report.service.ts
@Code "functions calling generateReport"

Step 3: Optimization
@src/services/report.service.ts @src/db/queries/
"Optimize the report generation using batch queries"

Measuring Context Effectiveness

Tip

Good context management can reduce task completion time by 50-70% and improve code quality significantly.

Metrics to Track

1. Tokens per task - Aim for < 50k tokens
2. Context switches - Fewer is better
3. AI accuracy - Should improve with better context
4. Time to solution - Faster with optimal context

Next Steps

Continue to First Feature

Now let’s put all your skills together and build your first AI-assisted feature.

First Feature →

Time: 15 minutes

Tip

Pro Tip: Create a personal context cheat sheet with your most-used patterns. Pin it in your workspace for quick reference.