Large Codebase Strategies: Tips 76-90

Your project hit 200,000 lines of code. Cursor’s indexing takes 20 minutes, agent responses reference files from two years ago, and Tab suggestions pull patterns from deprecated modules. The tool that made you faster on small projects is now slowing you down on the project that matters. These 15 tips solve the scaling problem.

What You Will Walk Away With

• An indexing strategy that keeps Cursor fast on codebases over 500k lines
• Context budget management that prevents the agent from drowning in irrelevant files
• Multi-root workspace configurations for monorepos and multi-repo setups
• Scoped search and navigation techniques that find the right code in seconds, not minutes
• Architectural analysis prompts that help you understand unfamiliar areas of a large codebase

Indexing Strategy

Tip 76: Configure Exclusions Before Opening a Large Project

The first time you open a large project, Cursor indexes everything. If your node_modules has 100,000 files, that is 100,000 files consuming memory and CPU before you write a single line of code. Configure exclusions first:

Create or update .cursorignore in your project root (works like .gitignore):

# Build artifacts
dist/
build/
.next/
out/
coverage/

# Dependencies
node_modules/
vendor/
.pnp/

# Generated code
*.generated.ts
*.generated.js
prisma/generated/
graphql/generated/

# Large binary files
*.wasm
*.map
*.min.js
*.min.css
*.bundle.js

# Lock files (huge, rarely useful for AI)
package-lock.json
pnpm-lock.yaml
yarn.lock

Do not exclude your source code

A common mistake is excluding too aggressively. Never exclude your actual source directories (src/, lib/, app/), test files, or configuration files. The AI needs these to understand your project.

Tip 77: Open Specific Packages Instead of the Monorepo Root

In a monorepo with 20 packages, opening the root directory forces Cursor to index everything. Instead, open only the packages you are actively working on:

# Instead of:
cursor ~/projects/big-monorepo

# Open specific packages as a multi-root workspace:
cursor ~/projects/big-monorepo/packages/web \
       ~/projects/big-monorepo/packages/api \
       ~/projects/big-monorepo/packages/shared

Or create a workspace file for common combinations:

// web-api.code-workspace
{
  "folders": [
    { "path": "packages/web", "name": "Web App" },
    { "path": "packages/api", "name": "API Server" },
    { "path": "packages/shared", "name": "Shared Types" },
    { "path": "packages/config", "name": "Config" }
  ]
}

Tip 78: Monitor and Manage Indexing Health

Check indexing status regularly in Settings > Indexing and Docs. Healthy benchmarks:

Codebase Size	Expected Index Time	Index Size
Under 10k files	1-3 minutes	Under 500 MB
10k-50k files	3-10 minutes	500 MB - 2 GB
50k-200k files	10-30 minutes	2-5 GB
Over 200k files	Use exclusions aggressively	Target under 5 GB

If indexing exceeds these times, your exclusions need work. The most common culprits: node_modules not excluded, large generated files, or binary assets in the source tree.

Context Budget Management

Tip 79: Think in Context Budgets

Every agent conversation has a finite context window. In a large codebase, you will hit this limit quickly if you reference too many files. Think of context as a budget:

• Budget: ~200k tokens per conversation (varies by model and mode)
• Cost per file: A typical 200-line TypeScript file costs ~1,000-2,000 tokens
• Cost per directory: Referencing @src/ on a 500-file project costs your entire budget

The discipline: reference the minimum number of files needed for the task. Start narrow and expand only if the agent says it needs more context.

Tip 80: Use Summary Files for Large Modules

For modules too large to reference directly, create a summary file that the agent can reference instead:

src/payments/ARCHITECTURE.md

# Payments Module Architecture

## Key Files
- `service.ts` - Core payment processing (Stripe integration)
- `webhook.ts` - Webhook handlers for payment events
- `types.ts` - TypeScript interfaces for payment entities
- `repository.ts` - Database operations (PostgreSQL via Drizzle)

## Data Flow
1. Client calls POST /api/payments/checkout
2. service.ts creates Stripe session
3. Stripe sends webhook to webhook.ts
4. webhook.ts updates payment status via repository.ts
5. WebSocket notifies client of status change

## Key Constraints
- All amounts in cents (integer, never float)
- Idempotency keys required for all Stripe calls
- Webhook verification must happen before processing

Now instead of @src/payments/ (which might consume 50k tokens), reference @src/payments/ARCHITECTURE.md (2k tokens) and only pull in specific files as needed.

Tip 81: Use Scoped Agent Conversations

For large codebases, scope every agent conversation to a specific area:

Copy-paste scoped agent prompt template

Context: I am working in the payments module. Only reference files in @src/payments/ and @src/shared/types/.

Task: Add a refund endpoint that calls Stripe’s refund API, updates the payment status in our database, and sends a notification email.

Constraints: Follow the patterns in @src/payments/service.ts for Stripe calls and @src/payments/repository.ts for database operations. Do not modify any files outside of @src/payments/.

The explicit scope prevents the agent from wandering into unrelated modules and consuming your context budget on irrelevant code.

Navigation at Scale

Tip 82: Combine Semantic Search with Grep for Precision

In a large codebase, neither semantic search nor text search alone is sufficient:

• Semantic search finds conceptually related code but may return results from deprecated modules
• Text search (grep) finds exact matches but misses code that does the same thing with different names

The combined workflow:

Find all code that handles subscription renewal. Use semantic search
to identify the relevant modules, then grep for specific function calls
to 'renewSubscription', 'processRenewal', and 'handleRenewalWebhook'.
Show me results only from the active codebase -- ignore anything in
src/legacy/ or src/deprecated/.

Tip 83: Use @codebase Search for Cross-Module Understanding

