Module 6: Context Management for Large Projects
Context Window Reality — 1M Tokens
Context Window Reality — 1M Tokens
Capsule description
"1 million tokens" sounds like infinite capacity. It isn't. In this capsule you're going to understand the real limits of the context window, recognize the symptoms of context pressure, and learn the practical rules that separate effective use from wasted context.
The key data point: 1M tokens ≈ ~750K tokens of code (after the overhead of system instructions) ≈ ~25K effective lines of code. That covers a complete medium project, but not a large one. And the quality of Claude Code's answers degrades well before reaching the technical limit.
The Real Numbers
From 1M tokens to lines of code
1,000,000 tokens (total context window)
- ~100,000 tokens (system prompt, instructions, conversation history)
- ~150,000 tokens (tool and format overhead)
= ~750,000 tokens available for code
750,000 tokens ÷ ~3 tokens per line of Python code
= ~250,000 theoretical lines
BUT: the quality degrades significantly after ~50K tokens of code
= ~15,000-25,000 effective high-quality lines
The 70% rule
In practice, use at most 70% of the context window for code. The remaining 30% is for:
- Conversation (your prompts + Claude's answers)
- The system prompt and tools
- A margin for Claude to "think" (reasoning tokens)
Practical rule: if your project has 20K lines, it fits. If it has 100K lines, you need chunking.
Symptoms of Context Pressure
How to recognize that Claude Code is losing context
# Symptom 1: Inconsistent answers
> "Add type hints to user_service.py"
# Claude adds correct type hints
> "Now add type hints to order_service.py"
# Claude uses DIFFERENT conventions from user_service
# (e.g., dict vs Dict, str | None vs Optional[str])
# Symptom 2: "Forgetting" files
> "Update the UserService import in all the files"
# Claude updates 7 of 9 files — it forgot 2
# Symptom 3: Contradictory code
> "Create a function to calculate tax"
# Claude creates calculate_tax() with a 16% rate
# 50 messages later:
> "Use the tax function in order_service"
# Claude creates ANOTHER calculate_tax() function with a 21% rate
# It forgot it had already created one
# Symptom 4: Generic answers
> "How does this project handle errors?"
# Claude gives a generic answer about error handling
# instead of describing the project's specific pattern
What to do when you detect these symptoms
- Reduce context: remove irrelevant files from the conversation
- New session: start fresh with only the necessary files
- CLAUDE.md: add project context that doesn't require whole files
- Chunking: divide the work into smaller pieces
What to Include and What to Exclude
Always include
| Type | Why | Example |
|---|---|---|
| Interfaces/types | They define contracts between modules | models.py, types.py, schemas.py |
| The file you're modifying | Claude needs to see the current code | order_service.py |
| CLAUDE.md | Persistent project context | .claude/CLAUDE.md |
| Relevant tests | To verify changes | test_order_service.py |
| Relevant config | To understand the environment | settings.py (only the relevant sections) |
Include selectively
| Type | When to include | When to exclude |
|---|---|---|
| Implementations | If you're going to modify them | If you only need the interface |
| Docs | If they inform the task | If it's a generic README |
| Other modules' tests | If they test code you affect | If they're independent |
| Migrations | If you change the schema | If you don't touch the DB |
Never include
| Type | Why not |
|---|---|
| node_modules / venv | Thousands of irrelevant files |
| Build artifacts | Generated, not informative |
| Images / binaries | They're not code |
| Logs | Changing and long |
| The whole codebase "just in case" | Dilutes what matters |
Progressive Context Loading
The most effective pattern
Instead of giving everything at the start, load context progressively:
# Session: Refactor order_service.py
# Step 1: Minimum context
> "Read src/services/order_service.py and tell me what
each function does"
# Claude reads 1 file, responds with an analysis
# Step 2: Add what's needed
> "Now also read src/models/order.py and
src/models/product.py to understand the types"
# Claude has 3 files
# Step 3: Add tests
> "Read tests/test_order_service.py to understand
the expected behavior"
# Claude has 4 files — enough to refactor
# NEVER: "Read all of src/ to understand the project"
Comparison: Context Strategies
| Strategy | Context used | Quality | When to use |
|---|---|---|---|
| The whole codebase | 100% | Low (diluted) | Never on large projects |
| Only affected files | 10-20% | High | Specific refactoring |
| Interfaces + affected | 20-30% | Very high | Changes that cross modules |
| Progressive loading | Increases | High | Exploration + modification |
| CLAUDE.md + affected | 15-25% | Very high | Any task with CLAUDE.md |
Connection with the Project
In the Module Project (capsule 05), you design a context strategy for a project of 100K+ lines. You need to know the real limits to make practical recommendations.
Troubleshooting
Problem 1: Claude "forgets" what I told it 20 messages ago
Solution: Start a new session with CLAUDE.md + relevant files. Long sessions accumulate old context.
Problem 2: Claude generates code inconsistent with the project
Solution: Include CLAUDE.md with the project's conventions: naming, patterns, style.
Problem 3: I don't know how much context I'm using
Solution: Heuristic rule — each Python file ~3 tokens per line of code. A 200-line file ≈ 3K-5K tokens.
Exercises
Exercise 1: Decide what to include (Easy)
You're going to refactor payment_service.py. Which of these files do you include?
payment_service.py(the file to modify)models/payment.py(model used)models/user.py(user model)services/email_service.py(sends confirmation)utils/string_utils.py(generic utility)README.mdtests/test_payment_service.pyconfig/settings.py
See solution
- ✅ 1.
payment_service.py— it's the file to modify - ✅ 2.
models/payment.py— defines the types it uses - ❌ 3.
models/user.py— only if payment_service imports it directly - ⚠️ 4.
email_service.py— only if you're going to modify the integration - ❌ 5.
string_utils.py— irrelevant for payment - ❌ 6.
README.md— doesn't inform the refactoring - ✅ 7.
tests/test_payment_service.py— to verify behavior - ⚠️ 8.
config/settings.py— only the payment config section
Result: 3 files always + 2 conditional = 3-5 files, not 8.
Exercise 2: Detect context pressure (Medium)
Read these Claude Code outputs and identify which are symptoms of context pressure:
- Claude suggests creating a function that already exists in another file
- Claude uses
Optional[str]in one file andstr | Nonein another - Claude can't find a file you asked for
- Claude gives a generic answer about testing instead of mentioning the project's specific pytest fixtures
See solution
- ✅ Context pressure — it forgot the function already exists
- ✅ Context pressure — it lost the project's conventions
- ❌ Not context pressure — probably an incorrect path
- ✅ Context pressure — it doesn't have the project context to give a specific answer
Common Errors with the Context Window
Error 1: "Filling the context uses more capacity"
Symptom: You paste the whole codebase to "give Claude more information" and the answer quality drops.
Why it happens: The model distributes its attention over all the content. Irrelevant information "competes" with the relevant. More context ≠ better context. Studies and experience show that the quality drops noticeably after ~70% of the context.
How to fix: Apply the 70% rule. If your codebase takes more, do chunking (capsule 03). If it fits in less than 70%, still filter out the irrelevant.
Error 2: Keeping a session going for hours
Symptom: You work with Claude Code for a complete 4-hour session. The last answers are noticeably worse than the first ones.
Why it happens: Each turn accumulates context. After 50+ turns, the context has a lot of old conversation that dilutes what matters. Even if you don't reach the technical limit, the quality degrades.
How to fix: Sessions of at most 1-2 hours. When you notice degradation, start a new session with CLAUDE.md + relevant files. Capsule 04 develops session hygiene criteria.
Error 3: Not measuring the files' tokens
Symptom: You're surprised when Claude Code says "you're near the limit" — because you never calculated.
Why it happens: "Three files" sounds small. But a 500-line Python file is ~5K tokens. Three files like that are 15K. Plus a 50-turn conversation at 500 tokens each is 25K more. It adds up fast.
How to fix: Estimate before pasting. Heuristic: ~3 tokens/line of Python code, ~5 tokens/line of YAML/HTML/JSON. Multiply by the number of files. If you pass 50% of the context with code, you have a problem.
Error 4: Assuming the problem is the model
Symptom: Claude Code "makes a mistake." You repeat the prompt expecting a better answer. It doesn't improve.
Why it happens: The model didn't make a mistake — the context is bad. Relevant information is missing or irrelevant information is in excess. The instinct is to "be clearer in the prompt," but the problem is in which files are loaded.
How to fix: Diagnose the context before re-prompting. Which files are in context? Is CLAUDE.md missing? Is there irrelevant history in excess? Starting a new session with well-curated context is often better than iterating prompts.
Summary
- 1M tokens ≠ unlimited code — in practice, 15-25K effective lines
- Symptoms of context pressure: inconsistencies, forgetting, generic answers
- Include interfaces + affected files, exclude everything else
- Progressive loading is more effective than giving everything at the start
- New session when you detect context pressure — better than fighting it
- Measure tokens before pasting files
- Short sessions (1-2 hrs) keep the quality consistent
Next capsule: Chunking Strategies — how to divide the work when the project doesn't fit in one session.
Connection with the Rest of the Guide
What you learned here (real limits and symptoms of pressure) is the base for:
- Capsule 03 (Chunking) — the structural solution when context isn't enough
- Capsule 04 (CLAUDE.md) — the persistent context solution that doesn't consume the dynamic window
- Capsule 05 (Project) — designing a complete strategy for 100K+ lines
- Module 7 (Modernize Legacy) — where you modernize large codebases that require chunking
- Module 8 (Capstone Project) — where you apply everything to a real project
If at some later point you see the symptoms we described above, the answer isn't "give Claude more context" — it's going back to this module's techniques and diagnosing what type of pressure you have.
The correct reflex in order of cost: (1) check which files are in context, (2) remove the irrelevant ones, (3) consult CLAUDE.md, (4) if nothing resolves it, start a new session.
Additional Resources
- Anthropic - Context Window - Official context window specs
- Claude Code - Best Practices - Recommended practices
- Token Estimation for Code - A tool to estimate tokens
- Managing AI Context - Prompt Engineering - Anthropic techniques
- Effective Context Management - Research on effective context use
Module 6, Capsule 02 — Refactoring & Legacy Code with Claude Code Guide