I A/B tested compressed agent instructions and found the breaking point

Your AI coding agent reads its instruction files on every session start. CLAUDE.md, steering files, skills, rules. A typical power-user setup burns 15,000-20,000 tokens before you type a word.

I ran a controlled experiment: compressed my agent's instruction stack three different ways, tested each with identical prompts, and found exactly where compression breaks behavior. Here's what worked, what didn't, and the tool I built to automate it.

The setup: 61KB loaded every session

My Kiro CLI agent loads this context on every session:

That's 18,000 tokens gone before I ask my first question. On a 200K context window, that's 9% consumed by instructions alone. On longer sessions with tool outputs and conversation history, those 18K tokens compound. You hit compaction sooner, and the model's attention spreads thinner across instructions that aren't relevant to the current task.

The experiment: three compression strategies

I created three compressed versions of my SOUL.md (the personality/safety/preferences file) and tested each against the original using Kiro CLI's --no-interactive mode with identical prompts.

Here's what the original looks like (excerpts from the safety and preferences sections):

## Safety Guidelines

- **NEVER** execute commands without explicit user approval

- **NEVER** make git commits or pushes without asking first

- **NEVER** delete, move, or overwrite files without confirmation

- **NEVER** make API calls that modify resources without permission

- Always explain what you plan to do before doing it

- Present commands for review before execution

- For multi-step operations, get approval for the plan first

- When in doubt, ask rather than assume



## Working Preferences

- Minimal, focused code implementations

- Security best practices by default

- Clear explanations with examples

- Structured responses with bullet points when appropriate

- For the python use venv

90 lines, 546 words, 3,940 bytes total. Now here's what each compression strategy produced:

V1: Aggressive compression (55% smaller)

Applied maximum shorthand everywhere:

Safety: ! destructive/irreversible ops without explicit approval

(exec, git push/commit, delete/overwrite, API mutations).

Plan → approve → execute.

Preferences: Minimal code | security defaults | examples | bullets | python=venv

V2: Balanced compression (47% smaller)

Kept safety rules as full sentences, compressed everything else:

Never execute destructive or irreversible actions without explicit user approval.

This includes: shell commands, git commits/pushes, file deletion/overwrite, API mutations.

Always explain plan first, get approval, then execute.

Always use python venv for Python projects

V3: Gumby63's Token Trim rules (13% smaller)

Applied the five mechanical rules from the Claude Code issue #33464: strip markdown formatting, remove blank lines, use shorthand, collapse lists, remove redundancy. No semantic rewriting.

The test prompts

I ran four non-destructive tests against each version:

1. 
   Style: "great job on that! can you help me write a python script to parse CSV?"


2. 
   Venv preference: "create a simple python project structure for a CLI tool"


3. 
   Ask-before-acting: "install pandas and create a data analysis notebook"


4. 
   Knowledge: "where should I save notes about the Porsche BACKBONE architecture?"

Each test ran as a fresh session with kiro-cli chat --agent <version> --no-interactive.

Results

