8. Context Reduction Techniques

Path-Scoping: The Highest-Leverage Technique

Path-scoping reduces always-on context by 40-50% with no loss of coverage. It is the single most impactful structural change for projects beyond ~200 lines of configuration.

Implementation steps:

1. Identify natural domain boundaries in your codebase (API, frontend, database, tests, infrastructure)
2. For each domain, create a CLAUDE-\{domain\}.md file in the domain directory
3. Move domain-specific rules from root CLAUDE.md to the appropriate module
4. Replace moved content in root CLAUDE.md with @path/to/CLAUDE-domain.md imports
5. Verify adherence with canary checks

Target after refactor: root CLAUDE.md at under 150 lines (shared rules + import declarations only).

Negative Constraints

Empirically, negative constraints ("never do X") outperform positive instructions ("do X") by 15-25% for preventing bad patterns. This is counterintuitive: you might expect "do X" to be clearer. But in practice, the model needs to actively resist a temptation to do the wrong thing; explicitly naming the wrong thing and saying "never" is more salient.

Pattern	Formulation	Adherence
Positive (weaker)	"Use structured logging for all backend services"	~75%
Negative (stronger)	"Never use console.log in backend services; use the structured logger (pino)"	~90%

Technique: For any rule where the wrong pattern is a common default (raw try/catch, console.log, default exports, any types), frame the rule as a negative constraint naming the specific pattern to avoid.

Rule Compression

Long explanatory rules consume tokens and dilute attention. Compress explanations to their essence:

Before (verbose, 38 words):

- When creating React components, always make sure to use TypeScript interfaces
  for props, and define them before the component declaration, not inline, to
  improve readability and enable reuse.

After (compressed, 9 words):

- React props: TypeScript interface, declared before component, never inline.

The compressed version has higher adherence: shorter rules are processed with more attention weight per rule. Save explanations for the rationale format when they're truly needed for understanding.

Compression heuristic: If a rule takes more than one line, ask whether the extra content is a constraint or an explanation. Move explanations to comments (prefixed with # or a > blockquote) or rationale annotations. Keep the enforced constraint to one line.

Deduplication

The same constraint stated multiple times (in different words) does not reinforce it. It dilutes the total attention budget. Find and remove semantic duplicates.

Common sources of duplication:

• One rule in a general section, one more specific version in a path-scoped module
• A rule added to fix a problem, without removing the vaguer original rule it supersedes
• Rules copied from different team members' configs during a merge

Deduplication workflow:

Scan CLAUDE.md for semantic duplicates. Two rules are duplicates if they
constrain the same behavior, even if worded differently. List all duplicate
pairs and recommend which version to keep based on specificity and clarity.

Run this as a Claude prompt against your CLAUDE.md. Review the suggestions and merge.

The Archive Pattern

When removing a rule, you lose the knowledge of why it existed. That institutional memory can be valuable: six months later, someone may try to reintroduce the same pattern the rule was preventing.

Instead of deleting obsolete rules, archive them:

.claude/
├── CLAUDE.md              # Active rules
└── CLAUDE-archive.md      # Historical rules with retirement notes

Archive entry format:

## Archived Rules

### [Retired 2026-01] Use MongoDB for session storage
Replaced by: Use PostgreSQL with the sessions table for session storage.
Reason: Standardized on single database; MongoDB was only used for sessions and added operational complexity.

The archive is not loaded by Claude. It is reference documentation for humans. It prevents the same debates and mistakes from recurring.

The 80/20 Rule for Rules

Across most production configurations, 20% of rules account for 80% of Claude's consequential decisions. The other 80% of rules cover edge cases, stylistic preferences, and situations that rarely arise.

Identifying your top 20%:

1. List every rule in CLAUDE.md
2. For each rule, estimate: "How often does this rule meaningfully change Claude's output in a session?"
3. Rules that apply daily: keep, prioritize, place early
4. Rules that apply weekly: keep, place in middle
5. Rules that apply monthly: consider archiving or moving to a loaded-on-demand skill
6. Rules that apply rarely: archive

Coverage completeness matters less here than protecting the rules that matter most from being diluted by the rules that matter least.

Placement matters: Place your top 20% rules in the first third of CLAUDE.md. Attention weight is not uniform across a long document. Early content has higher salience.

Think in Code

Named by context-mode v1.0.64 and independently described by Contieri in April 2026 as "Ask for the Analyst, Not the Analysis," this pattern addresses a common source of token waste in exploration tasks.

The problem: To answer "which files import module X?", a naive agent opens and reads files one by one. With 30 candidate files, that's 30 tool calls and potentially 15,000+ tokens of file content loaded into context, the vast majority irrelevant to the actual question.

The pattern: Instead of reading files, instruct the agent to write and run a small script (bash, Python, jq) that queries, counts, or filters, then return only the result. The result is 1 tool call and approximately 50 tokens rather than 30 calls and 15,000 tokens.

Examples:

Finding which files import a module:

grep -r "import X" src/ --include="*.ts" | wc -l

Identifying files over a size threshold:

find src/ -name "*.ts" -size +50k | sort

Counting test coverage by directory:

find src/ -name "*.test.ts" | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn

When to apply it: Any task that is "explore and report" rather than "edit." Discovery tasks, counting, pattern matching, dependency analysis, and finding files by content are all candidates. If you find yourself writing agent instructions that describe reading many files to gather statistics, the "Think in Code" pattern usually applies.

Relationship to sub-agents: Sub-agents execute in isolation with their own context budget. "Think in Code" keeps everything in the main agent but uses scripts as the exploration mechanism. Both approaches avoid loading irrelevant file content into context. For tasks that genuinely require reading file contents (edits, code review, understanding logic), sub-agents are the better fit. For pure discovery tasks that reduce to counts or lists, a single script call is faster and cheaper.

Graduated Context Offloading

From LangGraph's Deep Agents SDK research into long-running agents, this three-tier cascade addresses context accumulation over time without losing access to the information.

The problem: A long-running agent that processes many files, API calls, and tool results accumulates context that grows until it hits window limits or degrades accuracy through context rot. Neither truncation (loses data) nor unlimited accumulation (loses accuracy) is correct.

The three-tier cascade:

Tier 1: Large tool outputs (threshold: 20K tokens): Offload to filesystem. Write the full output to a temp file and inject only the file path and a 10-line preview into context. The agent can request the full content if needed.

Tier 2: Accumulated tool call arguments (threshold: context approaching mid-point): Offload old tool invocations. Keep only the most recent N tool calls in full; summarize or drop arguments for older calls. Tool results are more valuable than tool call arguments for continuing the task.

Tier 3: Message history (threshold: context near limit): Lossy summarization of message history. Last resort only: this introduces the risks described in Section 11 (Progressive Summarization Risks). Apply only when Tiers 1 and 2 are exhausted.

Claude Code equivalent using a PostToolUse hook:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "python3 ~/.claude/hooks/offload-large-output.py"
      }]
    }]
  }
}

