Context Engineering

Context engineering is the art and science of filling Claude’s context window with exactly the right information. Get this right, and Claude becomes dramatically more effective.

The Science of Context Rot

Research from Chroma and others has demonstrated that LLM performance degrades as context fills up—even well before hitting the maximum limit.

Key Findings

Context Usage	Performance Impact
0-30%	Optimal performance
30-50%	Slight degradation
50-70%	Noticeable issues
70%+	Significant problems

Why This Happens

Claude uses attention mechanisms to understand relationships between tokens. As context grows:

Attention spreads thin - Each token gets less focus
“Lost in the middle” - Information in the middle gets overlooked
Noise increases - Irrelevant context competes with relevant
Reasoning degrades - Complex multi-step tasks fail first

Principles of Context Engineering

1. Relevance Over Completeness

Don’t dump everything into context. Curate.

# Bad: Everything
> Here's our entire codebase documentation, all 50 files...

# Good: Relevant context
> I'm working on the payment module.
> Key files: payments.py, stripe_client.py
> Issue: webhook retry logic fails after 3 attempts

2. Recency Matters

Recent information gets more attention. Structure context so important information comes early or late, not middle.

# In CLAUDE.md - put critical info first

## ⚠️ Critical: Do Not Touch
- Never modify `core/auth.py` without security review
- Database migrations require approval

## Project Overview
[Less critical information...]

3. Start Fresh Frequently

Every conversation accumulates context. New tasks deserve fresh starts:

# Don't continue forever
> [after 30 messages] now let's work on something unrelated...

# Start clean
> /clear
# or
exit
claude "new task description"

4. Use Compression Strategically

The /compact command summarizes context. Use it:

Before starting a new sub-task
When you notice Claude forgetting things
After getting large responses (docs, database results)

> /compact

Practical Techniques

Technique 1: Task Isolation

Keep different tasks in different sessions:

# Session 1: Bug fixing
claude "fix the login bug"
# [complete the fix]
exit

# Session 2: New feature
claude "add rate limiting"
# [fresh context, full attention]

Technique 2: Progressive Disclosure

Don’t front-load everything. Provide context as needed:

# Start minimal
> add input validation to the user registration endpoint

# Claude asks about requirements or makes assumptions
# Now provide specifics
> for the email field, we need to verify the domain is not disposable

Technique 3: Explicit Context Boundaries

Tell Claude what to focus on:

> Focus only on the PaymentService class in services/payment.py
> Ignore the rest of the codebase for now
> Task: add retry logic for failed charges

Technique 4: Summarize Before Expanding

Before adding more context, summarize what you have:

> Let me summarize where we are:
> - We've identified the bug in auth.py line 45
> - The fix requires changes to both User model and login route
> - We've updated the model
>
> Now let's focus on the route changes.

Technique 5: Reference, Don’t Repeat

Point to files instead of pasting content:

# Bad: Pasting file contents
> Here's my entire config file: [500 lines of config]

# Good: Reference
> Check the database settings in config/database.py
> Specifically the connection pooling section around line 45

Context Budget Planning

For complex tasks, plan your context budget:

Example: Building a Feature

Phase	Context Allocation
Requirements gathering	10%
Architecture discussion	15%
Implementation	40%
Testing	20%
Refinement buffer	15%

If you’ve used 50% on requirements, start a new session for implementation with a summary.

The Handoff Pattern

# End of planning session
> Summarize everything we've decided into a spec I can use
> to start fresh in a new session.

[Claude produces spec]

# Save the spec
> save this to docs/feature-spec.md

# New session
exit
claude
> Implement the spec in docs/feature-spec.md

Warning Signs

Watch for these indicators of context rot:

Sign	Meaning	Action
Claude forgets earlier decisions	Context overflow	`/compact` or new session
Responses contradict themselves	Attention fragmented	Summarize and refocus
Simple questions get wrong answers	Noise overwhelming signal	Start fresh
Claude keeps asking for info you provided	Middle context lost	Repeat key info recently

CLAUDE.md Optimization

Your CLAUDE.md is always in context. Optimize it:

Do ✓

# Project: PaymentApp

## Critical Rules
- Never commit API keys
- All prices in cents (integer)

## Key Files
- app/services/payment.py - Payment processing
- app/models/order.py - Order model

## Commands
- make test - Run tests
- make dev - Start server

Don’t ✗

# PaymentApp

## Complete History
This project was started in 2020 when we needed...
[500 words of background]

## All Team Members
- John (backend, joined 2020)
- Sarah (frontend, joined 2021)
[200 words about team]

## Every Configuration Option
[1000 words of config docs]

The Paradox

More context feels helpful but often isn’t. The best Claude sessions are focused:

Clear objective
Minimal but relevant context
Fresh start for new tasks
Proactive compression