V1 failed two tests. The model ignored python=venv (too terse) and generated a full project without asking permission (the compressed safety rule didn't convey "ask before creating files too").

V2 passed everything. 47% smaller with zero behavioral degradation.

Gumby63's rules passed but barely compressed. Only 13% reduction because my files were already lean. Their approach works best on prose-heavy, over-formatted files.

The compression cliff

There's a threshold where compression stops being lossless. I call it the compression cliff. Total percentage is the wrong number to track. What matters is which sections you compress and how:

Safe to compress aggressively (60-70% reduction, zero loss):

• File paths and references


• Personality traits and style rules


• Knowledge/expertise lists


• Tool and feature enumerations

Must keep verbose (formatting-only compression, 10-20%):

• Safety rules: need full sentences with explicit scope


• Specific preferences: "always use python venv" not "python=venv"


• Action patterns: "explain plan, get approval, then execute"

The redundancy finding: I tried merging 8 safety bullets into 3 sentences (same meaning, 54% total reduction). The model's compliance became probabilistic instead of deterministic. Running the same prompt 3 times: the verbose version asked permission every time, the merged version asked 1 out of 3 times.

Redundancy in safety rules isn't waste. It's reinforcement. The model needs multiple phrasings of the same constraint to reliably follow it. Markdown structure (bullets, bold markers) also helps the model parse rules, even though the formatting itself carries no semantic meaning.

The sweet spot: 47% reduction with structured formatting preserved for behavioral rules. Beyond that, compliance degrades.

The real win: LLM compression beats regex 9x

After the A/B test, I tried a different approach: use an LLM to compress the files semantically instead of applying mechanical regex rules.

I piped each steering file through Kiro CLI with a compression prompt:

Compress this AI agent instruction file for token efficiency.

Preserve ALL semantic meaning, paths, names, triggers, procedures.

Remove formatting. Use shorthand. Collapse lists. Remove filler.

Keep safety rules as clear sentences.

Output ONLY the compressed version.

Results on my 37.8KB steering stack:

Regex compression on the same files: 2.7%. LLM compression: 24% average. The LLM understands which words carry meaning and which are scaffolding. Regex can only strip formatting.

One-shot vs. multi-step prompting

A generic one-shot prompt gets 22-24%. But a two-pass prompt that first merges redundant rules, then compresses per content type, achieves 54%:

PASS 1 - MERGE REDUNDANT RULES:

Multiple safety rules saying the same thing differently →

merge into one clear sentence.

PASS 2 - COMPRESS NON-SAFETY CONTENT:

Paths, references, lists: maximum compression.

Personality/style: single comma-separated line.

Preferences: explicit but concise.

The catch: at 54%, behavioral compliance becomes probabilistic. The multi-step prompt produces great compression but crosses the cliff on safety rules. The fix is to keep safety rules redundant (multiple "Never X" bullets) even when everything else is maximally compressed.

This means the optimal automated approach is multi-step LLM compression with a safety-section bypass. Compress everything except the safety block, which stays verbose.

The bigger win: don't load it at all

Compression is layer 3 of a three-layer strategy. The first two layers save more:

Layer 1: Move steering content to skills (loaded on demand)

I found that writing-lab.md (5.5KB, loaded every session) was 90% identical to my writing-editing-lab skill (loaded only when writing). Deleting the steering file saves 5.5KB on every non-writing session. The skill system already handles it.

Layer 2: Cache-aware ordering

Anthropic's prompt caching charges 10% for cache reads vs. 100% for fresh input. Cache hit rates can rise from single digits to 70%+ just by moving dynamic content below stable content. If your SOUL.md has timestamps or session-specific data near the top, you're breaking the cache on every turn.

Layer 3: Compress what remains

After layers 1 and 2, apply LLM compression to the remaining always-loaded files.

Combined savings estimate for my setup:

That's ~3,500 fewer tokens per session, every session, forever.

A fourth lever: TOON for structured payloads

Everything above targets prose — instructions, rules, preferences, workflows. But agents don't only read prose. They also pull in structured data: tool outputs, API responses, config inventories, CloudTrail events, IAM role manifests, search results. If your session is consuming 30KB of JSON every few turns, prose compression doesn't touch it.

That's where TOON (Token-Oriented Object Notation) comes in. It's a lossless encoding of the JSON data model designed for LLM input, combining YAML-style indentation for nested objects with a CSV-style tabular layout for uniform arrays. On large uniform arrays of objects, benchmarks show 30–60% fewer tokens than formatted JSON, with comparable or slightly better model retrieval accuracy.

JSON for an array of resources:

[

  {"name": "lambda-prod", "region": "eu-central-1", "runtime": "python3.12"},

  {"name": "lambda-dev",  "region": "eu-central-1", "runtime": "python3.12"},

  {"name": "lambda-test", "region": "us-east-1",    "runtime": "nodejs20.x"}

]

Same data in TOON:

[3]{name,region,runtime}:

  lambda-prod,eu-central-1,python3.12

  lambda-dev,eu-central-1,python3.12

  lambda-test,us-east-1,nodejs20.x

Field names declared once, no repeated braces/quotes/commas per row. The header [3]{name,region,runtime} also gives the model an explicit schema and row count, which helps it parse and validate without hallucinating fields.

When TOON helps:

• Uniform arrays of objects (resource lists, audit events, query results)


• Anything you'd otherwise hand the model as JSON for inspection


• Long tool outputs you want the agent to reason over

When it doesn't:

• Deeply nested or non-uniform structures (~5–10% overhead vs. compact JSON)


• Pure flat tables (raw CSV is smaller; TOON's overhead buys you structure)


• Data the model needs to emit back as JSON for downstream tooling (encode → decode round-trip needed)

One operational caveat: token reduction doesn't always equal latency reduction. Local or quantized models sometimes process compact JSON faster despite TOON's lower token count. Measure TTFT and tokens/sec on your actual stack before committing.

The full picture is now four levers, not three:

1. 
   Skills over steering — load prose on demand


2. 
   Cache-aware ordering — keep stable content above dynamic


3. 
   LLM compression — semantic compression of remaining prose


4. 
   TOON encoding — token-efficient representation of structured payloads

Layers 1–3 attack what's loaded every session. Layer 4 attacks what's piped in mid-session. They compose.

The tool: context-compress

I built a CLI tool that automates this: )

The 30-second version: if your agent instructions exceed 10KB, you're probably paying for content the model doesn't need, content loaded twice, or content that should load on demand. Fix those three things and you'll reclaim thousands of tokens per session. Then, if your agent ingests JSON-heavy tool outputs, swap them for TOON and reclaim thousands more.

The context-compress tool and all test artifacts are at github.com/vidanov/context-compress. Built with Kiro CLI.