Context Management - Common Mistakes

Context management in Claude Code is the skill that separates productive users from those who waste time. Here are the most common mistakes that sabotage your context window, with concrete fixes to optimize every session and avoid saturation pitfalls.

Mistakes in context management represent an essential aspect of mastering Claude Code.

Context management in Claude Code is the mechanism that determines what information the AI keeps in memory during a work session. Claude Code offers a large context window: up to 1,000,000 tokens on current models (Opus 4.6+ and Sonnet 4.6, roughly 750,000 words), and 200,000 tokens on older models and the Bedrock/Vertex/Foundry defaults. This capacity is often wasted by inefficient practices regardless of how large the window is.

Many long sessions degrade because of avoidable context saturation. Every token consumed unnecessarily reduces Claude Code's ability to produce relevant responses.

How does file overloading destroy your context?

Severity: Critical

Loading an entire project into context is the most common mistake. You burn through most of your window before even asking a useful question. A repository with 200 files consumes approximately 800,000 tokens, which alone fills most of a 1,000,000-token window and far exceeds the 200,000-token window of older models.

In practice, Claude Code then reads irrelevant files and loses accuracy on the ones that matter. If you are working on a bug in auth.ts, the 50 unit test files from other modules add nothing.

# Bad - loading the entire project
$ claude "Analyze all the code in /src and give me a summary"

# Good - targeting relevant files
$ claude "Analyze src/auth/login.ts and src/auth/middleware.ts to find the authentication bug"

To understand how to structure your requests, consult the complete context management tutorial that details loading best practices.

Always launch your session with a precise scope. Three to five targeted files yield better results than fifty files loaded in bulk.

Key takeaway: limit each session to a handful of relevant files to keep most of your window available.

Why does ignoring Plan mode cost you tokens?

Severity: Critical

Plan mode is a permission mode you cycle through with Shift+Tab (or Alt+M). In this mode, Claude reads files and runs read-only commands to explore your project, then proposes a plan before making any edits. Letting Claude propose a plan first, instead of editing blindly, avoids the wasteful generate-reject-retry loop.

In practice, many users launch modifications directly without a planning phase. Result: Claude Code generates code, you reject it, it starts over, and each iteration burns 2,000 to 5,000 tokens.

# Bad - executing directly
$ claude "Refactor the payment module into microservices"

# Good - planning first
$ claude "Propose a refactoring architecture for the payment module"

Activate Plan mode for any task involving more than two files. Planning before editing reduces wasted iterations and the tokens they consume.

To discover other saving techniques, explore the context management tips compiled by SFEIR Institute.

Key takeaway: Plan mode cuts wasted iterations on complex refactoring tasks by aligning on an approach before any edit.

What problems does the absence of automatic compaction cause?

Severity: Critical

Automatic compaction (auto-compact) summarizes past exchanges when the context reaches a critical threshold. Without it, Claude Code loses its initial instructions as soon as the window saturates: a phenomenon called "context amnesia."

In practice, many do not configure compaction and end up with incoherent responses after 30 minutes of session. Claude Code provides PreCompact hooks to customize this behavior.

Without a PreCompact hook, your .claude/settings.json has no hooks block. The fix is to add one that runs before each compaction:

// .claude/settings.json
{
  "hooks": {
    "PreCompact": [
      {
        "matcher": "auto",
        "hooks": [
          { "type": "command", "command": "echo 'Compaction at $(date)' >> .claude/compaction.log" }
        ]
      }
    ]
  }
}

Auto-compaction triggers automatically near 95% of context capacity. You can adjust this with the CLAUDE_AUTOCOMPACT_PCT_OVERRIDE environment variable, and use a PreCompact hook to save a structured summary before each compression. Consult the context management deep dive to master advanced hooks.

The PreCompact hook is a script that runs automatically before context compression. It allows you to extract and store key decisions made during the session.

Key takeaway: auto-compaction triggers automatically near 95% of capacity (adjustable via CLAUDE_AUTOCOMPACT_PCT_OVERRIDE); use PreCompact hooks to never lose critical information.

How do vague prompts waste your window?

Severity: Warning

A vague prompt forces Claude Code to "guess" your intention. It then generates long responses covering multiple possible interpretations, each consuming tokens with no added value.

A precise prompt generates responses that are shorter and far more relevant than a generic prompt, saving tokens on every exchange.

