Context Health Management

Guidance for maintaining effective context utilization during AI-assisted development.

The Core Problem

As conversations grow, AI assistants experience context degradation:

• Responses become less coherent
• Earlier context gets "forgotten" or misweighted
• Quality of suggestions decreases
• Errors and inconsistencies increase

This is not a bug—it's physics. Context windows have finite capacity, and as they fill, signal-to-noise ratio drops.

The 40-60% Rule

Target: Maintain context at 40-60% capacity.

Utilization	Status	Action
< 40%	Healthy	Continue working
40-60%	Optimal	Monitor, plan compaction
60-80%	Warning	Compact soon
> 80%	Critical	Compact immediately

Why this range?

• Below 40%: Plenty of room, no concerns
• 40-60%: Optimal balance of context and headroom
• Above 60%: Degradation begins, errors increase
• Above 80%: Significant quality loss, compaction urgent

Checking Your Context Usage

Claude Code can display your current context utilization in the statusline. To enable it:

1. Run /config and navigate to statusline settings
2. Enable context usage display
3. Monitor the percentage as you work

This gives you real-time visibility into when compaction is needed—no more guessing!

Signs of Context Degradation

Watch for these warning signs:

Behavioral:

• Repeating information already discussed
• Forgetting earlier decisions
• Contradicting previous statements
• Asking questions already answered
• Losing track of the current task

Quality:

• Suggestions that ignore established patterns
• Code that doesn't match project conventions
• Errors in previously working areas
• Decreased coherence in explanations

When you notice these: Compact immediately, don't push further.

Compaction Strategies

When to Compact

Natural breakpoints:

• Completing an RPI phase (research → plan → implement)
• Finishing a logical unit of work
• Before starting a complex new task
• Switching focus areas

Warning signs:

• Any degradation symptoms above
• Feeling like context is "cluttered"
• Multiple back-and-forth clarifications needed

Time-based:

• After extended sessions (2+ hours of active work)
• Before taking a break
• End of work session

What to Preserve

Always keep:

• Current task status and progress
• Key decisions and their rationale
• Critical file paths and line numbers
• Patterns and conventions discovered
• Open questions and blockers

Safe to discard:

• Exploratory searches that didn't pan out
• Verbose tool outputs (keep summaries)
• Superseded approaches
• Obvious information easily re-derived

How to Compact

Use the /harness:compact command to:

1. Generate a structured handoff document
2. Capture all essential state
3. Prepare for context reset

The handoff document becomes the "seed" for the next context.

Context-Efficient Practices

Use Subagents for Exploration

When exploring unfamiliar code:

• Use cartographer agent instead of exploring in main context
• Subagent context is separate from main conversation
• Main context only receives synthesized results

Instead of:

Let me search for all files related to authentication...
[20 grep results]
Let me read each of these...
[verbose file contents]

Do:

Launch cartographer to explore authentication code.
[Agent returns: synthesized findings]

Document to External Files

Move information out of context into files:

• Research findings → RESEARCH.md
• Implementation plans → PLAN.md
• Decisions and rationale → project docs

Files persist across context resets. Context doesn't.

Be Specific in Requests

Vague requests waste context on clarification:

Instead of: "Help me fix this bug" Say: "Fix the null pointer in src/auth.ts:45 when user has no email"

Specific requests get specific answers with less back-and-forth.

Summarize Periodically

After completing a unit of work:

• Summarize what was accomplished
• Note any decisions made
• Identify next steps

This creates natural compaction checkpoints.

Recovery from Degradation

If you notice degradation mid-task:

1. Stop - Don't push further
2. Summarize - Capture current state quickly
3. Compact - Use /harness:compact to create handoff
4. Reset - Start fresh context
5. Resume - Load handoff and continue

It's better to compact early than to fight degradation.

Context Health Checklist

Before starting complex work:

• Is context relatively fresh?
• Are previous tasks cleanly wrapped up?
• Is the goal clearly stated?

During work:

• Am I getting coherent responses?
• Is Claude remembering earlier context?
• Are suggestions matching project patterns?

After completing phases:

• Should I compact before continuing?
• Is important context documented externally?
• Are next steps clear?

Additional Resources

For detailed compaction workflows:

• references/compaction-patterns.md - Detailed compaction strategies
• /harness:compact command - Create compaction checkpoint