Compressed CLAUDE.md Rules Beat Verbose Instructions and Caveman Encoding (15,120 Benchmarks)

Should you write detailed CLAUDE.md instructions or compress them down to key phrases? The conventional wisdom says “be clear and explicit.” The Brussee CLAUDE.md toolkit says “compress everything, remove vowels, abbreviate ruthlessly.” What does the data say?

I ran 15,120 benchmarks to test seven compression strategies ranging from verbose instructions to ultra-compressed caveman encoding. The winner is structured compression at around 80 tokens per section. The loser is caveman-style compression, which barely beats having no instructions at all. The compression curve is non-linear, and token savings don’t translate to quality improvements once you sacrifice readability.

This is the twenty-third experiment in our benchmark series, and it’s particularly relevant to the targeted constraints experiment, which showed that focused, specific instructions beat generic advice. Both experiments point to the same conclusion: structure and precision matter more than volume.

Experiment Design

I tested seven CLAUDE.md variants with different compression strategies:

Each variant was run across:

• 3 models: Haiku, Sonnet, Opus
• 48 tasks: 12 per language (Python, Go, TypeScript, Rust)
• 15 repetitions per model-task-variant combination

That’s 7 variants × 3 models × 48 tasks × 15 reps = 15,120 runs.

The Scoreboard

Executive summary: overall performance across all tested variants.

Here are the overall results:

Compressed-rules wins by 3.36 points over bare and beats verbose-rules by 1.2 points. The caveman variants barely outperform having no instructions at all.

The Compression Sweet Spot

The data reveals a non-linear compression curve:

The curve looks like this:

• 0 tokens (bare): 70.36
• ~25-40 tokens (caveman): 70.59-70.67 (+0.23 to +0.31)
• ~50 tokens (terse-generic): 72.65 (+2.29)
• ~80 tokens (compressed-rules): 73.72 (+3.36) ← PEAK
• ~200 tokens (verbose-rules): 72.52 (+2.16)

There’s a jump from caveman to terse-generic (+2 points), another jump to compressed-rules (+1 point), and then a slight drop to verbose-rules. The 80-token sweet spot is real.

Caveman Encoding Backfires

The Brussee CLAUDE.md toolkit recommends aggressive compression: “wrt cln cd”, “hndl errs”, “doc fncs”. The philosophy is that tokens are scarce and the model can infer meaning from context. The data says otherwise. Caveman encoding gains you nothing in quality and costs you maintainability.

The worst performer is caveman-full at 70.59, which is barely distinguishable from bare at 70.36. If you’re going to write instructions, make them readable.

Model-Specific Results

Radar charts: multi-dimensional performance comparison.

Heatmap: detailed performance breakdown across dimensions.

Different models have different compression preferences:

The pattern is clear:

• Haiku (low-tier model): verbose-rules wins (64.40). The smallest model benefits from explicit, detailed instructions. Compression hurts it.
• Sonnet (mid-tier model): compressed-rules wins clearly (76.07). This is where the compression sweet spot shines. Structured, concise instructions outperform both verbose and caveman.
• Opus (high-tier model): code-adapted wins (81.72). The most capable model benefits from preserving code examples while compressing prose. It can infer context from technical artifacts better than from natural language.

If you’re optimizing for Haiku, keep instructions verbose. If you’re optimizing for Sonnet, compress to structured rules. If you’re optimizing for Opus, preserve code examples and compress the prose around them.

The Code-Adapted Strategy

Code-adapted is the consistent runner-up at 73.08 overall, and it wins on Opus at 81.72. What is it?

Code-adapted means: compress prose instructions, but preserve code examples and technical standards verbatim. Don’t abbreviate function signatures, command-line flags, or error-handling patterns. Those are information-dense and hard to abbreviate without losing precision.

if err != nil {
    return fmt.Errorf("operation failed: %w", err)
}

if err!=nil{rtrn fmt.Errorf("op fail:%w",err)}

func TestParseInput(t *testing.T) {
    t.Run("empty string", func(t *testing.T) { ... })
    t.Run("invalid format", func(t *testing.T) { ... })
}

The code-adapted strategy works because code examples are unambiguous. “if err != nil” is clearer than any prose explanation of error handling. The model can pattern-match against concrete examples more reliably than it can parse natural language descriptions.

Language-Specific Breakdown

Do different languages benefit from different compression strategies?

Rust is the opposite: bare (70.05) vs compressed-rules (70.43) is only +0.38. Rust tasks are hard, and the model struggles regardless of instruction quality. Code-adapted actually makes Rust worse (68.60), which suggests that Rust examples in CLAUDE.md files confuse the model more than they help.

Practical Implications

Token efficiency: quality vs cost tradeoff.

Statistical significance analysis.

Limitations

• Token counts are approximate. We estimated token counts using whitespace heuristics rather than exact tokenization. The ~80 token sweet spot could be off by 10-20 tokens in either direction.
• Claude models only. Other model families (GPT-4, Gemini, etc.) may have different compression preferences. But the pattern across Haiku, Sonnet, and Opus suggests this is a general property of transformer-based LLMs.
• Single-file tasks. These are isolated coding tasks. CLAUDE.md instructions for multi-file projects, architectural standards, or deployment procedures may have different optimal compression levels.
• No interaction with other strategies tested. We didn’t test compression combined with chain-of-thought, personas, or targeted constraints. Interaction effects could exist.
• Compression strategies could be varied further. We tested seven variants, but there’s a large space of possible compression approaches. Structured bullets, numbered lists, markdown formatting, and other organizational strategies could perform differently.

Try It Yourself

The output compression experiment configuration and all data are open source:

pip install claude-benchmark

# Run the output compression experiment
claude-benchmark experiment run experiments/output-compression.toml

# Generate the report
claude-benchmark report

# See the results
open results/*/report.html

You can also define your own compression variants in the experiment TOML and test them against your specific codebase conventions. If you find a compression strategy that beats compressed-rules, I’d like to see the data.

Full experiment configuration: experiments/output-compression.toml

For the complete picture of what works in CLAUDE.md optimization, see the init vs best-practices experiment and the targeted constraints experiment. For the synthesis of all benchmark results, see the capstone-v2 experiment.