Context Management: Large Projects and the Context Window Limit

Description

Module 02 explained what the context window is and how it fills up. This capsule applies that knowledge to the real situation: what happens when your project has hundreds or thousands of files and the context window can only handle a fraction? How do coding agents work on projects that don't fit entirely in memory?

The answer is in context management — the strategies for using the context window efficiently, deciding what to include and what to leave out.

---

The Problem: Your Project vs the Context Window

The numbers

TYPICAL PROJECT:

Small project (personal):
→ 50 files → ~100,000 tokens → FITS in a 200K context

Medium project (startup):
→ 500 files → ~1,000,000 tokens → DOESN'T FIT (5x the context)

Large project (enterprise):
→ 5,000+ files → ~10,000,000 tokens → DOESN'T FIT (50x the context)

EVEN THE SMALL PROJECT has a problem:
→ If the project "technically" fits, the context fills up
→ There's no space left for the system prompt, history, tools, and output
→ The quality of the reasoning degrades at 70-80% of capacity

The reality

NO REAL PROJECT FITS COMPLETELY IN THE CONTEXT WINDOW
(except the most trivial ones)

BUT AGENTS WORK WELL ON LARGE PROJECTS.

How? Because they DON'T need to see the whole project.
They need to see WHAT'S RELEVANT to the current task.

---

Strategy 1: Selective Reading

The principle

The agent does NOT read your whole project. It reads only the files relevant to the task.

TASK: "Fix the bug in the login endpoint"

WHAT THE AGENT READS:
→ src/routes/auth.ts           (~800 tokens)
→ src/controllers/AuthController.ts  (~1,200 tokens)
→ src/services/AuthService.ts  (~1,500 tokens)
→ src/utils/validate.ts        (~600 tokens)
──────────────────────────────────────
Total: ~4,100 tokens (2% of the context)

WHAT IT DOESN'T READ (and doesn't need):
→ The other 496 files of the project
→ node_modules/ (never)
→ .git/ (never)
→ Build outputs (dist/, build/)
→ Tests of other modules
→ Unrelated documentation

How the agent decides what to read

1. SEARCH FIRST
   → search("login") → finds 4 relevant files
   → It only reads those 4, not the project's 500

2. FOLLOWING IMPORTS
   → Reads file A → sees "import { validate } from './validate'"
   → Reads validate.ts because it's a direct dependency

3. FOLLOWING THE INSTRUCTION
   → "Look at src/auth/" → only reads files in that folder
   → It doesn't explore the rest

4. STATIC CONTEXT
   → CLAUDE.md says "auth is in src/auth/"
   → The agent knows where to look without exploring

---

Strategy 2: Context Window Budgeting

Distributing the space

CONTEXT WINDOW: 200K tokens

TYPICAL DISTRIBUTION OF A SESSION:

Fixed costs (always present):
├── System prompt:              3,000 tokens   │ 1.5%
├── Tool definitions:           2,000 tokens   │ 1.0%
└── Config (CLAUDE.md, etc):    1,000 tokens   │ 0.5%

Variable costs (grow with the session):
├── Files read:               10,000-40,000   │ 5-20%
├── Search results:            2,000-8,000    │ 1-4%
├── Shell results:             1,000-5,000    │ 0.5-2.5%
├── Conversation history:     10,000-50,000   │ 5-25%
└── Model output:              5,000-20,000   │ 2.5-10%

AVAILABLE BUDGET for the task:
→ In a new session: ~180,000 tokens available
→ After 10 iterations: ~130,000 tokens available
→ After 30 iterations: ~60,000 tokens available
→ After 50 iterations: close to the limit

THE CONTEXT WINDOW IS A FINITE RESOURCE.
EVERY DECISION OF WHAT TO READ HAS A COST.

Practical implications

FOR YOU (DEVELOPER):

1. SHORT SESSIONS > LONG SESSIONS
   → Better 3 sessions of 15 iterations
   → Than 1 session of 45 iterations
   → Each session starts with fresh context

2. SMALL TASKS > HUGE TASKS
   → "Implement the login endpoint" (focused)
   → vs "Implement the whole auth system" (too broad)
   → Large tasks get split into sub-tasks

3. CURATED CONTEXT > MASSIVE CONTEXT
   → Indicating specific files saves exploration
   → Fewer files read = more space for reasoning
   → "Read src/auth/login.ts" > "Investigate how auth works"