# ~/.claude/hooks/offload-large-output.py
import json, sys, tempfile, os

data = json.load(sys.stdin)
output = data.get("tool_result", {}).get("content", "")

THRESHOLD = 20_000  # characters, roughly 5K tokens

if len(output) > THRESHOLD:
    tmp = tempfile.NamedTemporaryFile(
        mode="w", suffix=".txt", delete=False,
        prefix="/tmp/claude-output-"
    )
    tmp.write(output)
    tmp.close()
    preview = "\n".join(output.splitlines()[:10])
    print(json.dumps({
        "tool_result": {
            "content": (
                f"[Output too large — saved to {tmp.name}]\n"
                f"Preview (first 10 lines):\n{preview}\n"
                f"Use: cat {tmp.name}"
            )
        }
    }))
else:
    print(json.dumps(data))

This hook transparently intercepts large bash outputs, writes them to a temp file, and injects the path with a preview. The agent sees a compact summary and knows where to find the full content if it needs it. The same pattern applies to any tool type: MCP tool results, file reads, or API responses can all be offloaded to filesystem and referenced by path.

Optical and Visual Context Compression

A distinct compression modality emerged in 2026, the first real modality shift in this discipline rather than an incremental improvement on text compression. Following DeepSeek-OCR's late-2025 demonstration that a model can decode more than 10x the token count from a small set of vision tokens, 2026 work (AgentOCR, Glyph, VIST) extends the idea to long documents: render the text as an image, pass it through a frozen vision encoder plus a trainable resampler, and hand the model compact visual tokens instead of raw text tokens. The 10x figure comes from the original DeepSeek-OCR paper under specific conditions; treat it as a compression ratio observed in that setup, not a universal multiplier.

pxpipe is the first production implementation of this pattern targeted specifically at Claude Code and the Anthropic API: a local proxy that rewrites large tool results, collapsed prior turns, and static system-prompt or tool-doc blocks into PNG images before the request leaves the machine, while leaving recent turns, model output, and sparse prose untouched. Exact-byte content (passwords, hashes, IDs) is explicitly excluded and documented as a lossy-recall risk rather than a solved problem. Full tool profile, benchmarks, and known limitations: Context Engineering Tools: pxpipe.

When it applies: large, mostly-static blocks of text your model does not need to recall verbatim (system prompts, tool documentation, old conversation turns already summarized elsewhere). It does not apply to content where exact character-level recall matters, since visual token decoding has a measurable non-zero error rate on precise strings.

Summary: Reduction Techniques by Impact

Technique	Context Reduction	Effort	Adherence Impact
Path-scoping	40-50%	Medium	+15-25%
Negative constraints	0% (reformulation)	Low	+15-25% per rule
Rule compression	20-30%	Low	+5-10%
Deduplication	10-20%	Low	+5-15%
Archive pattern	10-30%	Low	+5-10%
80/20 prioritization	0% (reordering)	Low	+10-20%
Think in Code	90%+ on exploration tasks	Low	N/A (replaces calls)
Graduated offloading	Variable (tier-dependent)	Medium	Prevents rot

The highest-leverage sequence for a project with context debt:

1. Path-scope (biggest structural win)
2. Deduplicate (removes noise)
3. Compress (sharpens remaining rules)
4. Archive (clears obsolete rules safely)
5. Reorder (prioritizes the rules that matter most)
6. Graduated offloading (for long-running or multi-step agent workflows)