When you need to understand how a concept spans multiple modules:

Copy-paste cross-module analysis prompt

@codebase How does user authentication flow through this application? Trace the path from the login API endpoint through middleware, services, and database queries. Show me the key files involved and the data transformations at each step.

This prompt triggers Cursor’s semantic understanding of the entire indexed codebase. It is slower than scoped searches but gives you the full picture when you need to understand cross-cutting concerns.

Tip 84: Build Mental Maps of Unfamiliar Code

When onboarding to a large codebase, use the agent to build a structured understanding:

1. “What are the top-level directories and what is each one responsible for?”
2. “Show me the main entry points — where do HTTP requests arrive, and where do scheduled jobs start?”
3. “What are the core domain models and how do they relate to each other?”
4. “What external services does this application depend on? (databases, APIs, message queues)”
5. “Where are the most complex parts of the codebase? Which files have the most dependencies?”

Each question builds on the previous answers, giving you a structured mental map within 30 minutes.

Monorepo-Specific Techniques

Tip 85: Use Workspace-Specific Rules for Monorepos

In a monorepo, different packages often have different conventions. Create package-specific rules:

packages/web/.cursor/rules/web.md       # React conventions
packages/api/.cursor/rules/api.md       # Express conventions
packages/shared/.cursor/rules/shared.md # Pure TypeScript rules
packages/mobile/.cursor/rules/mobile.md # React Native conventions

When the agent edits files in packages/web/, it picks up the React-specific rules. When it edits packages/api/, it gets the Express-specific rules. This prevents the agent from applying React patterns to your API code or vice versa.

Tip 86: Handle Cross-Package Dependencies Explicitly

When a change in one package requires updates in another, be explicit about the dependency chain:

Copy-paste cross-package change prompt

I need to add an “organizationId” field to the User type.

Step 1: Update the type definition in @packages/shared/src/types/user.ts Step 2: Update the database schema in @packages/api/src/db/schema.ts and create a migration Step 3: Update the API endpoints in @packages/api/src/routes/users.ts to accept and validate organizationId Step 4: Update the frontend form in @packages/web/src/components/UserForm.tsx to include the new field

Execute each step in order. Verify that TypeScript compiles after each step before moving to the next.

Tip 87: Use Targeted Refactoring Across Packages

When refactoring a shared type or interface, the blast radius can span the entire monorepo. Control it:

Rename the "UserRole" type to "AccountRole" in @packages/shared/src/types.ts.
Then find and update every import and usage across all packages. Run
pnpm run typecheck at the monorepo root after the rename to verify
there are no broken references.

With YOLO mode enabled, the agent does the rename, runs TypeScript, sees any remaining broken references, and fixes them iteratively.

Performance Optimization

Tip 88: Close Files You Are Not Actively Editing

Cursor uses open files as high-priority context. In a large codebase, you can easily accumulate 30+ open tabs, most of which are irrelevant to your current task. This degrades:

• Tab prediction quality (too much noisy context)
• Agent response time (more files to consider)
• Memory usage (Cursor holds open files in memory)

Close tabs aggressively. Use Cmd+P to jump to files when you need them instead of keeping them permanently open.

Tip 89: Use Max Mode Selectively for Large File Analysis

Max Mode gives extended context windows at higher cost. In a large codebase, it is tempting to keep it always on. Do not. Enable Max Mode only for:

• Analyzing individual files over 3,000 lines
• Understanding complex dependency chains that span 10+ files
• Planning architectural changes that require holding the entire module structure in context

For everything else — implementing features, fixing bugs, writing tests — standard mode is sufficient and significantly cheaper.

Tip 90: Create a “Quick Context” Cheat Sheet for Your Project

For codebases you work on daily, create a quick-reference file that gives the agent instant context:

Copy-paste project context template

.cursor/project-context.md

# Project Quick Context

## Architecture
- Monorepo with 4 packages: web (Next.js), api (Express), shared (types), mobile (React Native)
- PostgreSQL + Redis, deployed on AWS ECS
- Authentication: JWT with refresh tokens, managed by packages/api/src/auth/

## Key Patterns
- All API routes use the pattern in packages/api/src/routes/users.ts
- Database queries go through Drizzle ORM, schema in packages/api/src/db/schema.ts
- Frontend state management via Zustand stores in packages/web/src/stores/
- Shared types exported from packages/shared/src/index.ts

## Common Commands
- pnpm run dev: Start all packages in development
- pnpm run test: Run vitest across all packages
- pnpm run typecheck: TypeScript check across all packages
- pnpm run db:migrate: Run pending database migrations

Reference this file at the start of complex agent conversations to give instant, token-efficient context.

When This Breaks

Indexing is stuck at a percentage and not progressing: Usually a single large file is blocking the indexer. Check for generated files (GraphQL codegen, Prisma client, compiled assets) that slipped past your exclusions. Add them to .cursorignore and restart the index.

Agent gives answers about the wrong part of the codebase: In a monorepo, the agent sometimes confuses similarly named files across packages. Be explicit about which package: “@packages/api/src/users.ts — not the one in packages/web.”

Tab suggestions are slow on large projects: Reduce the number of open tabs, close irrelevant files, and verify your exclusions are working. Tab’s speed is directly proportional to how much context it needs to process.

Agent response quality drops mid-conversation: Context saturation. Start a new conversation. In large codebases, agent conversations should be shorter and more focused than on small projects. Aim for 5-10 exchanges maximum before starting fresh.

What is Next

You can now handle codebases at any scale. Move to Advanced Techniques (Tips 91-105) for MCP server integration, background agents, custom automations, and the expert-level features that push Cursor to its limits.