---

Strategy 3: Compaction (context compression)

What compaction is

When the context window approaches the limit, modern agents compress the history:

BEFORE COMPACTION:
→ Message 1: [500 tokens]
→ Message 2: [800 tokens]
→ Tool result (file_read): [3,000 tokens]
→ Message 3: [600 tokens]
→ Tool result (file_read): [2,500 tokens]
→ ...
→ Total history: 150,000 tokens

AFTER COMPACTION:
→ [History summary]: [5,000 tokens]
→ Recent messages: [10,000 tokens]
→ Total history: 15,000 tokens

→ Frees up 135,000 tokens of context window
→ BUT loses detail from the early history

What is lost with compaction

WHAT'S KEPT:
→ The general summary of what was done
→ The most recent messages
→ The main decisions

WHAT'S LOST:
→ The exact content of files read at the start
→ The reasoning detail of early iterations
→ Subtle context the summary doesn't capture

IMPLICATION:
→ If an important decision was made at the start,
  the agent can "forget" it after compaction
→ It repeats key information if the session is long
→ Or better: split into shorter sessions

---

Strategy 4: Static Context (configuration files)

The concept

Instead of the agent rediscovering your project each session, you can give it static context that loads automatically:

STATIC CONTEXT = information the agent receives
BEFORE you tell it anything.

CLAUDE.md → For Claude Code
.cursorrules → For Cursor
AGENTS.md → For GitHub Copilot/Codex

CONTAINS:
→ What the project is
→ How it's organized
→ What conventions it uses
→ What patterns to follow
→ What NOT to do

Capsule 05 goes deeper into these files. Here, the point is that they reduce the necessary exploration — the agent already knows things before starting.

WITHOUT STATIC CONTEXT:
→ The agent explores: list_dir, search, file_read x 5
→ ~15,000 tokens of exploration
→ ~5 iterations before starting to work

WITH STATIC CONTEXT (a well-made CLAUDE.md):
→ The agent already knows the structure, conventions, dependencies
→ ~2,000 tokens of CLAUDE.md (loaded automatically)
→ ~1-2 iterations before starting to work
→ Savings: ~13,000 tokens and 3-4 iterations

---

Large Projects: Specific Strategies

For projects with 500+ files

1. DIVIDE AND CONQUER
   → Don't ask "refactor the project"
   → Ask "refactor src/auth/" → one folder at a time
   → Each sub-task is a separate session

2. AIM DIRECTLY
   → Always indicate specific files when possible
   → "The bug is in src/services/PaymentService.ts line 145"
   → vs "There's a bug in the payments"

3. USE STATIC CONTEXT
   → A good CLAUDE.md / .cursorrules saves thousands of tokens
   → Describe the structure in a few lines
   → List the main conventions

4. FOCUSED SESSIONS
   → One task per session
   → If the task is large, split it into R→P→E→V
   → Research in one session, Execute in another if necessary

For monorepos

MONOREPO with frontend/, backend/, shared/:

STRATEGY:
→ Each task indicates the relevant directory
→ "Work in backend/src/auth/ — don't modify frontend/"
→ The agent only reads the files of the indicated directory
→ Less unnecessary exploration

STATIC CONTEXT:
→ The CLAUDE.md can have sections per project:
  "Frontend: React + TypeScript in frontend/src/"
  "Backend: Express + Prisma in backend/src/"
  "Don't modify shared/ without confirmation"

---

When to Start a New Session

SIGNS THAT YOU NEED A NEW SESSION:

1. THE AGENT CONTRADICTS ITSELF
   → "Earlier you said X, now you say Y"
   → Probably: compaction lost context

2. THE QUALITY DROPS
   → The answers are less precise
   → The generated code has more errors
   → The agent seems "confused"

3. THE TASK CHANGED
   → You started with "fix the auth bug"
   → Now you're on "refactor the payments module"
   → Better: a new session with fresh context

4. MANY ITERATIONS
   → More than 20-30 iterations in one session
   → The context window is 50%+ full of history
   → The per-iteration quality is dropping

5. THE AGENT REPEATS TOOL CALLS
   → It reads the same file it already read
   → It searches for the same thing it already searched
   → A sign that it lost previous context

---

Practical Exercise

Exercise 1: Estimate your project's context usage