# Bad - vague prompt
$ claude "Improve this code"

# Good - precise prompt with constraints
$ claude "In src/api/users.ts, replace callbacks with async/await and add a try/catch to the fetchUser function (line 42)"

Always specify the file, function, line number, and expected action. This saves tokens on every exchange. The "minimum sufficient context" technique is detailed in the common mistakes for first conversations.

Key takeaway: a precise prompt cuts token consumption while sharply improving response relevance.

Why is not using multiple sessions a mistake?

Severity: Warning

Working in a single session for a complex project is like opening 200 browser tabs. Horizontal scaling (distributing work across multiple parallel sessions) is the strategy used by high-performing teams.

In practice, a session dedicated to the frontend and another to the backend each keep their own focused context, instead of cramming everything into one window where information gets lost. You can run several Claude Code sessions in parallel, for example one per terminal or git worktree.

# Bad - everything in one session
$ claude "Fix the frontend bug AND refactor the backend API AND update the tests"

# Good - dedicated sessions
# Terminal 1: frontend session
$ claude "Fix the UserCard component rendering in src/components/"

# Terminal 2: backend session
$ claude "Refactor the /api/users endpoint in src/routes/"

Open separate sessions for each functional domain. You can consult the slash command mistakes to master launching multiple sessions.

Key takeaway: horizontal scaling via multiple sessions keeps each context focused and boosts your effective processing capacity.

What are the risks of not monitoring token consumption?

Severity: Warning

Without monitoring, you exceed the critical threshold without knowing it. Response quality degrades progressively as the window fills, and the drop becomes steep once the context approaches saturation.

The /context command shows your current context-window usage and fill percentage (use /cost or /usage only for cost and plan-limit stats). In practice, many never check their context level and discover the problem when Claude Code produces off-topic responses.

# Bad - working blind
$ claude "Continue the refactoring..." # After 45 minutes without checking

# Good - monitoring regularly, inside an interactive session
> /context   # Check context-window usage
# If usage is high: run /compact to compress
> /compact

To dive deeper into monitoring, the advanced best practices cover proactive monitoring strategies.

Key takeaway: check your context-window usage regularly with /context and run /compact when the window fills up.

How to avoid losing system instructions after compaction?

Severity: Critical

During compaction, Claude Code summarizes past exchanges to free up space. If your initial instructions (tone, format, constraints) are not protected, they disappear from the summary. You end up with an assistant that has "forgotten" your guidelines.

The CLAUDE.md file at the root of your project is the solution. Its content is re-read after compaction, so your conventions persist across the session. In practice, most instruction losses are avoidable via this file.

<!-- Bad - instructions in the first message -->
"You are a React expert, use TypeScript strict,
no any, prefer functional components..."

<!-- Good - CLAUDE.md file at project root -->
# CLAUDE.md
## Conventions
- TypeScript strict, never use `any`
- Functional React components only
- Tests with Vitest, coverage > 80%
- Conventional commits (feat:, fix:, chore:)

Create a CLAUDE.md file from day one on every project. The custom commands and skills show you how to enrich this file with team conventions.

Key takeaway: the CLAUDE.md file is your permanent anchor. It survives all compactions and ensures session consistency.

Why is mass copy-pasting counterproductive?

Severity: Warning

Pasting 500 lines of logs or an entire file into the chat is a natural reflex, but destructive. A 500-line block consumes approximately 4,000 tokens, often for information that is mostly irrelevant, and these blocks add up quickly across a session.

Claude Code can read files directly from your file system. Use file references rather than copy-paste to preserve your context.

# Bad - pasting the entire error log
$ claude "Here is my error log: [500 lines of stack trace]..."

# Good - referencing the file and filtering
$ claude "Analyze the errors in logs/error.log, focus on lines containing 'TypeError' after the 14:30 timestamp"

In practice, file referencing consumes far fewer tokens than copy-paste because Claude Code reads only the relevant sections. The Git integration mistakes illustrate other situations where copy-pasting large diffs saturates the context.

Key takeaway: reference files instead of pasting them. You will save significant tokens for the same information.

Can you use Claude Code effectively without understanding token anatomy?

Severity: Minor

A token is not a word. In English, a common word is often a single token, while technical terms (function names, file paths) consume 2 to 4 tokens each. Ignoring this reality distorts your estimate of remaining capacity.

