Large Codebase Strategies

You joined a team working on a 300,000-line TypeScript monolith. You open Cursor, ask it to explain the authentication flow, and it comes back with a vague answer that misses half the middleware chain. You try Agent mode for a feature, and it creates a new file from scratch instead of integrating with the existing service layer three directories deep. The codebase is too large for the AI to hold in context all at once, and without guidance, it makes assumptions that do not match your architecture.

Large codebases require a fundamentally different approach to AI-assisted development. You need to guide the AI to the right parts of the codebase, document the patterns it cannot infer, and structure your prompts around scoped, incremental changes.

What You’ll Walk Away With

• A rules-based approach to encoding domain knowledge the AI cannot infer from code alone
• Context management strategies that point the agent at the right files without burning your token budget
• Prompt patterns designed for scoped, incremental changes in large codebases
• Indexing and workspace configuration for optimal performance

Write Rules for Domain-Specific Knowledge

Think about what you would tell a new hire on their first day. What context would they need to start making meaningful contributions? That same context is valuable for Cursor.

Create .cursor/rules/ files that capture knowledge not obvious from reading the code:

---
description: Add a new API endpoint
alwaysApply: false
---

When creating new API endpoints:

1. Define the route in src/routes/[domain]/index.ts
2. Create the controller in src/controllers/[domain]/
3. Add validation schemas in src/schemas/[domain].ts using Zod
4. Register the route in src/app.ts under the appropriate middleware group
5. All endpoints must use the withAuth middleware unless explicitly public
6. Error responses use our standard format: { error: string, code: string, details?: unknown }

See @src/routes/users/index.ts for a complete example.

Tip

Copy-paste rule for file conventions:

Create .cursor/rules/file-conventions.mdc:

---
globs: "*.ts"
alwaysApply: true
---

- Use kebab-case for file names (user-service.ts, not userService.ts)
- Use camelCase for function and variable names
- Use PascalCase for classes, interfaces, and type aliases
- Use UPPER_SNAKE_CASE for constants
- Prefer named exports over default exports
- One primary export per file

Auto-Attach Rules with Glob Patterns

Rules matching specific file patterns are automatically included when the agent works with matching files. Your backend conventions only load for backend files, frontend conventions only load for frontend work:

---
globs: "src/api/**/*.ts"
---

Backend API conventions:
- All handlers receive (req: Request, res: Response, next: NextFunction)
- Use the logger from @src/lib/logger, never console.log
- Database queries go through the repository layer, never raw SQL in handlers
- All mutations must be wrapped in transactions

Scope Down Every Prompt

The single most important habit for large codebases: never ask Agent to do too much at once. Instead of “add role-based access control to the application,” break it down:

1. “Add a role column to the users table and create the migration” (1-2 files)
2. “Create a withRole middleware that checks user roles, following the pattern in @src/middleware/auth.ts” (1-2 files)
3. “Apply the withRole('admin') middleware to the admin routes in @src/routes/admin/index.ts” (1 file)
4. “Add tests for the role middleware in @src/middleware/tests/role.test.ts” (1 file)

Each step is small enough for the agent to hold all relevant context and produce accurate output. Each step builds on committed, verified work from the previous step.

Tip

Copy-paste prompt for scoped implementation:

I need to add email notification support. Start with just the email service layer.

Create src/services/email-service.ts that:
- Uses Resend as the email provider (see @package.json for the dependency)
- Follows the same service pattern as @src/services/payment-service.ts
- Exports sendEmail(to, subject, htmlBody) and sendTemplateEmail(to, templateId, variables)
- Includes proper error handling and retry logic
- Logs all email sends using our logger from @src/lib/logger.ts

Do NOT create routes, controllers, or templates yet. Just the service layer.

Use Chat to Get Up to Speed

When navigating an unfamiliar part of a large codebase, use Ask mode before making any changes:

Trace the request lifecycle for POST /api/orders/create.

Start from the route definition, through all middleware, into the controller,
through the service layer, and into the database queries. List every file
in the call chain and explain what each one does.

Include error handling paths -- what happens when validation fails,
when the database is unavailable, and when the payment provider rejects.

This kind of exploration in Ask mode takes 30 seconds and saves 15 minutes of manual file navigation.

Pick the Right Tool for Each Edit

Tool	Best For	Scope	Speed
Tab	Quick manual edits with AI suggestions	Single cursor position	Instant
Inline Edit (Cmd/Ctrl+K)	Focused changes to selected code	Single file	Fast
Agent (Cmd/Ctrl+I)	Multi-file features and refactoring	Multiple files	Thorough

In large codebases, Tab and Inline Edit handle 60-70% of your changes. They are faster, more predictable, and do not require the AI to understand the entire project. Save Agent for changes that genuinely span multiple files.

Tip

Copy-paste for targeted inline edit:

Select a function, press Cmd/Ctrl+K, and paste:

Refactor this function to use async/await instead of .then() chains. Preserve all error handling. Do not change the function signature or return type.

Context Management at Scale

Use @-Mentions Liberally

In large codebases, the agent needs your help finding the right files:

Add a new user notification preferences endpoint.

Follow the patterns in:
- @src/routes/users/index.ts (route definition)
- @src/controllers/users/profile.ts (controller pattern)
- @src/schemas/user.ts (validation schema)
- @src/services/user-service.ts (service layer)

The new endpoint should be PATCH /api/users/notification-preferences

Use .cursorignore for Noise Reduction

Exclude directories that add noise without value:

.cursorignore

node_modules/
dist/
build/
.next/
coverage/
*.min.js
*.map
vendor/
__generated__/

This reduces indexing time, keeps the context window clean, and prevents the agent from referencing generated or vendored code.

Start New Chats Often

Long conversations in large codebases are a recipe for confusion. The agent accumulates context from earlier messages and may reference outdated information.

Start a new chat when:

• You move to a different part of the codebase
• You have committed a set of changes and are starting the next piece
• The agent references files or code that no longer exists
• You have been going back and forth for more than 5-6 exchanges

When This Breaks

Agent creates files from scratch instead of integrating with existing patterns. Your rules are not detailed enough. Add a rule that describes the file structure and references canonical examples with @file mentions.

Agent loses context partway through a large change. The change is too big for one prompt. Break it into smaller, committed steps.

Indexing takes too long or uses too much memory. Ensure .cursorignore excludes generated files, build artifacts, and large vendor directories. See Performance Optimization.

Agent follows the wrong conventions. Create glob-scoped rules that auto-attach when editing specific directories. A backend rule that loads for src/api/**/*.ts ensures correct conventions without repeating them in every prompt.

What’s Next

• Custom Rules and Templates — Deep dive into building a comprehensive rules library
• Performance Optimization — Tuning indexing and memory for large projects
• Token Management — Managing costs when context windows are large