1. Choose 5 key files from your project
2. Estimate tokens per file (lines × ~5 tokens/line):
   File 1: _____ lines ≈ _____ tokens
   File 2: _____ lines ≈ _____ tokens
   File 3: _____ lines ≈ _____ tokens
   File 4: _____ lines ≈ _____ tokens
   File 5: _____ lines ≈ _____ tokens

3. Total of the 5 files: _____ tokens
4. Percentage of the context window (200K): _____%
5. How many files like these would fit? _____

REFLECTION:
→ Does your project need context management? _____
→ Which strategy would you use? _____

See solution

Example calculation for a typical project:

File	Lines	Estimated tokens
src/app.ts	120	~600
src/routes/users.ts	200	~1,000
src/services/UserService.ts	350	~1,750
src/models/User.ts	80	~400
src/middleware/auth.ts	150	~750

• Total of 5 files: ~4,500 tokens
• Percentage of 200K: ~2.25%
• How many files like these would fit? ~44 groups of 5 files = ~220 files of similar size

Reflection:

• If your project has fewer than 50 key files, context management is moderate — indicating specific files in the prompt is enough.
• If your project has hundreds of files, you need active context management: focused tasks, prompts with exact paths, and a good CLAUDE.md/.cursorrules.
• Remember: the context window isn't just for files. The system prompt, conversation history, tool results, and model output also take up space. In practice, you have ~60-70% of the context available for files read.
• Recommended strategy: Selective Reading (read only what's relevant) + Static Context (CLAUDE.md) for medium and large projects.

Exercise 2: Optimize your prompt

Take a task you gave the agent recently.
Rewrite the prompt to REDUCE the necessary exploration:

ORIGINAL PROMPT:
"_______________________________________________"

OPTIMIZED PROMPT (includes files, patterns, context):
"_______________________________________________
 _______________________________________________
 _______________________________________________"

PREDICTION:
→ Original tool calls: _____
→ Estimated tool calls with the optimized prompt: _____
→ Estimated savings: _____

See guided reflection

Pattern for optimizing any prompt:

An optimized prompt includes three elements that reduce exploration:

1. Exact location: "in src/services/PaymentService.ts" instead of "in the payments module"
2. Pattern to follow: "follow the pattern of src/services/UserService.ts" instead of letting the agent search for conventions
3. Technical context: "we use Express + Prisma + Jest" instead of the agent reading package.json

Concrete example:

• ❌ Original: "Add cache to the database queries" → Estimated tool calls: 8-12 (explore structure, find queries, check if cache already exists, read config...)
• ✅ Optimized: "Add Redis cache to the UserService queries in src/services/UserService.ts. Use the cache pattern from src/services/ProductService.ts. Redis config in src/config/redis.ts. Tests in src/__tests__/user.test.ts." → Estimated tool calls: 3-4 (read pattern, read service, edit, verify)

Typical savings: 50-70% fewer tool calls with a prompt that includes paths, patterns, and stack. This doesn't just save tokens — it reduces the probability of the agent taking incorrect paths during exploration.

---

Common Mistakes

Mistake	Reality
"The agent handles large projects automatically"	You need to split tasks and give context
"Long sessions are more productive"	After 20-30 iterations the quality drops
"More files in the prompt = better"	More files = more tokens spent, not always better
"The agent remembers everything it read"	After compaction, it loses detail from the start
"I don't need static context"	CLAUDE.md / .cursorrules save thousands of tokens per session

---

Summary

THE PROBLEM:
→ Your project doesn't fit entirely in the context window
→ But agents work well on large projects
→ The key: context management

STRATEGIES:
1. Selective Reading: read only relevant files
2. Context Budgeting: distribute the available space
3. Compaction: compress history when it fills up
4. Static Context: CLAUDE.md reduces exploration

FOR LARGE PROJECTS:
→ Divide and conquer (one folder/task at a time)
→ Aim directly (specific files)
→ Use static context (CLAUDE.md, .cursorrules)
→ Focused sessions (one task, fresh context)

WHEN A NEW SESSION:
→ The agent contradicts itself or loses quality
→ The task changed
→ More than 20-30 iterations
→ The agent repeats tool calls

Next capsule: 05 - Configuration and permissions — CLAUDE.md, .cursorrules, AGENTS.md, and the permission system.

---

Resources

1. Anthropic: Context Window Management — How Claude handles context
2. Cursor: Working with Large Projects — Strategies in Cursor
3. Agentic Coding: Context Strategies — Context best practices