Tokenization is the process of breaking text into units understandable by the model. Claude splits text into sub-word tokens using a learned tokenizer; the exact algorithm is not publicly documented.

# Illustrative token consumption (approximate)
"hello" # -> ~1 token
"authentication" # -> ~2-3 tokens
"src/components/UserDashboard.tsx" # -> ~6-8 tokens
"const handleUserAuthenticationCallback = async (req, res) =>" # -> ~13-16 tokens

These are illustrative estimates: exact ratios vary by content and model.

For a complete mastery of the topic, the dedicated context management page covers the anatomy of the context window in detail.

Key takeaway: code consumes more tokens than plain text, so factor this into your capacity estimate.

When should you start a new session rather than continuing?

Severity: Warning

Persisting in a saturated session is the most costly mistake in terms of time. Once the window is nearly full, responses take longer to generate and their quality drops. Yet many continue until total failure.

Here is how to identify the right moment to switch:

1. Responses become repetitive or off-topic
2. Claude Code "forgets" instructions given earlier
3. The /context command shows the window is nearly full
4. Response time exceeds 30 seconds for simple requests
5. Generated code blocks contain unusual syntax errors

# Bad - forcing continuation
$ claude "I repeat: use TypeScript, not JavaScript!"

# Good - new session with summarized context
$ claude "Resume the refactoring of src/api/.
Context: we are migrating callbacks to async/await.
Remaining files: userService.ts, orderService.ts"

Check saturation signals and do not hesitate to launch a clean session. The headless mode mistakes show that this discipline is even more critical in CI/CD environments.

Key takeaway: once the context is nearly full, a new session is often more effective than compaction.

How to structure a CLAUDE.md file to maximize context retention?

Severity: Minor

A poorly structured CLAUDE.md file wastes tokens on secondary information. The optimal structure prioritizes critical conventions at the top of the file, because Claude Code gives more weight to the first lines.

A well-structured CLAUDE.md preserves your conventions across compactions and reduces convention errors while saving tokens each session.

<!-- Bad - catch-all CLAUDE.md -->
# My project
This is a React project created in 2024...
[200 lines of project history]
Oh right, use TypeScript strict.

<!-- Good - CLAUDE.md structured by priority -->
# CLAUDE.md
## Critical rules (always follow)
- TypeScript strict, `noAny: true`
- Functional components + hooks only
- No console.log in production

## Code conventions
- Naming: camelCase for variables, PascalCase for components
- Imports: relative for the project, absolute for node_modules

## Tech stack
- React 19, Next.js 15, Vitest 3.0
- Node.js 22 LTS, pnpm 9

Organize your CLAUDE.md into sections in decreasing priority order. Critical rules should appear in the first 20 lines.

SFEIR offers the Claude Code full-day training: you will learn to configure the CLAUDE.md file, master compaction, and manage multi-context sessions with hands-on exercises on real projects.

To go further, the AI-Augmented Developer training (2 days) covers integrating Claude Code into a complete development workflow, from pair programming to code review. And if you already master the basics, the AI-Augmented Developer - Advanced training (1 day) deepens advanced context management strategies and multi-agent orchestration.

Key takeaway: structure your CLAUDE.md with critical rules first: the first 20 lines have the most impact.

Is there a summary of mistakes ranked by severity?

Here is a summary of the 10 most common context management mistakes in Claude Code, ranked by severity:

1. File overloading (Critical): loading the entire project saturates most of the context before any useful question.
2. Ignoring Plan mode (Critical): editing without a plan triggers wasteful generate-reject-retry loops.
3. No compaction (Critical): without auto-compact, context saturates and instructions are lost.
4. Instruction loss after compaction (Critical): without CLAUDE.md, guidelines disappear.
5. Vague prompts (Warning): an imprecise prompt sharply increases token consumption.
6. Single session for everything (Warning): refusing multi-sessions fragments and dilutes your effective capacity.
7. No monitoring (Warning): many never check their consumption.
8. Mass copy-paste (Warning): pasting 500 lines wastes 4,000 tokens unnecessarily.
9. Persisting in a saturated session (Warning): once the window is nearly full, quality drops sharply.
10. Unstructured CLAUDE.md (Minor): a poorly organized file wastes tokens each session.

For a complete view of best practices, consult the context management tips and the deep dive into internal workings.

Key takeaway: fix the critical mistakes first - they account for the bulk of context-related productivity losses.