Engineer Claude Code Context Budgets, Compaction, and Session Hygiene

Quick answer

Treat context as a limited engineering resource. Load only evidence that can change the next decision, filter large outputs at the source, move durable rules into CLAUDE.md, keep reference material in on-demand skills, delegate isolated investigation to fresh-context subagents, and start a new session when stale history costs more than a handoff. Use /context to measure instead of guessing. Anthropic's context-window guide explains what loads and when.

Apply progressive disclosure

Use four passes:

Index: names, paths, manifests, and search hits.
Sample: the smallest representative files or relevant ranges.
Trace: only the runtime or dependency path tied to the task.
Deep dive: full content for the components you will change.

Do not read every file in a directory “for context.” Ask what uncertainty each read resolves.

Filter output before it enters the session

Prefer commands that cap and select:

git log --oneline -20 -- src/auth
git diff --stat main...HEAD
grep -R "refreshSession" src test --exclude-dir=dist
pytest tests/auth/test_refresh.py -q --tb=short

For failing CI, capture the failing job, first causal error, and a small surrounding window—not the entire pipeline log. For structured data, select required fields and limit rows. Never dump secrets merely because a file is small.

Keep instructions in the right layer

Conversation: temporary task direction.
CLAUDE.md: durable repository rules and commands.
Path-scoped rules: instructions that apply only to a subtree.
Skill: reusable workflow or deep reference loaded on demand.
Auto memory: useful learned facts that should be audited.
External artifact: plan, ADR, issue, or handoff that humans also review.

Putting everything in CLAUDE.md consumes startup context and weakens signal. Putting everything in conversation makes it vulnerable to compaction.

Compact with an explicit preservation contract

Before /compact, request a state summary:

Preserve: goal, acceptance criteria, verified root cause, accepted design,
files changed, tests and exact results, open risks, and next command.
Discard: rejected hypotheses, superseded plans, raw logs, and repetitive tool output.

After compaction, ask Claude to restate the constraints before editing. If important facts are missing, recover them from durable artifacts rather than trusting reconstruction.

Decide when to reset

Start a fresh session when:

the primary goal changed;
most history concerns rejected approaches;
behavior becomes repetitive or contradictory;
the remaining task is independently describable;
a clean reviewer should challenge the implementation;
one large artifact repeatedly causes context thrashing.

Create a handoff with facts, decisions, evidence, file state, and next step. A reset is a performance technique, not a defeat.

Measure useful efficiency

Do not optimize token count alone. Track successful tasks per session, corrections, regression rate, verification completeness, and time to review. An extra 500 tokens that prevent a wrong migration are efficient; a 5,000-line log that changes no decision is waste.

Mastery lab

Run the same medium debugging task twice. In the first session, allow broad reads and raw logs. In the second, use progressive disclosure, filtered output, and a mid-task handoff. Compare context use, time, wrong hypotheses, and final defects. Turn the winning pattern into a small team checklist.

FAQ

Does a shorter prompt always save context?

No. Missing constraints can cause expensive exploration and rework. Optimize total task context, not prompt length.

Do MCP servers always consume their full schemas?

Claude Code supports deferred tool loading/tool search in applicable configurations, but inspect /mcp and /context because behavior depends on environment and settings.

When should I use a subagent for context control?

When investigation is bounded, parallelizable, and can return a concise evidence summary without requiring the parent’s entire conversational state.