Context Management — Working with Large Codebases

A new Claude session starts clean. After a long session, context fills up and older information gets compressed away. Understanding how this works — and how to work with it, not against it — is what separates developers who get stuck re-explaining things from developers who maintain momentum across sessions and weeks.

What Happens as a Session Grows

When you start a session, Claude's working memory is empty. As you have a conversation:

• Your messages are added to the context
• Claude's responses are added
• Files that Claude reads are added
• Previous turns accumulate

Eventually, the context gets large. When it does, Claude uses compaction — it summarizes the earliest parts of the conversation into a compressed version that takes fewer tokens, then continues. Older messages are no longer available in their original form, but a summary of what they covered remains.

The Excel analogy: Imagine your Excel model is working on a very large dataset. When RAM gets full, Excel starts swapping older parts of the dataset to disk. The data is still "there" in theory, but accessing it is slower and less precise. If you need to reference a formula you wrote 200 rows ago, it is still accessible — but Excel has to work harder to get to it.

Claude's compaction works similarly. The recent context is sharp and precise. Older context exists as a summary — present, but less detailed.

Reading a Compaction Summary

When Claude compacts a long session, it generates a summary of what has been covered. You will see a block in the transcript that summarizes the session's history.

This summary is your key to continuing effectively. Read it when you see it. If it is inaccurate or missing something important, correct it immediately by telling Claude what is wrong or missing.

Correcting the summary immediately reorients Claude without having to re-explain the entire session.

How CLAUDE.md Is Cached

CLAUDE.md is special. Unlike your conversation messages, which accumulate and get compacted, CLAUDE.md is cached by the Claude Code system and provided at the start of every session and every turn — without consuming fresh tokens.

What this means in practice:

Your CLAUDE.md might be 4,000 tokens of project context. Without caching, every single turn in a long conversation would include those 4,000 tokens as input — costing you tokens constantly. With caching, those 4,000 tokens are paid once and reused for free across many turns.

The implication for your writing style:

Write thorough CLAUDE.md files without worrying about length. The cost of a longer CLAUDE.md is nearly zero compared to its value — it is cached. The cost of an incomplete CLAUDE.md is high — you re-explain context repeatedly across sessions.

The same caching applies to skill files that Claude reads. Once read in a session, they stay available without additional token cost.

When to Start a New Session

The most common mistake is trying to continue a single session indefinitely. Here is when to start fresh:

Start a new session when:

• You are switching to a completely unrelated task (debugging auth, then building the analytics dashboard — two separate sessions)
• A session has accumulated a lot of wrong turns and Claude seems confused about the current state
• You want a completely fresh perspective on a problem you have been circling for a while
• The compaction summaries are losing important details that you need

Do NOT start a new session when:

• You are in the middle of a feature and want to add something related
• Claude's context is accurate and the momentum is good
• You are debugging and have useful error context in the conversation

Use /clear when:

• You want to clear the conversation but stay in the same terminal session
• You finished a task and want a clean slate for the next one without restarting Claude entirely

How to Brief Claude at Session Start

When you start a new Claude session on an existing project, CLAUDE.md gives Claude the project context. But it does not know what you were working on yesterday or what the current task is.

A good session-start brief takes 3–5 sentences. It should cover: what you are building, what was done in the previous session, what today's specific task is, and what the current state of the codebase is for this feature.

This brief gets Claude oriented immediately. Without it, Claude starts cold even though your CLAUDE.md is loaded — the CLAUDE.md tells Claude about the project, but only you know what the current task is.

The session-start habit:

This habit saves the first 10–15 minutes of every session that would otherwise be spent re-establishing context.

The Context Dump Technique

For complex debugging or when picking up an abandoned feature, use a targeted context dump at session start:

With this context dump, Claude has:

• The actual file content (no need to read it — you provided it)
• A precise description of the bug
• What you have already tried (so Claude does not suggest the same things)
• The query key structure (so Claude knows what to invalidate)

This gets to a solution in 1–2 turns instead of 8–10.

Working with Large Codebases

As your project grows, so does the cognitive load of working with it. Here are techniques for keeping Claude effective on large projects:

Be specific about which file to read: Name the exact file you want Claude to read before writing anything. "Read the existing login form before writing the new one" is better than letting Claude guess which file is relevant.

Tell Claude what NOT to read: If there are large files or folders that are not relevant to the current task, say so. "Ignore everything in the admin/ folder for this task" prevents unnecessary context consumption.

Break large features into sessions:

A feature with 5 files, 3 database changes, and a new API endpoint should be broken into separate sessions:

• Session 1: Database migration and types
• Session 2: Edge function
• Session 3: React hook
• Session 4: UI components

Each session has a tight scope and a clear outcome. Trying to do all steps in one session produces context clutter that degrades output quality.

Use the decision log:

At the end of every significant session, spend 2 minutes updating your CLAUDE.md decision log with what was decided and why. The next session picks up this knowledge from the cached CLAUDE.md — no re-explaining needed.

/clear vs New Session — Practical Guidance

The Daily Workflow That Works

Here is the workflow used across multiple production projects that keeps context clean and productive:

Morning (session start):

During the session:

End of session:

When picking up an abandoned task (next day or after a break):

This workflow is not complicated. It is just consistent. The consistency is what makes it work.

One Last Concept: The "Warm Start"

A warm start is when you configure a session to begin with maximum context from the very first message. You do this by:

1. Having a complete, accurate CLAUDE.md (the foundation)
2. Writing an accurate session brief (the current state)
3. Telling Claude which files to read before asking the first question

A well-configured warm start means Claude's first response to your actual question is as good as the response it would give after a long context-building back-and-forth. You skip the warm-up phase entirely.

This compounds. Over 50 sessions on a project:

• Cold start approach: the first 10 messages of every session are spent re-establishing context
• Warm start approach: the first message is productive

That is roughly 500 messages of productive work vs. re-explanation. On a 4-month project with multiple sessions per week, this difference is measured in weeks, not hours.