Module 6: Context Management for Large Projects
Module 6: Context Management for Large Projects
Module 6: Context Management for Large Projects
Capsule description
The previous modules work well for medium-sized projects — 5K-20K lines that Claude Code can process without problems. But in professional reality, codebases are much larger: 50K, 100K, 500K+ lines. Even with Opus's 1M token context window, there are practical limits. This module teaches you how to work effectively within those limits.
The difference between a casual user and a Claude Code professional is context management. The casual one gives it the whole codebase and hopes it works. The professional knows what to include, what to exclude, how to chunk the work, and how CLAUDE.md gives persistent context without consuming the context window.
If in modules 4-5 you felt Claude Code was losing context, forgetting files, or generating inconsistent code — those are symptoms of context pressure. This module gives you the solutions.
By the end of the 5 capsules, you'll be able to work with codebases of any size using context management strategies, diagnose and resolve context pressure, write a CLAUDE.md that makes each session productive from the first message, and design a chunking strategy for 100K+ projects.
Module Context
Where are we?
Guide #8, Phase 2: Refactoring, Module 6 of 6 (the close of Phase 2).
Phase 2: Refactoring (Modules 4-6)
├── Module 4: Multi-File Refactoring ✅
├── Module 5: Framework Migration ✅
└── Module 6: Context Management ← YOU ARE HERE
→ 1M tokens, chunking, CLAUDE.md, progressive context
What you already know
From modules 4-5 you master the techniques of coordinated refactoring and framework migration. What you probably already noticed, especially in non-trivial projects: sometimes Claude Code "loses the thread" — it forgets a file you already read, regenerates code inconsistent with your codebase, or repeats obvious questions. That's not a model bug. It's context pressure. This module teaches you to prevent it.
Where are we headed?
Phase 3 applies everything to legacy code. Module 7 uses context management to modernize legacy code in large projects. Module 8 integrates everything into a complete migration where context management is essential — without it, you simply can't execute the capstone project on a real codebase.
Professional Objective
By the end of this module, you'll be able to work effectively with codebases of any size using context management strategies.
By the end you'll be able to:
- ✅ Understand the real limits of the context window (1M tokens ≠ 1M of code)
- ✅ Decide what to include and exclude from the context
- ✅ Apply chunking strategies: by feature, layer, or module
- ✅ Create and maintain CLAUDE.md as a project context file
- ✅ Implement progressive context loading
- ✅ Manage sessions (when to start a new one vs continue)
- ✅ Recognize and resolve symptoms of context pressure
The Problem: When 1M Tokens Aren't Enough
To anchor the module, consider two real projects:
Small project (10K lines) — no problem
Codebase: ~10K lines of Python + tests
Estimated tokens: ~80K (8 tokens/line average for code)
Capacity of the Opus 1M context window:
→ The whole project fits ~12 times
→ You can paste it all and still have room for reasoning
→ Context management = a luxury, not a necessity
Real project (200K lines) — the industry reality
Codebase: ~200K lines of Python (a typical e-commerce monolith)
Estimated tokens: ~1.6M
Capacity of the Opus 1M context window:
→ The whole project DOESN'T FIT
→ Even if it fit, filling the context degrades the quality
→ Context management = MANDATORY
Without context management:
→ You paste 30 files, Claude Code "forgets" half
→ You generated code that doesn't use the right ORM
→ You ignored project conventions that are in docs/
→ In each session you repeat the same onboarding
With context management (this module):
→ CLAUDE.md persists conventions and rules (capsule 04)
→ Chunking strategy: you work by feature, not by everything (capsule 03)
→ Progressive loading: you start with 5 files, expand as needed
→ Each session is productive from the first message
The tangible result: without context management, a 30-minute task on a small project becomes a 4-hour task on a large project — full of rework. With context management, the task scales linearly with the complexity of the change, not with the size of the codebase.
Module Progression
Module Map
| Capsule | Topic | What you'll learn |
|---|---|---|
| 02 | Context Window Reality | The real limits of 1M tokens and the symptoms of context pressure |
| 03 | Chunking Strategies | Divide the work by feature, layer, or module |
| 04 | CLAUDE.md and Project Context | The file that makes each session productive from the first message |
| 05 | Project: Strategy for a 100K+ Project | Design a complete context strategy for a large project |
Learning flow
You start by understanding how big 1M tokens actually is (capsule 02) — and what happens when you fill it. Then you learn to partition the work (capsule 03) so you never have to fill it. Capsule 04 gives you the highest-leverage tool of the module: CLAUDE.md, the file that gives context without consuming the context window. And the project integrates everything by designing a complete strategy for an open-source project of 100K+ lines.
Key Concepts You'll See
A quick preview of the module's central concepts so you arrive with the vocabulary:
Context Window
The maximum amount of tokens the model can process simultaneously — input + output. In the current Opus: 1M tokens. But fitting and working well are different things (capsule 02).
Context Pressure
A set of symptoms that appear when the context approaches the limit or contains too much irrelevant information: the model "forgets" files, regenerates inconsistent code, repeats questions you already answered. It's not a bug — it's information: you need to reorganize the context.
Chunking
A strategy to partition the work (not the file): you work on one feature/layer/module at a time, not the whole codebase. Three main patterns:
- Feature chunking — e.g. "touch everything related to authentication"
- Layer chunking — e.g. "modify all the repositories"
- Module chunking — e.g. "work inside
payments/only"
CLAUDE.md
A file at the project root (or in .claude/) that persists context between sessions: codebase conventions, naming, architecture rules, frequent commands. Claude Code reads it automatically. It doesn't consume your context window dynamically — it's cheap context.
@-References
Syntax to include specific files in a prompt without pasting them: @src/payments/processor.py. It allows surgical selectivity: include 4 relevant files vs pasting 40.
Progressive Context Loading
A pattern of starting with the minimum set of files and expanding when Claude Code asks you for more (or when you notice context is missing). The opposite of "I paste everything just in case".
Session Hygiene
The discipline of when to cut and start a new session. After many turns, the accumulated context can degrade the quality. Sometimes starting fresh with a good CLAUDE.md is more effective than continuing.
The Core Principle
Less is more. Claude Code with 20 relevant files is more effective than Claude Code with 200 irrelevant files. Context management isn't giving everything — it's giving the right thing.
Three derived principles:
- Selectivity over exhaustiveness. If the change is in
pricing/, don't includenotifications/. - Persistence over repetition. Project conventions go in CLAUDE.md, they aren't repeated in every prompt.
- Progression over all-at-once. Start with the minimum set, expand when Claude Code asks for more.
Connection with the Project
In the Module Project (capsule 05), you design a complete context strategy for an open-source project of 100K+ lines: CLAUDE.md, chunking strategy, and @-reference templates for common tasks.
In Module 8 (Capstone Project), you apply everything learned here to the real legacy project. Without this module's techniques, the capstone project is executable only on small codebases — with them, it scales to real projects.
Symptoms of Context Pressure (Preview)
You've probably already seen these symptoms without naming them. Capsule 02 develops them — this table gives you a preview so you recognize them while you read the rest of the module:
| Symptom | What happened | Solution (capsule) |
|---|---|---|
| Claude Code "forgets" a file you already read | The file drifted out of the focus of attention | Re-include it or start a new session (04) |
| It generates code inconsistent with your codebase | It doesn't have the conventions present | Persistent CLAUDE.md (04) |
| It repeats questions you already answered | The initial context got diluted | Cut the session and restart (04) |
| The code mixes patterns from irrelevant files | Too much irrelevant context | Chunking + selectivity (03) |
| Vaguer answers as the session advances | The context window is almost full | Compaction or a new session (02, 04) |
| "Finding an import" takes many iterations | The project's initial orientation is missing | CLAUDE.md with the project structure (04) |
If you took M01 (Onboarding) and M02 (Explore) without seeing any of these symptoms, you probably worked on small projects. In real projects, you're going to see them — and now you'll know what to do.
Frequent anti-pattern: "I give it more context and it's fixed"
When the symptom appears, the intuitive reaction is to give more context ("let me also paste this other file"). But the common cause isn't a lack of context — it's poorly organized context: irrelevant files that dilute the attention, or conventions the model doesn't remember because they're in another part of the old prompt. The correct solution is usually less:
- Start a new session with the minimum set of files
- Load CLAUDE.md (which persists the project's conventions)
- Use surgical @-references instead of pasting blocks
Capsule 02 develops how to diagnose correctly, and capsule 04 how to prevent it from the start with a good CLAUDE.md.
Traps to Avoid While Taking This Module
Five predictable misunderstandings. Anticipate them before you start.
1. "1M tokens means I can paste everything"
No. Fitting and working well are different things. Filling the context window degrades the model's attention: the relevant information gets "diluted" among the irrelevant. Studies and practical experience show that the quality drops noticeably past ~70% of the context. Capsule 02 develops this point with data.
2. "CLAUDE.md is optional"
In small projects, yes. In large projects it's the highest-leverage change you can make. Without CLAUDE.md, you repeat conventions, naming, and rules in every session. With CLAUDE.md, those rules are persistent context — Claude Code "knows" them from the first message. Capsule 04 teaches you what to include and what not.
3. "Chunking means splitting the file into pieces"
No. Chunking here means splitting the work: you work on one feature at a time, not the whole codebase. If the change touches 8 files, those 8 are your chunk — you don't include the remaining 200. Capsule 03 gives you the 3 patterns (by feature, by layer, by module) and when to use each.
4. "If Claude Code gets confused, I give it more context"
Sometimes. But more often: less context, better selected. The confusion often comes from contradictory or duplicated information. Removing irrelevant files helps more than adding explanations. Capsule 02 teaches you to diagnose context pressure correctly.
5. "A long session is better than many short sessions"
It depends. After a certain number of turns, the context accumulates and degrades. Starting a new session with a solid CLAUDE.md and the right files is often more effective than continuing a long session. Capsule 04 gives you the criteria to decide when to cut.
Diagnosis: What's Your Starting Point?
Five questions to calibrate before you start.
Question 1: Have you noticed Claude Code "forget" a file or detail you mentioned earlier in the same session?
If yes: note the case. Capsule 02 gives you the vocabulary to understand it (context pressure, attention dilution) and the solutions.
If no: you've probably worked on small projects. Capsule 02 prepares you for when you start touching real codebases.
Question 2: Do you have a CLAUDE.md (or equivalent) in your projects? What's inside?
If you said "yes, with conventions and rules": you're on the right track. Capsule 04 gives you a rubric to audit and improve it.
If you said "no" or "it's empty": capsule 04 is the priority of the module. It's where you'll get the most leverage.
Question 3: When you give context to Claude Code, do you usually include more, less, or just enough?
If you said "more, just in case": trap #1 applies to you. Capsule 02 shows you the cost of filling the context.
If you said "just enough": how do you decide "just enough"? Capsule 03 formalizes this into chunking strategies.
Question 4: Do you know how to count (estimate) how many tokens your codebase, or a subset, has?
If yes: capsule 02 gives you a formal map — what each tool measures (tiktoken, the Anthropic counter), the practical equivalences (8 tokens/line average).
If no: you're going to learn it. It's the basis for making informed context decisions.
Question 5: When do you start a new session with Claude Code? Out of habit, out of necessity, never?
If you said "when something goes wrong": capsule 04 teaches you to anticipate the optimal moment (not wait for "something goes wrong").
If you said "always the same session": trap #5 applies to you.
If you hesitated on 3 or more: this module is a priority before Phase 3. If you answered them all with clear criteria, use it as a focused review of CLAUDE.md (capsule 04), which can almost always be improved.
Evidence of Success
Before moving on to Module 7 (Modernize Legacy Code), you should be able to:
- ✅ Estimate how many tokens a codebase has and predict whether it will fit completely in context
- ✅ Recognize the 3-4 symptoms of context pressure and apply the corresponding solution
- ✅ Design a chunking strategy (feature / layer / module) for a project you know
- ✅ Write a useful CLAUDE.md — not generic — for a real project
- ✅ Decide when it's time to start a new session instead of continuing
- ✅ Work with projects of 100K+ lines without context overflow or quality degradation
If any one isn't met at the end, go back to the corresponding capsule. Module 7 and Module 8 assume these techniques — without them, the Phase 3 projects become unviable on real codebases.
Summary
- Context management is the skill that separates the casual from the professional
- 1M tokens has practical limits — this module teaches you to work within them
- CLAUDE.md is the most underused tool of Claude Code
- Less is more: include the relevant, not everything
- Chunking strategies (feature, layer, module) scale to any project
- The difference between "30 minutes" and "4 hours" from the initial scenario is exactly this module
Next capsule: 02 — Context Window Reality — the practical limits of 1M tokens, what happens when you fill them, how to measure your codebase, and the symptoms of context pressure you've probably already seen without naming them.
Additional Resources
- Claude Code - CLAUDE.md Documentation - Official reference
- Context Window Explained - Anthropic - How context windows work
- Prompt Engineering Guide - Anthropic - Context management techniques
- Anthropic Token Counting - The official tool for counting tokens
- Large Codebase Navigation - Complementary tools for large codebases
- Token Counting - tiktoken - A tool for counting tokens (approximately compatible with Anthropic)
- Effective Code Reading at Scale - Human techniques that complement AI
Module 6, Capsule 01 — Refactoring & Legacy Code with Claude Code Guide