Managing Large Codebases with AI: The Context Window Problem

Large codebases (100+ files, 50,000+ lines of code) present a unique challenge for AI tools. The AI can't see everything at once, so you need strategies to provide the right context.

This guide shows you how to use AI effectively on large projects.

The Context Window Challenge

AI models have a “context window”—the amount of text they can process at once:
* GPT-4o: ~128,000 tokens (~300 files)
* Claude 3.5 Sonnet: ~200,000 tokens (~500 files)
* Gemini 3 Pro: ~2,000,000 tokens (~5,000 files)

For projects larger than this, you need strategies.

Strategy 1: The “@Codebase” Search

Instead of loading the entire codebase, search for relevant parts.

Prompt in Cursor:
> “@Codebase find all files related to user authentication”

Cursor will search the codebase and load only relevant files into context.

Strategy 2: The “Focused Context” Approach

Manually specify which files are relevant.

Prompt:
> “@src/auth/login.ts @src/auth/middleware.ts @src/models/User.ts
>
> Refactor the authentication flow to use JWT instead of sessions.”

This gives the AI exactly the context it needs.

Strategy 3: The “Incremental Refactor”

Don't try to refactor everything at once. Work module by module.

Week 1: Refactor the auth module
Week 2: Refactor the payment module
Week 3: Refactor the notification module

Prompt for each module:
> “Refactor the auth module to use modern patterns. Files in scope: @src/auth/*”

Strategy 4: The “Architecture Map”

Create a high-level architecture document that the AI can reference.

File: `ARCHITECTURE.md`
“`markdown

System Architecture

Modules

– Auth: Handles user authentication (JWT-based)
– Payment: Stripe integration for subscriptions
– Notification: Email and push notifications
– Analytics: User behavior tracking

Data Flow

User → Auth → API Gateway → Microservices → Database

Key Files

– `src/auth/middleware.ts` – JWT verification
– `src/payment/stripe.ts` – Stripe integration
– `src/db/schema.ts` – Database schema
“`

Prompt:
> “@ARCHITECTURE.md I need to add a new feature: password reset. Which modules are affected? Generate a plan.”

Strategy 5: The “Dependency Graph”

Use tools to visualize dependencies, then ask AI to analyze them.

“`bash
npx madge –image graph.png src/
“`

Prompt:
> “Analyze this dependency graph. Identify circular dependencies and suggest how to break them.”

Strategy 6: Use Gemini 3 Pro (Antigravity)

If your codebase is huge, use Google Antigravity with Gemini 3 Pro's massive context window.

Prompt in Antigravity:
> “Load the entire codebase into context. Analyze the architecture and suggest improvements.”

Gemini 3 Pro can handle projects with thousands of files.

Real-World Example: Refactoring a Monolith

The Problem

A 10-year-old e-commerce monolith:
* 500 files
* 200,000 lines of code
* Mix of old and new patterns
* No tests

The Approach

Phase 1: Map the Territory
Prompt:
> “@Codebase create a list of all modules and their responsibilities”

Phase 2: Add Tests
Prompt:
> “For each module, generate integration tests”

Phase 3: Refactor Incrementally
Prompt (repeated for each module):
> “Refactor the [module name] to use modern patterns. Keep the same API.”

Phase 4: Extract Microservices
Prompt:
> “Identify which modules can be extracted into separate microservices. Consider coupling and cohesion.”

Best Practices

1. Use `.cursorrules` for Consistency

“`markdown

Project Context

This is a large e-commerce monolith being gradually refactored.

Coding Standards

– Use TypeScript
– Follow the existing module structure
– Add tests for all new code
– Don't break existing APIs
“`

2. Document as You Go

After each refactor, update the architecture docs:

Prompt:
> “Update ARCHITECTURE.md to reflect the changes we just made”

3. Use Git Strategically

Create feature branches for each module refactor:
“`bash
git checkout -b refactor/auth-module
“`

This makes it easier to review and roll back if needed.

4. Leverage AI for Code Navigation

Prompt:
> “@Codebase where is the code that handles password hashing?”

This is faster than manually searching.

5. Ask for Impact Analysis

Before making changes:

Prompt:
> “If I change the signature of the `authenticateUser` function, which files will be affected?”

Conclusion

Managing large codebases with AI requires strategy. You can't just throw the entire codebase at the AI and expect magic. But with the right techniques, AI can help you navigate and refactor even the messiest legacy code.

At BYS Marketing, we've used these strategies to refactor codebases with millions of lines of code. AI makes the impossible manageable.

—

Struggling with a large codebase?
Contact BYS Marketing. We specialize in modernizing legacy systems.