Optimizing Context Budget

Overview

You now understand that context is finite and that tools like .ctx files and memory help distribute and persist it. But there is a more fundamental optimization: making every token inside the context window work harder. This lesson covers practical techniques for keeping your CLAUDE.md lean, making your codebase self-describing, working with context compression, and structuring agent interactions so the agent gets maximum value from minimum context.

The Lean CLAUDE.md

The most common context budget mistake is a bloated CLAUDE.md. Teams add rules and examples over time without removing anything, and the file grows from a focused 30-line guide to a 500-line manual that covers every edge case.

The problem is not the content itself -- each line was probably added for a good reason. The problem is that every line is loaded into every session, whether it is relevant or not.

Comparison of bloated vs lean CLAUDE.md: a bloated 500-line file containing build commands, 20 style rules, API patterns, database conventions, frontend patterns, deploy procedures, security guidelines, code examples, and edge cases costs ~8,000 tokens every session with low relevance. A lean 50-line file with just build/test/lint commands, top 5 critical rules, a 3-sentence architecture overview, and pointers to .ctx files costs ~800 tokens with high relevance.

The fix is to apply the 80/20 rule: identify the 20% of instructions that prevent 80% of agent mistakes, and keep only those in CLAUDE.md. Everything else goes into .ctx files, where it is loaded on demand.

Here is a practical comparison:

The "after" version is roughly 200 tokens. The "before" was over 6,000. The agent gets the critical information it needs for every session, and detailed patterns are available on demand through .ctx files when the agent is actually working in that area.

Making Your Codebase Self-Describing

The best way to reduce context consumption is to make the code communicate its own intent. A self-describing codebase uses names, types, and structure so clear that the agent rarely needs to consult external documentation.

Good names eliminate documentation. Compare these two approaches:

The first function requires the agent to read its callers, its tests, and possibly a comment to understand what it does. That is three file reads, potentially thousands of tokens. The second function communicates everything through its signature: zero extra context needed.

Types carry context for free. In typed languages, every type annotation is a piece of context that the agent gets without reading any documentation:

Directory structure communicates architecture. When directories are named clearly and organized logically, the agent can infer the architecture from the file tree without reading a single file:

Every improvement to your code's self-description pays a double dividend: it helps human developers and it reduces agent context consumption.

Working with Context Compression

As conversations grow long, a process called context compression kicks in. The agent platform automatically summarizes earlier messages to free up space for new content. This is invisible to the developer but has real consequences.

What gets compressed:

• Early messages in the conversation are summarized first
• Tool output (file contents, command results) is often heavily compressed
• Repetitive exchanges (multiple rounds of similar edits) get collapsed

What survives compression:

• Recent messages retain full detail
• Key decisions and corrections tend to persist
• System instructions (CLAUDE.md) are protected from compression

Context compression over a session: at the start, all messages have full detail. By mid-session, earlier messages (1-20) are compressed into summaries like 'Discussed API design, decided on REST.' Late in the session (40+ messages), the current context is mostly recent work at full detail, while early conversation details may be lost.

The practical implication: do not rely on the agent remembering details from early in a long session. If you made an important decision in message 5 and you are now on message 40, the agent may only have a vague summary of that decision.

Strategies for working with compression:

• Keep sessions focused. One task per session reduces the need for the agent to recall distant context.
• Restate important constraints. If a decision from early in the session matters for current work, restate it rather than assuming the agent remembers.
• Use CLAUDE.md for persistent rules. Rules in CLAUDE.md survive compression. Rules mentioned in conversation do not.

The Discovery vs. Pre-load Trade-off

A key context budget decision is what the agent should know before starting versus what it should discover as needed. Pre-loading means putting information in CLAUDE.md or memory so the agent has it immediately. Discovery means letting the agent find it by reading files or searching the codebase.

Pre-load vs discover trade-off: Pre-loaded context (CLAUDE.md, Memory) is always available but costs tokens every session — best for universal rules, build commands, and critical constraints. Discovered context (Search, Read) is loaded only when needed and costs tokens only when relevant — best for implementation details, module-specific patterns, and examples.

The rule of thumb: pre-load things the agent needs in every session, and let it discover things it only needs sometimes.

Token Counting Intuition

Developers benefit from building an intuition for how many tokens different kinds of content consume. This helps you make informed trade-offs about what to include.

Rough guidelines:

• 1 line of code is approximately 10-15 tokens
• 1 line of English prose is approximately 15-25 tokens
• A typical function (10-30 lines) is 150-400 tokens
• A typical file (100-300 lines) is 1,500-4,500 tokens
• A lean CLAUDE.md (30-50 lines) is 500-800 tokens
• A bloated CLAUDE.md (300+ lines) is 5,000-10,000 tokens

In a 200K token context window, a bloated CLAUDE.md consumes 5% of the total budget before the agent does anything. That is 5% less space for actual code, test output, and reasoning.

Every line in your CLAUDE.md should earn its place. Ask: "Does this line prevent a common mistake in most sessions?" If not, it belongs in a .ctx file or nowhere.

Practical Optimization Checklist

Use this checklist to audit your context budget:

• CLAUDE.md under 60 lines? If not, move low-frequency rules to .ctx files
• Every CLAUDE.md line earns its place? Remove anything that duplicates the linter, the types, or the compiler
• Code uses descriptive names? Every x, tmp, and data costs future context for the agent to understand
• Types are explicit? Implicit types force the agent to trace through code to determine types
• Directory structure is clear? Ambiguous directory names like utils/ and helpers/ force the agent to read files just to understand organization
• Sessions are focused? Long, multi-topic sessions suffer from compression; break them into focused tasks
• Important decisions restated? In long sessions, restate critical constraints near the point where they matter

Summary

• A bloated CLAUDE.md is the biggest context budget anti-pattern -- keep it under 60 lines and move details to .ctx files
• Self-describing code (good names, explicit types, clear structure) reduces context consumption because the agent infers intent from the code itself
• Context compression summarizes earlier messages in long sessions -- do not rely on the agent remembering early conversation details
• Pre-load universal rules and build commands; let agents discover module-specific patterns and examples on demand
• Build intuition for token costs: a bloated CLAUDE.md can consume 5% of the context window before the agent starts working
• Every line of documentation should earn its place by preventing a common mistake in most sessions